Circle USYC 백서 전문

MENT_MISSING_BLOCKCHAIN_ADDRESS` | The payment is missing the sender blockchain address. **Resolution:** Make sure you [create the payment](/api-reference/cpn/cpn-platform/create-payment) with `blockchain` and `senderAddress`. | | `400` | `290340` | `INSUFFICIENT_ALLOWANCE_TO_PERMIT2` | The ERC-20 allowance granted to the `Permit2` contract is insufficient to cover the total required token amount for the payment, including both the payment amount and associated fees. **Resolution:** With your sender wallet, approve the `Permit2` contract to spend the required amount of USDC for the payment. | | `400` | `290341` | `PERMIT2_NONCE_ALREADY_USED` | The `Permit2` nonce included in the typed data for the sender has already been used. **Resolution:** Create a new transaction for the same payment with the same sender address, then sign and submit it. | | `400` | `290349` | `BLOCKCHAIN_UNSUPPORTED_FOR_V1` | The blockchain is not supported for Transactions V1. For example, Arc supports Transactions V2 only. **Resolution:** Resubmit the quote or transaction request with `transactionVersion=VERSION_2`. See [supported blockchains](/cpn/references/blockchains/supported-blockchains) for the V1/V2 support matrix. | | `400` | `290352` | `ONCHAIN_SETTLEMENT_CUTOFF_TIME_EXCEEDED` | The signed transaction was submitted after the onchain settlement cutoff. The cutoff time is the payment's expiry time minus a blockchain-specific buffer (for example, \~19 minutes for Ethereum, \~8 minutes for Polygon PoS, \~25 seconds for Solana, and \~0.5 seconds for Arc). **Resolution:** Request a new quote, create a new payment, and submit the signed transaction before the cutoff time. | ## RFI | Status code | Error code | Detail | Description | | - | - | - | - | | `400` | `290400` | `RFI_EXPIRED` | The RFI has expired; you can't submit data to an expired resource. **Resolution:** Create a new payment for the user and complete a new RFI. | | `400` | `290401` | `RFI_NOT_SUBMITTABLE` | Requirement data submissions are limited to RFIs with the `INFORMATION_REQUIRED` status. Submission for an RFI in any other status results in this error code. | | `400` | `290402` | `RFI_FILE_NOT_FOUND` | The uploaded filename does not match the file input name specified in the request for information. **Resolution:** Ensure the correct files are uploaded and that the file names exactly match those specified in the RFI. | | `400` | `290403` | `RFI_FILE_INVALID_CONTENT` | The server was unable to read the content of the uploaded file. **Resolution:** Ensure the uploaded file contains content in a compatible format that can be processed by the CPN server. | | `400` | `290404` | `RFI_FILE_CONTENT_TOO_LARGE` | The size of the uploaded file exceeds the maximum allowed size. **Resolution:** Ensure that the uploaded file does not exceed the 10 MB. | | `400` | `290405` | `RFI_UNSUPPORTED_FILE_TYPE` | The MIME type of the uploaded file is not supported. **Resolution:** Ensure that the uploaded file has a MIME type accepted by the file upload endpoint. | ## Encryption | Status code | Error code | Detail | Description | | - | - | - | - | | `400` | `290500` | `ENCRYPTED_BLOB_DECRYPTION_ERROR` | The decryption process failed. **Resolution:** Ensure the correct public key was used to encrypt the payload. | | `400` | `290502` | `INVALID_JWE_FORMAT` | The JWE compact payload is not formatted correctly or is missing required components. **Resolution:** Ensure you're using a standard library for encrypting the payload and sending in the JWE compact format. | | `400` | `290503` | `UNSUPPORTED_ENCRYPTION_ALGORITHM` | The JWE compact payload was not encrypted with a supported algorithm. **Resolution:** Ensure your encryption function is correctly implementing the appropriate algorithms and resubmit. | ## Support ticket | Status code | Error code | Detail | Description | | - | - | - | - | | `400` | `290600` | `TICKET_REFERENCE_REQUIRED` | Ticket reference ID is required for escalation. | | `404` | `290601` | `ORIGINAL_TICKET_NOT_FOUND` | The original ticket was not found with the provided reference ID. | | `400` | `290602` | `INVALID_SUPPORT_TICKET_ISSUE_TYPE` | Issue type is not allowed for this origin. **Resolution:** Ensure the correct issue type is provided. | | `404` | `290603` | `PAYMENT_NOT_FOUND_FOR_TICKET` | The payment ID provided was not found. | | `500` | `290604` | `SUPPORT_TICKET_SALESFORCE_CREATION_FAILED` | Failed to create a ticket in Circle Salesforce. **Resolution:** Try again at a later time. | | `500` | `290605` | `SUPPORT_TICKET_BFI_CREATION_FAILED` | Failed to create a BFI support ticket. **Resolution:** Try again at a later time. | # Archive an account Source: https://developers.circle.com/api-reference/cpn/managed-payments/accounts/archive-account openapi/accounts.yaml post /v1/accounts/{accountId}/archive Archives a subledger account. Only subledger-type accounts (those created via `POST /v1/accounts`) may be archived, and the account must have a zero balance. While archived, mutating operations on the account are blocked: transfers into or out of the account, new deposit-address generation, fiat withdrawals, payment-intent creation, and fetching wire instructions are all rejected. Read endpoints (e.g. `GET /v1/accounts/{accountId}`, `GET /v1/accounts/deposits`) continue to work. An archived account is excluded from the default `GET /v1/accounts` listing; pass `status=archived` (or include `archived` in a multi-value `status` filter) to retrieve it. Archiving is idempotent: archiving an already-archived account succeeds. An incoming deposit to a pre-existing deposit address or wire instruction on the archived account will auto-unarchive it (status returns to `active`). # Create an account Source: https://developers.circle.com/api-reference/cpn/managed-payments/accounts/create-account openapi/accounts.yaml post /v1/accounts Creates a new account. This account can be used to create accounts for Mint, or intermediary accounts for a Managed Payments customer. For Managed Payments, the account created represents the end customer that will settle stablecoin payments by the customer. That end customer can be either a business or an individual (retail) end customer. Routing for this endpoint is body based. Requests that include `businessPii`, `individualPii`, or `endCustomerType` are routed to the Managed Payments intermediary account creation flow, while requests that include none of those fields are routed to the standard account creation flow. For Managed Payments, `endCustomerType` selects which PII block is required: - `business`, or omitted, requires `businessPii` and rejects `individualPii`. - `individual` requires `individualPii` and rejects `businessPii`. Both flows require an explicit `type` and `purpose` in the request body: - Standard (digital asset / Mint) accounts use `purpose` `custody` and `type` `first_party` or `third_party`. When `clientEntityId` is omitted the account is owned by the caller and `type` must be `first_party`; when `clientEntityId` is provided the account is owned by a sub-entity and `type` must be `third_party`. - Managed Payments intermediary accounts use `type` `first_party` and `purpose` `payments`. # Get an account Source: https://developers.circle.com/api-reference/cpn/managed-payments/accounts/get-account openapi/accounts.yaml get /v1/accounts/{accountId} Retrieves a single account by `accountId`. # List all accounts Source: https://developers.circle.com/api-reference/cpn/managed-payments/accounts/list-accounts openapi/accounts.yaml get /v1/accounts Retrieves the accounts available to the calling entity. # Create a recipient Source: https://developers.circle.com/api-reference/cpn/managed-payments/address-book/create-address-book-recipient openapi/payouts.yaml post /v1/addressBook/recipients Creates an address book recipient. Required fields depend on your Circle entity; use the request body options that match your integration. For Singapore (CIRCLE_SG) customers creating a self-hosted (`ownership.custody.type` = `self_hosted`) entry, `metadata.email` is required and the beneficiary PII object matching `identity.type` (`identity.individual` or `identity.business`) is required. The two PII objects are mutually exclusive. For non-regulated jurisdictions the PII objects are accepted if provided but not required. Validation failures can return error codes in the `2024`–`2038` range (for example `2024` when `identity` is required but missing, `2025` when `ownership` is required but missing, `2038` when `metadata.email` is missing for a self-hosted entry), as well as the PII-missing errors `ADDRESS_BOOK_INDIVIDUAL_PII_MISSING` and `ADDRESS_BOOK_BUSINESS_PII_MISSING`. # Delete a recipient Source: https://developers.circle.com/api-reference/cpn/managed-payments/address-book/delete-address-book-recipient openapi/payouts.yaml delete /v1/addressBook/recipients/{id} # Get a recipient Source: https://developers.circle.com/api-reference/cpn/managed-payments/address-book/get-address-book-recipient openapi/payouts.yaml get /v1/addressBook/recipients/{id} # List all recipients Source: https://developers.circle.com/api-reference/cpn/managed-payments/address-book/list-address-book-recipients openapi/payouts.yaml get /v1/addressBook/recipients # Modify a recipient Source: https://developers.circle.com/api-reference/cpn/managed-payments/address-book/modify-address-book-recipient openapi/payouts.yaml patch /v1/addressBook/recipients/{id} Updates address book recipient metadata. # Borrow against line of credit Source: https://developers.circle.com/api-reference/cpn/managed-payments/credit/create-managed-payments-credit-transfer openapi/managed-payments.yaml post /v1/managedPayments/credit/lines/{lineId}/transfers Initiates a transfer (borrowing) against the line of credit. # Get credit line details Source: https://developers.circle.com/api-reference/cpn/managed-payments/credit/get-managed-payments-credit-line openapi/managed-payments.yaml get /v1/managedPayments/credit/lines Retrieves the details of the Managed Payments credit line. # Get a credit transfer Source: https://developers.circle.com/api-reference/cpn/managed-payments/credit/get-managed-payments-credit-transfer openapi/managed-payments.yaml get /v1/managedPayments/credit/lines/{lineId}/transfers/{transferId} Returns detailed information about a specific credit transfer. Fields `outstanding`, `dueDate`, and `disbursedDate` are present when the transfer status is `disbursed`, `paid`, or `past_due`. Field `paidDate` is present only when status is `paid`. # Get repayment wire instructions Source: https://developers.circle.com/api-reference/cpn/managed-payments/credit/get-managed-payments-credit-wire-instructions openapi/managed-payments.yaml get /v1/managedPayments/credit/lines/{lineId}/wireInstructions Fetches the necessary wire transfer instructions for repaying funds borrowed against the line of credit. # List credit transfers Source: https://developers.circle.com/api-reference/cpn/managed-payments/credit/list-managed-payments-credit-transfers openapi/managed-payments.yaml get /v1/managedPayments/credit/lines/{lineId}/transfers Returns a list of credit transfers for the specified credit line. Filterable by status and date range. # Get an account bank deposit Source: https://developers.circle.com/api-reference/cpn/managed-payments/deposits/get-account-deposit openapi/accounts.yaml get /v1/accounts/deposits/{id} Returns a bank deposit by ID. # List all account bank deposits Source: https://developers.circle.com/api-reference/cpn/managed-payments/deposits/list-account-deposits openapi/accounts.yaml get /v1/accounts/deposits Searches for bank deposits sent to accounts. If the date parameters are omitted, returns the most recent deposits. This endpoint returns up to 50 deposits in descending chronological order or pageSize, if provided. # Create a payment intent Source: https://developers.circle.com/api-reference/cpn/managed-payments/payment-intents/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`. # Expire a payment intent Source: https://developers.circle.com/api-reference/cpn/managed-payments/payment-intents/expire-payment-intent openapi/payments.yaml post /v1/paymentIntents/{id}/expire # Get a payment intent Source: https://developers.circle.com/api-reference/cpn/managed-payments/payment-intents/get-payment-intent openapi/payments.yaml get /v1/paymentIntents/{id} # List all payment intents Source: https://developers.circle.com/api-reference/cpn/managed-payments/payment-intents/list-payment-intents openapi/payments.yaml get /v1/paymentIntents # Refund a payment intent Source: https://developers.circle.com/api-reference/cpn/managed-payments/payment-intents/refund-payment-intent openapi/payments.yaml post /v1/paymentIntents/{id}/refund # Get a payment Source: https://developers.circle.com/api-reference/cpn/managed-payments/payments/get-payment openapi/payments.yaml get /v1/payments/{id} # List all payments Source: https://developers.circle.com/api-reference/cpn/managed-payments/payments/list-payments openapi/payments.yaml get /v1/payments # Create a payout Source: https://developers.circle.com/api-reference/cpn/managed-payments/payouts/create-payout openapi/payouts.yaml post /v1/payouts Create a stablecoin payout. The following table includes the supported pairs of `amount.currency` and `toAmount.currency` for stablecoin address book payouts: | amount.currency | toAmount.currency | | ---------------- | ----------------- | | USD | USD | | EUR | EUR | Required fields depend on your Circle entity; use the request body options that match your integration. For Singapore (CIRCLE_SG) entities and customers using Managed Payments, `purposeOfTransfer` is **required** and must use a payment reason code from [Crypto Payouts payment reason codes](https://developers.circle.com/circle-mint/crypto-payouts-payment-reason-codes). Invalid or missing values can return error code `5020`. # Get a payout Source: https://developers.circle.com/api-reference/cpn/managed-payments/payouts/get-payout openapi/payouts.yaml get /v1/payouts/{id} # List all payouts Source: https://developers.circle.com/api-reference/cpn/managed-payments/payouts/list-payouts openapi/payouts.yaml get /v1/payouts # Create a crypto payment refund address Source: https://developers.circle.com/api-reference/cpn/managed-payments/refund-addresses/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. # Create an account transfer Source: https://developers.circle.com/api-reference/cpn/managed-payments/transfers/create-account-transfer openapi/managed-payments.yaml post /v1/accounts/transfers Create an internal transfer from an account to another account under the same parent. Supported paths are subaccount to subaccount, main wallet to subaccount, and subaccount to main wallet. Cross-parent transfers are rejected. This endpoint creates internal transfers only. Sending funds to an external blockchain address is not supported, and both `source` and `destination` must be of type `account`. # Get an account transfer Source: https://developers.circle.com/api-reference/cpn/managed-payments/transfers/get-account-transfer openapi/managed-payments.yaml get /v1/accounts/transfers/{id} Retrieves a specific transfer. For onchain activity, outbound transfers typically appear with an account source and blockchain destination, while inbound transfers typically appear with a blockchain source and account destination. # List all account transfers Source: https://developers.circle.com/api-reference/cpn/managed-payments/transfers/list-account-transfers openapi/managed-payments.yaml get /v1/accounts/transfers Searches for all money movement recorded against your accounts. Results include internal account-to-account transfers, onchain deposits, and onchain withdrawals. Use the `source` and `destination` fields on each transfer to determine directionality: onchain deposits appear with a blockchain source and an account destination, while onchain withdrawals appear with an account source and a blockchain destination. Note that you can only *create* internal account-to-account transfers between accounts under the same parent. Onchain deposits and withdrawals are recorded by other flows and appear here as read-only history. See [Create an account transfer](#operation/createManagedPaymentsAccountTransfer). Returns up to 50 transfers in descending chronological order or `pageSize`, if provided. If date parameters are omitted, returns the most recent transfers. # Transfer state change Source: https://developers.circle.com/api-reference/cpn/managed-payments/webhooks/custody-transfer openapi/managed-payments-webhooks.yaml webhook custodyTransfer Sent when a stablecoin transfer changes state. A `wallet` destination is an internal transfer between subaccounts. A blockchain destination is an outbound crypto transfer. `status` is one of `pending`, `complete`, or `failed`. The payload also carries `transactionHash`, `fees`, `message`, `errorCode`, `riskEvaluation`, `policyEvaluation`, and `identities` when those values apply. # Subaccount status change Source: https://developers.circle.com/api-reference/cpn/managed-payments/webhooks/mint-accounts openapi/managed-payments-webhooks.yaml webhook mintAccounts Sent when a subaccount changes status. `status` is one of `pending`, `active`, `rejected`, `archived`, or `closed`. `type` is `first_party` or `third_party`, and `purpose` is `payments` or `custody`. # Recipient address state change Source: https://developers.circle.com/api-reference/cpn/managed-payments/webhooks/mint-address-book-recipients openapi/managed-payments-webhooks.yaml webhook mintAddressBookRecipients Sent when a recipient address changes state, most often as it moves through verification. `status` is one of `pending`, `pending_verification`, `pending_additional_information`, `pending_owner_information`, `pending_beneficiary_information`, `denied`, `inactive`, `verification_succeeded`, `active`, `on_hold`, `failed`, or `disabled`. Wait for `active` before using the address as a transfer destination. # Deposit state change Source: https://developers.circle.com/api-reference/cpn/managed-payments/webhooks/mint-deposits openapi/managed-payments-webhooks.yaml webhook mintDeposits Sent when a fiat deposit into a subaccount changes state. `status` is one of `pending`, `complete`, or `failed`. # External entity compliance decision Source: https://developers.circl