End-to-end Payouts Workflow

The following sequence describes the steps your system needs to execute to support a complete customer payout event.

1. Customer requests a payout. Your platform initiates the flow.

2. Client calls the POST/v1/customers/{customerId}/crypto-addresses endpoint to add a crypto address. This provides the beneficiaryAddressId to be used in Payouts.

3. Call POST /v1/payouts. Provide the sourceAccountId, beneficiaryId, beneficiaryAddressId, sourceQuantity, sourceCurrency, beneficiaryCurrency, paymentReason, feePaidBy, and optionally clientReference. Persist the returned payoutId.

4. Review the payout details if required. Use GET /v1/payouts/{payoutId} to retrieve the payout record and verify the beneficiary information, payout amount, fees, conversion rate, and current status. Newly created payouts are returned with a status of PENDING_AUTHORIZATION.

5. Authorize the payout. Call PATCH /v1/payouts/authorize and provide the payoutId in the request body. Include a unique X-Request-Id header to support idempotent retries and prevent duplicate execution. CAMS verifies that the source account has sufficient buying power and transitions the payout to PROCESSING.

6. CAMS executes the payout. Funds are reserved, any required currency conversion is performed using the calculated conversion rate, and the transfer is initiated to the beneficiary's whitelisted wallet address.

7. CAMS monitors payout processing. The payout remains in PROCESSING while the transfer is being completed. Depending on the outcome, the payout status is updated to COMPLETED or FAILED.

8. Monitor and retrieve. Use GET /v1/payouts or GET /v1/payouts/{payoutId} to check payout status, retrieve fee and conversion details, support customer inquiries, and reconcile completed transfers. Results can be filtered by payout ID, beneficiary ID, currency, status, and request date.

9. Track status updates. If webhook notifications are enabled, your system can consume payout status events and update customer-facing interfaces, operational dashboards, or reconciliation workflows automatically.

10. Reconcile and report. Once the payout reaches COMPLETED, use the payout record for audit, reporting, and financial reconciliation. If the payout reaches FAILED, review the returned status and operational logs before initiating a replacement payout request.

Payouts Status Lifecycle

Payouts Process Flow Diagram