Circle USYC 백서 전문

| Code | Meaning | Treatment | | - | - | - | | `1143` | Checkout session not found—the supplied session ID doesn't exist. | Malformed | | `1144` | Checkout session is already in a completed state and cannot be extended. | State conflict | For asynchronous failure events on payment intents and payments, see [Webhook notifications](/circle-mint/references/webhook-notifications). ## Stablecoin Payouts errors Stablecoin Payouts errors have two sources. Synchronous validation covers Travel Rule fields and Address Book entity validation. After submission, the payout entity itself can transition to `failed` with an `errorCode` that describes why. ### Synchronous validation For full Travel Rule context, see [Travel rule compliance](/circle-mint/references/travel-rule-compliance). | Code | Meaning | Treatment | | - | - | - | | `5020` | `purposeOfTransfer` field is missing or invalid on a `CIRCLE_SG`-booked crypto payout. | Malformed | | `2024` | Address Book identity is missing for this entity. | Malformed | | `2025` | Address Book ownership is missing for this entity. | Malformed | | `2026` | Address Book VASP ID is missing for this entity. | Malformed | | `2027` | Address Book ownership type is invalid for this entity. | Malformed | | `2028` | Address Book custody type is invalid for this entity. | Malformed | | `2029` | Address Book custody is missing for this entity. | Malformed | | `2030` | Address Book VASP ID is invalid for this entity. | Malformed | | `2031` | Address Book identity type is invalid—must be `individual` or `business`. | Malformed | | `2032` | Address Book identity first name is missing for an individual identity. | Malformed | | `2033` | Address Book identity last name is missing for an individual identity. | Malformed | | `2034` | Address Book identity business name is missing for a business identity. | Malformed | | `2035` | Address Book VASP ID is not allowed—VASP ID must be omitted for self-hosted custody. | Malformed | | `2036` | Identity is not allowed in Address Book `PATCH` requests. | Malformed | | `2037` | Ownership is not allowed in Address Book `PATCH` requests. | Malformed | ### Asynchronous entity errors | `errorCode` | Meaning | | - | - | | `insufficient_funds` | Source wallet doesn't have enough USDC for the payout. | | `transaction_denied` | Payout was denied by Circle Risk Service—see `riskEvaluation` for the reason. | | `transaction_failed` | Payout failed due to an unknown reason. | | `transaction_returned` | Payout was returned by the receiving network. | | `fiat_account_limit_exceeded` | The fiat account limit was exceeded. | <Note> When `riskEvaluation.reason` is `3220`, the denial is a Travel Rule violation. Review your originator identities, beneficiary identity, VASP ID, and `purposeOfTransfer`, then resubmit with a new `idempotencyKey`. See [Travel Rule Compliance](/circle-mint/references/travel-rule-compliance). For the full list of `riskEvaluation.reason` values, see [Risk evaluation reason codes](#risk-evaluation-reason-codes). </Note> ## Credit errors The Credit API's draw, fee, and repayment endpoints surface validation failures via a top-level `validationErrors` array on the credit line. When `validationErrors` is non-empty, draw and repayment endpoints return HTTP 400 until the listed conditions clear. | Value | Meaning | Treatment | | - | - | - | | `INSUFFICIENT_BALANCE` | The credit line's Circle Mint wallet balance is below `minBalance`, blocking new draws. | State conflict | | `PENDING_FEES` | An unpaid fee is blocking new draws. | State conflict | | `OVERDUE_TRANSFERS` | At least one disbursed transfer is past its due date. | State conflict | Calling `POST /v1/credit/cryptoRepayment` against a Settlement Advance credit line returns HTTP 400—crypto repayment is only supported on Line of Credit lines. See the [Credit API concept](/circle-mint/concepts/credit-api) for product differences. ## Institutional Distribution errors These responses surface when you create or manage external entities through the Institutional API. | HTTP | Meaning | Treatment | | - | - | - | | `400` | Missing or invalid fields on external entity creation. | Malformed | | `401` | The API key doesn't have the Institutional Distribution permission. | State conflict: contact Circle to enable the entitlement. | | `409` | An external entity with the supplied `businessUniqueIdentifier` and `identifierIssuingCountryCode` already exists. Re-fetch via `GET /v1/externalEntities`. | State conflict | ## Custody balance errors These codes apply to daily user balance reporting for custody accounts. | Code | Meaning | Treatment | | - | - | - | | `500000` | Unsupported currency for reporting daily user balance—must be USDC or EURC. | Malformed | | `500001` | Custody balance `asOfDate` is too far from today's date. | Malformed | | `500002` | Custody balance cannot be less than zero. | Malformed | | `500003` | Local custody balance can't be greater than total custody balance. | Malformed | | `500004` | Idempotency key can't be reused across different requests. | State conflict | | `500005` | A custody balance report already exists for the provided date and currency. Contact customer care for edits. | State conflict | ## Transfer entity errors These `errorCode` values appear on a transfer resource after it transitions to `failed`. | `errorCode` | Meaning | Treatment | | - | - | - | | `transfer_failed` | Transfer could not be completed. | Transient: investigate `riskEvaluation` and network conditions. | | `transfer_denied` | Transfer was denied by Circle Risk Service. | Compliance: review and resubmit with a new `idempotencyKey`. | | `blockchain_error` | Onchain failure prevented the transfer from settling. | Transient: retry once network is healthy. | | `insufficient_funds` | Source wallet doesn't have enough USDC for the transfer. | Insufficient funds | # Create a notification subscription Source: https://developers.circle.com/api-reference/circle-mint/general/create-subscription openapi/general.yaml post /v1/notifications/subscriptions Subscribe to receiving notifications at a given endpoint. The endpoint should be able to handle AWS SNS subscription requests. For more details see https://docs.aws.amazon.com/mobile/sdkforxamarin/developerguide/sns-send-http.html. Note, the sandbox environment allows a maximum of 3 active subscriptions; otherwise, this is limited to 1 active subscription and subsequent create requests will be rejected with a Limit Exceeded error. # Remove a notification subscription Source: https://developers.circle.com/api-reference/circle-mint/general/delete-subscription openapi/general.yaml delete /v1/notifications/subscriptions/{id} To remove a subscription, all its subscription requests' statuses must be either 'confirmed', 'deleted' or a combination of those. A subscription with at least one 'pending' subscription request cannot be removed. # Get configuration info Source: https://developers.circle.com/api-reference/circle-mint/general/get-account-config openapi/general.yaml get /v1/configuration Retrieves general configuration information. # List all stablecoins Source: https://developers.circle.com/api-reference/circle-mint/general/list-stablecoins openapi/general.yaml get /v1/stablecoins Retrieves total circulating supply for supported stablecoins across all chains. This endpoint is rate limited to one call per minute (based on IP). # List all notification subscriptions Source: https://developers.circle.com/api-reference/circle-mint/general/list-subscriptions openapi/general.yaml get /v1/notifications/subscriptions Retrieve a list of existing notification subscriptions with details. # Ping Source: https://developers.circle.com/api-reference/circle-mint/general/ping openapi/general.yaml get /ping Checks that the service is running. # Create an external entity Source: https://developers.circle.com/api-reference/circle-mint/institutional/create-external-entity openapi/institutional.yaml post /v1/externalEntities Creates an external entity for the institutional account. A new external entity is created with a `complianceState` of `PENDING` and has no `walletId`. Circle assigns the wallet only after compliance screening accepts the entity, so the field is omitted from the response while the entity is pending. Use `GET /v1/externalEntities` to retrieve the `walletId` once the entity is `ACCEPTED`. This endpoint is idempotent on `businessUniqueIdentifier` and `identifierIssuingCountryCode`. Creating an entity that already exists returns that entity in its current state, so a repeat request for an already-accepted entity returns `complianceState: ACCEPTED` together with its `walletId`. To access the Core API for Institutions, contact your Circle account representative. # Get all external entities Source: https://developers.circle.com/api-reference/circle-mint/institutional/get-all-external-entities openapi/institutional.yaml get /v1/externalEntities Returns all external entities for the institutional account. To access the Core API for Institutions, contact your Circle account representative. Note that the `businessUniqueIdentifier` and `identifierIssuingCountryCode` must both be provided, or not at all. Only providing one will result in an error. # Get an external entity by wallet ID Source: https://developers.circle.com/api-reference/circle-mint/institutional/get-external-entity-by-wallet-id openapi/institutional.yaml get /v1/externalEntities/{walletId} Returns an external entity by wallet ID. To access the Core API for Institutions, contact your Circle account representative. # Retrieve data for all visible sections Source: https://developers.circle.com/api-reference/circle-mint/onboarding/bulk-get-data openapi/partner-openapi.yaml get /v1/onboarding/partner/applications/{applicationId}/data Returns all visible section data keyed by section name alongside section statuses. The data object is round-trip compatible with PATCH /{applicationId}/data. Sections that do not contribute to application progress are excluded. # Save data for multiple sections in a single request Source: https://developers.circle.com/api-reference/circle-mint/onboarding/bulk-save openapi/partner-openapi.yaml patch /v1/onboarding/partner/applications/{applicationId}/data Accepts a JSON object keyed by section name. Each value is the same payload shape as PUT /sections/{sectionName}. Validation is atomic: all sections are validated before any data is saved, and if any section fails validation the entire request is rejected. Saves are sequential: after validation passes, sections are persisted one at a time. Array sections use upsert semantics: items with refId update existing entities, items without refId create new entities. Existing entities not included are preserved. The response data field is an object keyed by section name containing the saved data for each section. # Cancel an application Source: https://developers.circle.com/api-reference/circle-mint/onboarding/cancel-application openapi/partner-openapi.yaml delete /v1/onboarding/partner/applications/{applicationId} Cancels a draft ONBOARDING_APPLICATION. Other operation types are not currently cancellable. # Add a comment to an RFI Source: https://developers.circle.com/api-reference/circle-mint/onboarding/create-comment openapi/partner-openapi.yaml post /v1/onboarding/partner/applications/{applicationId}/rfis/{rfiId}/comments # Delete a comment on an RFI Source: https://developers.circle.com/api-reference/circle-mint/onboarding/delete-comment openapi/partner-openapi.yaml delete /v1/onboarding/partner/applications/{applicationId}/rfis/{rfiId}/comments/{commentId} # Delete a document Source: https://developers.circle.com/api-reference/circle-mint/onboarding/delete-document openapi/partner-openapi.yaml delete /v1/onboarding/partner/applications/{applicationId}/documents/{documentId} # Download a document Source: https://developers.circle.com/api-reference/circle-mint/onboarding/download-document openapi/partner-openapi.yaml get /v1/onboarding/partner/applications/{applicationId}/documents/{documentId} # Retrieve an application by ID Source: https://developers.circle.com/api-reference/circle-mint/onboarding/get-application openapi/partner-openapi.yaml get /v1/onboarding/partner/applications/{applicationId} # Get the JSON Schema (draft 2020-12) for an application's template Source: https://developers.circle.com/api-reference/circle-mint/onboarding/get-application-schema openapi/partner-openapi.yaml get /v1/onboarding/partner/applications/{applicationId}/schema # List active certifications for an application Source: https://developers.circle.com/api-reference/circle-mint/onboarding/get-certifications openapi/partner-openapi.yaml get /v1/onboarding/partner/applications/{applicationId}/certifications Returns the active certifications the end user must agree to for this application, including the HTML content, certification id, and metadata. Pass the returned ids back on POST /{applicationId}/submit as certificationIds to explicitly acknowledge them, or omit certificationIds to let the service auto-resolve the active set. # Get RFI detail with comment history Source: https://developers.circle.com/api-reference/circle-mint/onboarding/get-rfi openapi/partner-openapi.yaml get /v1/onboarding/partner/applications/{applicationId}/rfis/{rfiId} # Retrieve section data for an application Source: https://developers.circle.com/api-reference/circle-mint/onboarding/get-section openapi/partner-openapi.yaml get /v1/onboarding/partner/applications/{applicationId}/sections/{sectionName} Returns field data for the specified section. When typedValues=true, array/object/number field values are emitted as native JSON nodes instead of strings. # List applications for the authenticated partner Source: https://developers.circle.com/api-reference/circle-mint/onboarding/list-applications openapi/partner-openapi.yaml get /v1/onboarding/partner/applications # List documents for an application Source: https://developers.circle.com/api-reference/circle-mint/onboarding/list-documents openapi/partner-openapi.yaml get /v1/onboarding/partner/applications/{applicationId}/documents # List RFI bundles for an application Source: https://developers.circle.com/api-reference/circle-mint/onboarding/list-rfis openapi/partner-openapi.yaml get /v1/onboarding/partner/applications/{applicationId}/rfis # List sections for an application Source: https://developers.circle.com/api-reference/circle-mint/onboarding/list-sections openapi/partner-openapi.yaml get /v1/onboarding/partner/applications/{applicationId}/sections Returns visible sections with statuses. When includeData=true, each entry also includes the section's current field data — useful for rendering a progress view alongside prefilled form data. When typedValues=true (only meaningful with includeData=true), array/object/number field values are emitted as native JSON nodes instead of strings. # Remove an entity from an array section Source: https://developers.circle.com/api-reference/circle-mint/onboarding/remove-entity openapi/partner-openapi.yaml delete /v1/onboarding/partner/applications/{applicationId}/sections/{sectionName}/{refId} # Save section data for an application Source: https://developers.circle.com/api-reference/circle-mint/onboarding/save-section openapi/partner-openapi.yaml put /v1/onboarding/partner/applications/{applicationId}/sections/{sectionName} Saves field data for a section. The request body is a JSON object whose shape is defined by the section's JSON Schema (retrieve it via GET /{applicationId}/schema). For MULTIPLE array sections, maxItems is enforced and over-limit payloads return 422. # Submit an application Source: https://developers.circle.com/api-reference/circle-mint/onboarding/submit-application openapi/partner-openapi.yaml post /v1/onboarding/partner/applications/{applicationId}/submit # Update a comment on an RFI Source: https://developers.circle.com/api-reference/circle-mint/onboarding/update-comment openapi/partner-openapi.yaml put /v1/onboarding/partner/applications/{applicationId}/rfis/{rfiId}/comments/{commentId} # Submit field data in response to an UPDATE_FIELD or NEW_FIELD RFI Source: https://developers.circle.com/api-reference/circle-mint/onboarding/update-rfidata openapi/partner-openapi.yaml patch /v1/onboarding/partner/applications/{applicationId}/rfis/{rfiId} # Upload a document for an application Source: https://developers.circle.com/api-reference/circle-mint/onboarding/upload-document openapi/partner-openapi.yaml post /v1/onboarding/partner/applications/{applicationId}/documents # Create a crypto payment customer Source: https://developers.circle.com/api-reference/circle-mint/payments/create-payment-customer openapi/payments.yaml post /v1/payments/customers Creates a Travel Rule customer profile for crypto payment attribution. These APIs are available to eligible Circle Singapore (`CIRCLE_SG`) merchants. The customer starts in `pending` status while screening completes. A customer must be `approved` before a customer wallet can be created. # Create a crypto payment customer wallet Source: https://developers.circle.com/api-reference/circle-mint/payments/create-payment-customer-wallet openapi/payments.yaml post /v1/payments/customers/{customerId}/wallets Registers a hosted customer wallet for an approved Travel Rule customer. The resulting customer wallet ID can be supplied as `customerWalletId` when creating a transient payment intent. Customer wallet creation is available to eligible Circle Singapore (`CIRCLE_SG`) merchants. The customer must be `approved`. # Create a payment intent Source: https://developers.circle.com/api-reference/circle-mint/payments/create-payment-intent openapi/payments.yaml post /v1/paymentIntents Create a continuous (default) or transient payment intent. Continuous payment intents are created by default. To create a transient payment intent, the `type` field must be explicitly set to `transient`. `purposeOfTransfer` is conditionally required: it must be supplied when the entity's legal entity is Circle SG (`CIRCLE_SG`), Circle Inc (`CIRCLE_INC`) with Managed Payments enabled, or Circle SAS (`CIRCLE_FR`); it is optional for other legal entities. `PMT006` is not allowed. Eligible Circle SG (`CIRCLE_SG`) merchants can link a transient payment intent to a Travel Rule customer wallet by supplying `customerWalletId`. # Create a crypto payment refund address Source: https://developers.circle.com/api-reference/circle-mint/payments/create-payment-refund-address openapi/payments.yaml post /v1/payments/refundAddresses Creates a refund address-book entry that can be used as `destination.addressBookId` when refunding a crypto payment intent. This endpoint is used for Circle Singapore (`CIRCLE_SG`) refund flow 2, where the refund goes to a different address while reusing the original payment's Travel Rule originator PII. Provide the original `paymentId` and a hosted VASP in `ownership.custody.vaspId`; the supplied VASP ID must match the VASP associated with the original payment sender. Do not provide recipient `identity` in the request. Identity is derived from the original payment's Travel Rule originator PII. # Expire a payment intent Source: https://developers.circle.com/api-reference/circle-mint/payments/expire-payment-intent openapi/payments.yaml post /v1/paymentIntents/{id}/expire # Get a payment Source: https://developers.circle.com/api-reference/circle-mint/payments/get-payment openapi/payments.yaml get /v1/payments/{id} # Get a crypto payment customer Source: https://developers.circle.com/api-reference/circle-mint/payments/get-payment-customer openapi/payments.yaml get /v1/payments/customers/{id} Returns a Travel Rule customer, including customer details, for eligible Circle Singapore (`CIRCLE_SG`) merchants. # Get a crypto payment customer wallet Source: https://developers.