Integration Guide
Use the sandbox API console in this order: assets and accounts, receiving and receivables, then card issuing. OpenAPI remains the exact request and response contract.
Quick Start
- Open Developer Center and create a sandbox API key with the scope preset for the module you are testing. Copy the secret when it is shown; it cannot be viewed later.
- Open API Console, click Authorize and fill
apiKeyAuth. Enter the API Secret in the console's local signing field. - Run
GET /api/v1/assets, thenGET /api/v1/accounts. A successful response hascode: 0. - Verify receiving instruments and account transactions.
- Create or reuse a contact, then test an invoice or payment link and its webhook.
- Upload the contact's identity documents, confirm card readiness, and submit a card application.
- Copy the working requests into your server integration.
The domain resolves the brand. API keys belong to the issuing user and are separated by sandbox/live environment. V2 requests sign X-Workspace: personal or enterprise:<id>; existing v1 signatures continue to use their original enterprise.
The production API host accepts both sk_sandbox_ and sk_live_ keys. The prefix and signed X-Environment select the environment; test.dcwallet.com uses a separate dev database. The console follows the same module and endpoint order as this guide.
Authentication
Every plan, including Free, supports user-owned API keys and one user-level webhook endpoint per environment. Free includes 100 monthly API calls per sandbox and live workspace, subject to a 10 call per minute limit. KYB onboarding and outbound webhook deliveries do not consume that quota. Calls are counted in the selected workspace and environment.
Every route under /api/v1/** requires signed headers. The following v1 example applies to existing enterprise integrations; new keys use v2:
X-API-Key: sk_sandbox_... or sk_live_...
X-Timestamp: <unix_seconds>
X-Request-ID: <new_16_to_128_character_value>
X-Content-SHA256: <sha256_of_exact_body_bytes>
X-Signature: v1=<hmac_sha256>
Signing
- Serialize the final request body first, then calculate the lowercase hexadecimal SHA-256 digest of those exact bytes. Do not hash a parsed or reformatted JSON object. For a request without a body, hash zero bytes:
e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855. - Set
X-Timestampto the current Unix time in seconds. Generate a newX-Request-IDcontaining 16 to 128 letters, digits, dots, underscores, colons, or hyphens. - Build the UTF-8 canonical value below with exactly seven lines and no trailing newline. Uppercase the HTTP method. Use the request path only, followed by the raw query string exactly as transmitted, including its original encoding and parameter order; use an empty fourth line when there is no query string.
<X-Timestamp>
<UPPERCASE_METHOD>
<REQUEST_PATH>
<RAW_QUERY_OR_EMPTY>
<LOWERCASE_X-CONTENT-SHA256>
<X-Request-ID>
<X-API-Key>
Calculate HMAC-SHA256 over the canonical UTF-8 bytes using the API Secret as the UTF-8 key. Lowercase the hexadecimal result, prefix it with v1=, and send it as X-Signature. The API Secret is used only by the signing client and must never be sent as an HTTP header or stored in application logs.
Verification and replay protection
- The server requires all five headers, accepts only timestamps within 300 seconds of server time, and validates the request ID format.
- It hashes the exact body bytes received and compares the digest with
X-Content-SHA256using a constant-time comparison. - It resolves an active, unexpired API key for the current brand and sandbox/live environment, then verifies its owner, selected workspace, source-IP allowlist, and required route scope.
- It reconstructs the same canonical value and verifies
X-Signaturewith a constant-time comparison. A valid request ID is then reserved for 10 minutes; reusing it with the same API key is rejected as a replay. - After authentication succeeds, per-minute rate limits and the selected workspace's monthly API quota are applied; enterprise verification uses a separate rate limit and does not consume that monthly quota.
Every HTTP retry must use a new timestamp and request ID, then recompute the content hash and signature. For a retry of the same logical write, keep the same Idempotency-Key so the operation is not created twice.
The API console follows this same algorithm in browser memory. Enter the Secret in its local signing field; it never adds X-API-Secret to the request.
For v1, X-Environment is unnecessary. If supplied, it must match the API key.
For v2, sign X-Workspace, X-Environment, Idempotency-Key and the media type in addition to the v1 fields, prefixed by dcwallet-api-v2. Send X-Signature: v2=<hmac_sha256>. The console can generate this signature for the selected workspace. KYB onboarding uses live keys because enterprise verification is shared across environments.
Check each operation's x-dcwallet-signature-versions in the API reference. Published operations accept v2; new operations require v2. New user-owned keys accept v2 only.
Send Accept-Language: en-US, zh-CN, or zh-TW to localize human-readable error messages. Machine API errors default to English when the header is omitted. Numeric code values remain the stable integration contract.
0. Enterprise Verification
Use a v2 key with kyb:read and kyb:write. In the personal workspace, call GET /api/v1/enterprise-applications/requirements in sandbox or live. In live, upload raw PDF/JPEG/PNG bytes with POST /api/v1/enterprise-applications/documents/{documentType}, then submit complete KYB fields and document IDs once with POST /api/v1/enterprise-applications. Failed validation leaves no enterprise application. Select X-Workspace: enterprise:<applicationId> to query review status. If rejected or asked for EDD or renewal, upload replacement documents and call POST /api/v1/enterprise-applications/{applicationId}/resubmit with the complete corrected body.
The requirements response includes fixedFieldOptions for companyType, relatedParties[].partyType, relatedParties[].roles, relatedParties[].idType and relatedParties[].ownershipType. Submit option values, not labels. businessTypeSuggestions offers industry examples; MCC/SIC codes and industry keywords are also accepted. businessScope is a required free-text description of actual activities. fields lists dynamic fieldValues; uboOwnershipThresholdPct gives the share-based UBO threshold.
Submit each person once in relatedParties[], with every applicable role: legal_representative, director, shareholder, beneficial_owner or senior_management. Organization shareholders use partyType=organization. CN requires exactly one legal representative; HK requires at least one director and permits more. handheldDocumentRequired is the general KYB rule; bank-specific missing materials appear in bank-options/{bankId}/requirements.
KYB application, query, document, and submission calls do not consume the monthly API quota; a separate per-user rate limit applies. Sandbox keys can read field requirements but cannot access shared live KYB records. A previous KYB approval continues to allow business calls during EDD, renewal, and pending re-review; rejection and explicit compliance restrictions can still block calls.
To test bank opening before live KYB approval, sign POST /api/v1/sandbox/enterprise-samples with a sandbox v2 key, X-Workspace: personal, and an Idempotency-Key. It returns one reusable synthetic Hong Kong enterprise workspace for this user. Select its returned enterprise:<id> to test sandbox bank accounts, addresses, receipts, and webhooks. This sample is never a legal KYB approval and is invisible to live keys.
System-generated synthetic enterprise workspaces have a dedicated sandbox allowance of 100,000 API requests per UTC calendar month and 120 per minute by default. Existing usage counters are preserved and larger workspace allowances remain effective. This does not grant a paid subscription or live access; ordinary enterprise and personal quotas are unchanged.
Webhook delivery is optional. To receive KYB results, configure a user-level HTTPS callback once in the developer page or with POST /api/v1/webhook-endpoints in the personal workspace, and save its signing secret. The applicant is linked to the new enterprise automatically. One endpoint may receive all linked enterprise events. You can also poll the application without registering a callback.
KYB status contract: not_submitted means no complete application; pending means review in progress; approved means verified; rejected means declined; review_required means corrections requested; edd_required means enhanced due diligence requested; renewal_required means evidence must be refreshed. The initial value is not_submitted. KYB has no permanent terminal state: an approval may later require EDD or renewal, and a rejected application can be resubmitted. Use GET /api/v1/enterprise-applications/{applicationId} for reviewNote, actionRequired and field review details. The same status appears in KYB webhooks as currentStatus.
1. Assets and Accounts
GET /api/v1/assets returns enabled currencies and networks. GET /api/v1/accounts returns customer-facing balances, capabilities, and status. /accounts/{id}/transactions supports filters and transaction detail with before/after balances. Internal Wallet, custody, provider, seed, and vault identifiers are deliberately hidden.
2. Receiving Accounts
Use GET /api/v1/bank-options and GET /api/v1/bank-options/{bankId}/requirements to check eligibility and missing KYB materials. Send a v2 signed POST /api/v1/bank-account-applications with bankId, selected currencies, purpose and Idempotency-Key. For a missing DBS handheld photo, upload handheld_id and include {"requirementCode":"director_or_ubo_handheld_id","personId":"...","documentId":"..."} in supplements[]. DBS supports SGD. Currency Cloud, DBS and CFSB open synthetic accounts in sandbox; live applications await manual review and account entry. Poll the application, then list issued accounts with GET /api/v1/bank-accounts.
If the bank option lists applicationDocuments, upload each required PDF/JPEG/PNG using POST /api/v1/bank-application-documents with raw signed bytes and Idempotency-Key. Submit each returned ID as {"code":"application_form","documentId":"..."} in the bank application's applicationDocuments[]. When a rule has expiryDateRequired: true, include an ISO date such as "expiryDate":"2027-12-31" for each file. The date must be current at submission and approval. These files are attached to that application for operator review.
Send a v2 signed POST /api/v1/blockchain-addresses with chain and Idempotency-Key. The server selects the workspace default receiving wallet. The response contains an active public address; custody and provider metadata remain hidden.
Use account:read to poll GET /api/v1/payment-records for credits. User-level webhooks can subscribe to payment.pending_settlement for an AML-held fiat receipt and payment.settled after funds are credited. Subscribe to bank_account.* and blockchain_address.activated for receiving-resource updates.
The bank application list returns a paginated data object with items, total, page, and pageSize. Sandbox fiat and crypto deposit simulations accept status: settled (default), pending_settlement, refunded, or reversed. The last three create a test record and webhook without crediting funds.
Receiving status contract: a bank application begins at pending, may enter reviewing, then ends at approved or rejected. Approval is the application result; query GET /api/v1/bank-accounts for the actual issued account. Bank account and blockchain address status values are active and inactive; these are resource availability states, not final application outcomes. A payment record starts at pending_payment, can enter paying or pending_settlement, and reaches settled, failed, refunded or reversed. Settled funds can later be refunded or reversed; failed, refunded and reversed are final outcomes. The payment matchStatus is an extensible reconciliation label, not a settlement status. Inspect returned routingCodeType and localClearingNetwork on each issued bank account; these values depend on the bank and may be null.
3. Contacts
Use the same contact IDs shown in the dashboard for invoices, payment links, and cardholders. Start with GET /api/v1/contacts to reuse an existing contact, or create one with POST /api/v1/contacts and Idempotency-Key. OpenAPI shows accepted values and meanings for contact role, entity type, identity type, and document role. Use /contacts/{contactId}/accounts to maintain the contact's bank accounts and blockchain addresses.
For card products that require identity verification, upload the passport file or identity-document images to the contact first. The platform reads those stored files and securely submits them to the issuing channel during the card application; the card-application body therefore does not contain image or document fields.
4. Receivables
Receivables are the single creation and management concept. Create a draft with POST /api/v1/receivables, then activate its hosted checkout URL with POST /api/v1/receivables/{invoiceId}/send. Use a contact ID for business billing, or omit the contact and receiving account for a consumer stablecoin checkout with an automatically leased collection address. /api/v1/invoices remains a compatibility alias. Query received funds with GET /api/v1/payment-records. Both writes need an Idempotency-Key on v2 requests.
4a. Exchange
GET /api/v1/exchange/rates is indicative. Select two address IDs from GET /api/v1/blockchain-addresses, then create a no-funds-moved quote with POST /api/v1/exchange/quotes. Supply sourceAddressId, targetAddressId, sellCurrency, buyCurrency, and positive sellAmount. Confirm before quoteExpiresAt using POST /api/v1/exchange/orders with quoteId and a fresh Idempotency-Key.
Read GET /api/v1/exchange/orders/{orderId} until terminal. Subscribe to exchange.completed, exchange.failed, exchange.refunded, and exchange.cancelled; deduplicate by eventId. Cancellation is allowed only before an irreversible chain step. These writes require a v2 signed enterprise workspace, exchange:write, and enterprise exchange permission. Fiat rates remain indicative.
For crypto-to-fiat, select sourceAddressId from GET /api/v1/blockchain-addresses and a fiat targetAccountId from GET /api/v1/accounts?assetType=fiat. Submit POST /api/v1/exchange/crypto-fiat-orders with both currencies, sellAmount, and minimumBuyAmount. In Live, the source crypto is locked and the collection workflow starts; the fiat leg stays pending until settlement is reconciled. Poll the order for collectionStatus, collectionTxHash, actualBuyAmount, actualBuyCurrency, and nextStep. Use a fresh Idempotency-Key for each new order and the same key only to retry the exact request.
POST /api/v1/exchange/crypto-fiat-orders
{
"sourceAddressId": "<USDT address ID>",
"targetAccountId": "<USD account ID>",
"sellCurrency": "USDT",
"buyCurrency": "USD",
"sellAmount": 100,
"minimumBuyAmount": 98
}
Use status for the exchange outcome: completed means the fiat account was credited; pending_manual is unfinished. On completion, actualBuyAmount and actualBuyCurrency are the final net credit. minimumBuyAmount guards the net amount before order creation and reservation. collectionStatus=confirmed means only that collection finished, not fiat settlement. Sandbox collection fields may be null. nextStep is translated display text, not a status enum.
Cancellation and known failures before irreversible collection release the source reservation; this is not a second refund credit. Check canCancel. Broadcast or uncertain collection requires reconciliation before any unlock. General exchange states refund_pending and refunded mean refund outstanding and completed respectively; the crypto-to-fiat API has no customer-initiated refund route.
Amount-aware rates are indicative and are priced again on submission. Fees and net buy amounts use six decimal places with HALF_UP rounding. Crypto-to-fiat order fees are shown in the buy currency, without a second charge. When the quote fee is in sell units, the order fee is rounded gross buy amount minus rounded net buy amount. For example, selling 1 USDC at 0.9999 with a 0.005 USDC quoted fee gives a 0.994901 USD net credit and a 0.004999 USD displayed fee; stablecoins are not treated as fixed 1:1 USD.
Without an order ID, list GET /api/v1/exchange/orders?page=1&pageSize=20 in the same signed workspace and environment. There is currently no idempotency-key or request-ID filter. For an uncertain 5xx/timeout, retain the key and exact body and provide support with the request ID and response reference; do not create a replacement using a new key.
5. Transfers
Use transfer:write with POST /api/v1/transfers or /api/v1/transfer-batches and send an Idempotency-Key. The normal signed API-key headers authorize unattended server-to-server submission; X-2FA-Code is not used on machine requests. Creating, changing, rotating, or revoking a Live API key remains protected by interactive 2FA.
Mainland CNY payouts use an automatic platform simulator in sandbox. Transfer requirements expose executionMode and simulated; available=true, executionMode=api, simulated=true identifies this simulator. Use a sandbox CNH account, CNY recipient currency and country CN. Synthetic recipients: bank Platform Sandbox Bank, individual SANDBOX INDIVIDUAL / account 000000000000000001, or business SANDBOX BUSINESS LTD / account 000000000000000002. Omit the rail for default CNAPS field rules. Normal single-payment tests use the configured sandbox simulator policy; custom approval and compliance requirements still apply. Query the transfer until terminal. Live remains manual; a simulated platform receipt is not proof of bank payment.
Transfer business integration flow
Before building a fiat payout, call GET /api/v1/transfers/requirements with destination country, currency, optional beneficiaryType, paymentRail, and amount. suggestedRails gives country/currency field examples, not channel support. configuredRails lists rails explicitly advertised by eligible channels; query each concrete rail and amount to verify policy and route availability. A provider-defined rail has fieldRulesKnown=false, so apply its provider requirements in addition to generic fields. available=true requires the selected payout route to explicitly advertise that rail. Legacy routes without rail metadata return available=false with unavailableReason=rail_support_unverified even when a generic payout route exists. Other reasons are rail_not_described, amount_required, channel_unavailable, workspace_not_enabled and route_unavailable. A false preview does not itself reject submission; submission rechecks its own gates. Use the linked document requirements preview for conditional supporting files.
GET /api/v1/accountsand select an account whoseavailableBalancecovers the transfer; retain itsaccountId.POST /api/v1/transferswith thatsourceAccountIdand anIdempotency-Key; retain the returned transferid.GET /api/v1/transfers/{transferId}until the status issucceeded,failed,rejected, orcancelled.- Register
POST /api/v1/webhook-endpointsonce with the four terminal transfer events to receive asynchronous final results.
{
"sourceAccountId": "337893979704000514",
"amount": 100,
"recipientCurrency": "CNY",
"recipientBankName": "Bank of China",
"recipientAccountHolder": "Zhang San",
"recipientAccountNo": "6217000012345678901"
}
This direct CNY request does not require a contact, destinationAccountId, or beneficiary identity number. The source account must be CNH. When omitted, recipientBankCountryCode defaults to CN and recipientBeneficiaryType defaults to individual.
For a business beneficiary, set recipientBeneficiaryType to business. You may also provide recipientRegistrationNumber and recipientRegistrationType; supported examples include Hong Kong brn, European business_registration or vat, UK company_number, and US ein. The registration identifier is optional unless the selected payout channel requires it.
Transfer field values: recipientBeneficiaryType accepts exactly individual and business; it defaults to business when a registration number is supplied and otherwise to individual. recipientPaymentRail is optional and inferred from the IBAN, clearing code, bank country or SWIFT/BIC when absent. recipientBankCountryCode defaults to CN for direct CNY payout. recipientAccountIdentifierType is usually iban or local and is inferred from the account number. recipientRoutingCodeType commonly uses aba, sort_code, bank_code or cnaps. These rail and routing examples are extensible, not closed enums. recipientBankAccountType, recipientRegistrationType and paymentPurpose are free text; providers or document policies may impose additional conditions. Query /transfers/requirements for country/currency field suggestions and /transfers/document-requirements/preview for document rules.
- Hong Kong local account:
recipientBankCountryCode=HK,recipientPaymentRail=CHATS, and abank_code. - Euro-area account: an ISO country code, a valid IBAN, and
recipientPaymentRail=SEPA. - UK local account:
recipientBankCountryCode=GB,recipientPaymentRail=CHAPS, and a six-digitsort_code. - US local account:
recipientBankCountryCode=US,recipientPaymentRail=FEDWIRE, and a valid nine-digitabarouting number.
{
"url": "https://example.com/webhooks/transfers",
"events": [
"transfer.succeeded",
"transfer.failed",
"transfer.rejected",
"transfer.cancelled"
]
}
Webhook delivery is asynchronous and may be retried, so deduplicate by eventId and verify its signature. Keep status polling as the reconciliation fallback. API submissions use the same balance locking, compliance, approval, and channel-availability gates as the dashboard.
A saved destinationAccountId remains supported. A batch contains 1–500 rows and every row must use the same payment method, currency, and blockchain network; subscribe to batch_transfer.* for batch results.
Transfer states: pending (queued), draft (saved before submission), pending_approval (generic approval), pending_batch_approval (batch approval), pending_enterprise_approval (enterprise approval), enterprise_approved (enterprise approved), pending_platform_approval (platform approval), pending_compliance (compliance review), approved (authorized), signature_pending (awaiting signature), external_verifying (external verification), processing (executing), confirming (awaiting confirmation), pending_manual (queued for operator), manual_processing (operator executing) and failed_unknown (outcome under investigation) are nonterminal. The terminal states are succeeded (paid), failed (failed), rejected (denied) and cancelled (cancelled). There is no fixed submission default because approval rules determine the first state. Batch states are draft (prepared), pending_approval (awaiting review), approved (ready), processing (running), completed (finalized), rejected (denied) and cancelled (cancelled); the last three are terminal. Batch result is null until finalized, then succeeded (all succeeded), partial_failed (mixed result) or failed (none succeeded). These three values also filter GET /api/v1/transfer-batches?result=....
Single transfers enter enterprise approval when an active rule matches. Enterprise batches always require enterprise approval. clientOrderNo is unique within the brand, environment, and enterprise. A sandbox webhook test with transfer.succeeded or transfer.failed checks delivery only; it does not change the transfer or its locked funds.
When a transfer requires supporting documents, call POST /api/v1/transfers/document-requirements/preview, then upload PDF/JPEG/PNG bytes with POST /api/v1/transfers/documents/{role}. Include the returned documentId in the transfer request. V2 uploads require Idempotency-Key; reuse it with the same file bytes on retry.
6. Card Issuing
Card products expose bins with threeDsRequirement, cardholderRequirement and contactRequired. When a virtual BIN explicitly returns contactRequired=false, pass its ID as selectedBinId and omit contactId. An unknown cardholder requirement retains the default contact requirement. The 3DS marker does not control contact selection or issuance. Account KYC/KYB, AML, entity, country and funding checks still apply. Physical cards require a contact, and 3DS metadata does not enroll a card in 3DS.
Use account:read, contact:read, contact:write, card:read, and card:write. Add card_sensitive:read for hosted card reveal and webhook:read/webhook:write for callbacks.
GET /api/v1/assetsand/accounts, then select a funding account.POST /api/v1/contactswithIdempotency-Key,externalReference, identity, and residential-address data.- Upload raw file bytes to
POST /api/v1/contacts/{contactId}/documents/identity_frontandidentity_back, or usepassport. The platform forwards these stored files to the issuing channel when you submit the application. GET /api/v1/contacts/{contactId}and resolve every item inmissingFields.GET /api/v1/card-productsand choose one whose entity type, country, KYB requirement, and remaining inventory match the contact and enterprise.POST /api/v1/card-applications/quoteto check eligibility and fees, thenPOST /api/v1/card-applicationswith anIdempotency-Keyheader.- Query
/api/v1/card-applications/{id},/api/v1/cards/{id}, and card transactions. - After the cardholder completes second-factor verification in your own application, create
POST /api/v1/cards/{cardId}/reveal-sessionsand open its one-use hosted URL in a top-level browser window. - Use
/top-ups,/freeze,/unfreeze,/cancel, orPATCH /cards/{id}for card management. In sandbox, callPOST /cards/{id}/sandbox/purchases, then verify the result under/api/v1/card-transactions.
Signed v2 enterprise requests support card reveal, freeze, unfreeze, cancellation, nickname updates, sandbox purchase simulation and shared-card budgets. Live v2 budget funding and withdrawal put twoFaCode in the signed JSON body.
{
"contactId": "337893979704000512",
"productId": "337893979704000513",
"sourceAccountId": "337893979704000514",
"initialAmount": 100,
"nickname": "Marketing",
"purpose": "Online advertising"
}
Keep IDs as strings. Every card write uses an Idempotency-Key. AML must be clear and required enterprise KYB must be approved. Identity cards need front and back files; passports need only the passport file. Card top-ups also require the original sourceAccountId and return a top-up transaction. Sandbox purchase simulation accepts amount, merchantName, and merchantCategoryCode; live keys are rejected.
Hosted card reveal
Your application performs the cardholder's second-factor verification. Then send an opaque verificationSubject, the method, your audit reference, and a UTC verifiedAt no older than five minutes to POST /api/v1/cards/{cardId}/reveal-sessions. The URL expires after two minutes and works once; it shows PAN, expiry, and CVV for 60 seconds. Do not embed, log, persist, or instrument the URL. Your backend never receives raw card data.
{
"verificationSubject": "customer-user-42",
"verificationMethod": "passkey",
"verificationReference": "verify_01J5Z8YQABCD",
"verifiedAt": "2026-08-20T19:15:00Z"
}
If a channel write returns code 9003, keep the same idempotency key and query its resource until reconciliation completes. Do not create a second operation with a new key. Temporary states include reconciling, processing, freezing, unfreezing, and cancelling.
7. Webhooks
Register /api/v1/webhook-endpoints with subscriptions such as transfer.*, batch_transfer.*, card.*, invoice.*, payment.link.*, and agent.*. For a v2 create request, send Idempotency-Key; a retry with the same key and body returns the same endpoint and secret. Save that secret and verify v1=HMAC-SHA256(timestamp + "." + rawBody) using the brand-neutral X-Webhook-Timestamp and X-Webhook-Signature headers.
New v2 endpoints have account-level scope within one brand and environment. They receive matching events from the personal workspace and every actively linked enterprise. X-Workspace on the create request and enterprise IDs in the callback URL do not restrict delivery to that enterprise. The response reports scopeType: "account" and enterpriseId: null; historical v1 endpoints remain enterprise-scoped. Use enterpriseId in the verified event body to route each delivery to its workspace.
- Call
GET /api/v1/webhook-endpoints/event-typesto see the concrete events available in the sandbox test selector. - Create an endpoint whose subscription matches the event, for example
card.*. - Call
POST /api/v1/webhook-endpoints/{endpointId}/testwith a sandbox v2 enterprise key and select aneventType. HTTP 202 returns aneventIdanddeliveryId. - Query
GET /api/v1/webhook-endpoints/{endpointId}/deliveries?deliveryId=...until the status isdeliveredordead_letter.
A test event uses the production signing, asynchronous queue, retry policy, and delivery log, but is sandbox-only, contains test: true, targets only the selected endpoint, and never creates a card, transaction, invoice, payment, or balance change. Every payload includes eventVersion and createdAt; deduplicate deliveries by eventId.
Webhook state contract: GET /api/v1/webhook-endpoints/event-types returns the current concrete sandbox test events; do not treat examples in this guide as a complete event enum. Delivery status is pending (queued or scheduled for retry), delivering (worker processing), delivered (receiver returned 2xx, terminal) or dead_letter (attempts exhausted, terminal). The signed event body carries previousStatus and currentStatus for its resource; interpret those with the resource status contract above or in the API response schema. A settled payment may later become refunded or reversed; these two and failed are terminal payment outcomes. pending_payment, paying and pending_settlement are nonterminal.
The signed JSON body includes workspaceType and enterpriseId; after verifying the signature, compare them with X-Workspace. Delivery makes up to eight attempts, with delays of 1, 4, 9, 16, 25, 36, and 49 minutes before the remaining retries. A final failure enters dead_letter.
Request IDs and Retries
X-Request-ID identifies one signed HTTP attempt and must change on every retry. Idempotency-Key identifies one intended write and must stay the same for retries of that operation. On v2 routes with persisted idempotency, reusing the key with different request bytes is rejected. Check each operation's signature-version note before implementing it.
Successful exchange idempotency records currently have no automatic expiry. They are scoped to brand, environment, owning user, workspace and operation, separately from request-ID replay protection. A fully rolled-back transaction retains neither an order nor a permanent failed-key result, so replaying that key later may execute. Refresh the timestamp, request ID and signature for each retry; an HTTP error alone does not prove the final funds outcome.
Troubleshooting
| Result | Check first |
|---|---|
| 401 | The API-key prefix matches X-Environment, the secret belongs to this key, the key is active, and your server signs the exact path, query, and body bytes. |
| 403 | Check the operation's accepted signature versions, the signed X-Workspace, the key's scope, the selected workspace's subscription, and KYB or KYC approval. |
| 409 | The same Idempotency-Key was not reused with a different request body, and the resource allows the requested state change. |
| 429 | Inspect details[].reason and Retry-After. Monthly exhaustion returns X-Quota-*; minute exhaustion returns X-RateLimit-*. Reset values are Unix seconds. |
| 503 | The signing or quota service is temporarily unavailable. Retry later with a new X-Request-ID and the same idempotency key for the same write. |
A 429 response identifies the verified allowance owner through X-Quota-Workspace and X-Quota-Environment. Monthly windows reset at 00:00 UTC on the first day of the next calendar month. Keys selecting the same workspace share its quota; rotating a key does not reset it.
Error requestId matches the response X-Request-ID. Check details[].field for missing fields and details[].allowedValues for a missing scope. On request_mismatch, restore the original bytes and reuse the original idempotency key. After an unconfirmed result, query the known resource ID or retry the exact original request with its original key and a fresh signed request ID; do not create a replacement order.
If a secret was not saved, rotate the key in Developer Center. Include the response X-Request-ID when reporting an issue.
Errors
{ "code": 0, "message": "OK", "data": {} }
HTTP statuses: 400 validation, 401 credential/signature, 403 scope/subscription/policy, 404 resource, 409 conflict, 422 business rejection, 429 rate or monthly quota, 500 internal failure, and 503 temporary quota-service failure. Responses echo X-Request-ID. Successful authenticated responses also return X-Quota-Limit, X-Quota-Remaining, and X-Quota-Reset.
Exchange sell and minimum buy amounts must be positive. Resource IDs are positive signed 64-bit integer strings. Invalid input returns 400 with a specific details[].field; must_be_positive, invalid_id and same_as_source explain the correction. An exchange absent from the selected workspace or environment returns 404. Pagination requires page >= 1 and pageSize between 1 and 100.
8. Treasury Agent
Treasury Agent is the final optional module under /api/v1/agent. Signed v2 enterprise keys use agent:read to discover capabilities and query tasks/events, or agent:write to create and cancel tasks. Current enterprise developer permissions are checked on each request; task execution still requires user authorization.
GET /api/v1/agent/capabilities
POST /api/v1/agent/tasks
GET /api/v1/agent/tasks/{taskId}
GET /api/v1/agent/tasks/{taskId}/events
POST /api/v1/agent/tasks/{taskId}/cancel
Create JSON contains only capability, intent, and input; enterprise and environment come from the API key. HTTP 202 records the task but does not mean completion or funds movement. API keys cannot authorize tasks.