API ESSENTIALS

Rules to build by

The few behaviors every CAPSEND integration must handle correctly.

Authentication

Exchange your environment-specific client credentials at POST /api/token. Send the returned token on every wallet and transfer request:

http

Authorization: Bearer ACCESS_TOKEN

Tokens last 3600 seconds. Cache a token securely and request another shortly before expiry. Staging credentials and tokens never work in production, and production credentials and tokens never work in staging.

Money

Send money as a decimal string with no more than four decimal places:

json

{ "amount": "125.5000" }

CAPSEND returns money as four-decimal strings. Keep it as decimal data throughout your system; do not use JavaScript floating-point arithmetic for balances or settlement.

Idempotency

Every create-transfer request needs an idempotency-key header containing a UUID.

Generate one key for one logical transfer.
Save it with your transfer record.
Reuse it when retrying the same request after a timeout.
Never reuse it for a different transfer or changed request body.

An exact retry returns the original transaction. Reusing a key with changed data returns 409 Conflict.

Transfer lifecycle

Status	Meaning	What to do
`PENDING`	CAPSEND accepted and queued the transfer.	Wait for processing.
`PROCESSING`	The transfer is in progress or awaiting confirmation.	Keep it open; do not resend as a new transfer.
`SUCCESS`	The transfer completed successfully.	Mark it successful after a verified webhook or status response.
`FAILED`	The transfer failed.	Record `failureReason` when returned and follow your failure process.
`REFUNDED`	A previously successful transfer was refunded.	Reconcile the refund against the original transfer.
`PROCESSED`	Legacy successful value in historical records.	Treat as a successful terminal state.

Wallet behavior

CAPSEND places a hold for the transfer amount before processing. The configured fee is recorded separately and is not added to the hold or deducted from the wallet balance during payout processing.

The staging wallet is managed for you. If its available test balance falls below its target, CAPSEND restores it before accepting the next eligible staging transfer. One staging transfer cannot exceed the target balance.

Errors

json

{
  "message": "Idempotency key was already used for a different request",
  "code": "CONFLICT",
  "requestId": "5bd75f7a-35f1-4269-96ea-f017c75f32e8"
}

Authentication errors can contain only message. Other errors normally include code and requestId.

Status	Meaning	Retry?
`400`	Invalid request	No; correct the request.
`401`	Missing, invalid, expired, or wrong-environment token	Obtain the correct token.
`402`	Insufficient production wallet funds	Fund the wallet or lower the amount.
`403`	MTO account is not approved or active	Resolve account status.
`404`	Wallet or transfer not found	Verify the environment and identifier.
`409`	Idempotency conflict	Reuse the original body or investigate before proceeding.
`429`	Too many requests	Retry later with exponential backoff and jitter.
`500`	Unexpected CAPSEND error	Retry safely; preserve the idempotency key for create requests.

When contacting CAPSEND support, provide the environment, UTC time, requestId, transaction ID, and CAPSEND reference. Never send an access token, client secret, webhook secret, or full account number.