Bounded internal transfer API.
Move recorded testnet balances between approved wallets in your workspace, with exact fees, transaction limits and a shared daily allowance.
01Connect with the server SDK
Version 0.2.0 of @allwallex/checkout-sdk includes the six internal-transfer methods on AllwallexClient. Use quoteInternalTransfer and confirmInternalTransfer with separate persisted idempotency keys, then getInternalTransferQuote for outcome recovery. getInternalTransferLimits shows the current policy and UTC-day usage; listInternalTransfers follows recorded receipts. The SDK validates exact fee arithmetic and quote/receipt bindings and does not retry automatically.
02Grant specific authority
In Developers, verify your passkey and choose Create internal transfers. Select source wallets, destination wallets and an asset-specific maximum total debit per transaction and per UTC day. Both wallets must be ready on the same testnet. Confirm the wallet and debit limits before issuing the key. Add transfers:read to inspect limits, status and history. Existing keys gain no new permissions.
03Review the total debit
POST /v1/merchant/internal-transfer-quotes with sourceWalletId, destinationWalletId, assetId, an exact decimal amount and a persisted Idempotency-Key. The response freezes the received amount, processing fee and total debit for 60 seconds. Quotes do not reserve funds or daily allowance. Both limits include fees.
04Confirm once
POST /v1/merchant/internal-transfers with the quoteId and a separate persisted Idempotency-Key. Current key, creator role, website proof, wallet policy, balance, fee snapshot and limits are rechecked in the same transaction as the balanced ledger journal. Usage and financial records commit together. Refused or expired requests roll back all changes.
05Recover the saved outcome
Retry the identical request with the original key and body, or GET /v1/merchant/internal-transfer-quotes/{id}. Completed requests retain their receipt even after quote expiry, subject to current key authority. Quotes and confirmation request identities remain bound to the issuing key. Another key or an app session cannot confirm that quote. A key with transfers:read in the workspace can inspect current status before starting a new operation.
06Inspect and close
GET /v1/merchant/internal-transfer-limits returns this key’s policy and current UTC-day usage. GET /v1/merchant/internal-transfers returns history with an optional before UUID cursor. POST /v1/merchant/internal-transfer-quotes/{id}/cancel with {} closes an unused quote or returns its completed receipt; it cannot reverse a transfer. Status/history reads require transfers:read; quote, confirmation and cancellation require transfers:create.
07Rotate without resetting limits
A replacement financial key must retain the same wallet and limit policy. It shares daily usage with the original key, including during the overlap period. A changed policy requires a new separately reviewed key. Daily allowance resets at 00:00 UTC; a transaction crossing that boundary is rolled back for a safe retry. Revoke the old credential after checking the replacement.
08Scope and errors
These permissions support same-workspace testnet ledger transfers. They do not sign transactions, bridge networks, send externally, change fees or provide administrative access. API_TRANSACTION_LIMIT and API_DAILY_LIMIT return 409. Unapproved wallets/assets, a mismatched quote authority or a missing grant return 403. Expired keys return 401. Respect request quotas and retain original request identities after transport failures.
POST /v1/merchant/internal-transfer-quotes
Authorization: Bearer <server-key-with-transfers:create>
Idempotency-Key: <persisted-quote-request>
Content-Type: application/json
{
"sourceWalletId": "<approved-source-uuid>",
"destinationWalletId": "<approved-destination-uuid>",
"assetId": "ethereum:sepolia:usdc",
"amount": "70",
"reference": "Allocation 1042"
}
POST /v1/merchant/internal-transfers
Authorization: Bearer <same-server-key>
Idempotency-Key: <persisted-confirmation-request>
Content-Type: application/json
{ "quoteId": "<original-quote-uuid>" }
GET /v1/merchant/internal-transfer-quotes/{quoteId}
GET /v1/merchant/internal-transfer-limits
GET /v1/merchant/internal-transfersOpen your workspace