Disbursements

Disbursements are merchant-initiated payments of funds from your CDP account to a Coinbase user or onchain address. Use them for standalone refunds, goodwill payments, rebates, and other payouts that are not tied to a specific payment session.

For returning captured funds to the buyer within a payment session, use session refunds instead. Disbursements are for payouts independent of any session.

When to use disbursements

Scenario	Use
Buyer paid $100, you need to return $30	Session refund (`POST /payment-sessions/{id}/refunds`)
Goodwill credit for a delayed shipment	Disbursement (`POST /disbursements`)
Rebate to a customer’s Coinbase account	Disbursement
Payout to an onchain address	Disbursement

Create a disbursement

Disbursements are asynchronous. The resource is returned in pending status and transitions to succeeded or failed. To a Coinbase user:

{
  "source": {
    "accountId": "account_af2937b0-9846-4fe7-bfe9-ccc22d935114",
    "asset": "usdc"
  },
  "target": {
    "coinbaseUserId": "coinbase_user_abc123"
  },
  "amount": "25.00",
  "asset": "usdc",
  "reason": "Goodwill credit for delayed shipment",
  "externalReferenceId": "credit-2026-05-1234",
  "metadata": {
    "customer_id": "cust_12345",
    "ticket_id": "TICKET-789"
  }
}

To an onchain address:

{
  "source": {
    "accountId": "account_af2937b0-9846-4fe7-bfe9-ccc22d935114",
    "asset": "usdc"
  },
  "target": {
    "address": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
    "network": "base"
  },
  "amount": "10.00",
  "asset": "usdc",
  "reason": "Rebate for overcharge"
}

Target types

Target	Fields	Description
Coinbase user	`coinbaseUserId`	Send to a Coinbase account
Onchain address	`address`, `network`	Send to any blockchain address. Supported networks: Base, Ethereum, Solana, Aptos, Arbitrum, Optimism, Polygon

Disbursement statuses

Status	Description
`pending`	Disbursement accepted, awaiting settlement
`succeeded`	Funds delivered. `onchainTransactions` populated with transaction hash and network.
`failed`	Disbursement could not be completed. `error` object contains `code` and `message`.

Response

{
  "disbursementId": "disbursement_82c879c1-84e1-44ed-a8c2-1ac239cf09ad",
  "source": {
    "accountId": "account_af2937b0-9846-4fe7-bfe9-ccc22d935114",
    "asset": "usdc"
  },
  "target": {
    "coinbaseUserId": "coinbase_user_abc123"
  },
  "amount": "25.00",
  "asset": "usdc",
  "status": "pending",
  "reason": "Goodwill credit for delayed shipment",
  "externalReferenceId": "credit-2026-05-1234",
  "metadata": {
    "customer_id": "cust_12345",
    "ticket_id": "TICKET-789"
  },
  "createdAt": "2026-05-16T17:00:00.000Z",
  "updatedAt": "2026-05-16T17:00:00.000Z"
}

When the disbursement succeeds, the response includes the onchain transaction:

{
  "status": "succeeded",
  "onchainTransactions": [
    {
      "transactionHash": "0xabc123def456789012345678901234567890abcdef1234567890abcdef123456",
      "network": "base"
    }
  ]
}

Filtering

List disbursements with optional filters:

Filter	Description
`status`	Filter by `pending`, `succeeded`, or `failed`
`sourceAccountId`	Filter by the source CDP account
`externalReferenceId`	Filter by your client-supplied reference

cdp api /disbursements -e sandbox status==succeeded

Webhooks

Subscribe to acceptance.disbursement.* events for real-time status updates:

Event	Description
`acceptance.disbursement.pending`	Disbursement accepted, awaiting settlement
`acceptance.disbursement.succeeded`	Disbursement settled onchain
`acceptance.disbursement.failed`	Disbursement could not be completed

See Webhooks for setup.

Idempotency

Use the X-Idempotency-Key header (UUID v4) to safely retry disbursement requests:

cdp api -X POST /disbursements -e sandbox \
  "Header:X-Idempotency-Key:8e03978e-40d5-43e8-bc93-6894a57f9324" \
  source.accountId=$ACCOUNT_ID \
  source.asset=usdc \
  target.coinbaseUserId=coinbase_user_abc123 \
  amount=25.00 \
  asset=usdc

Idempotency keys are stored for 24 hours from the first stored response. Retries don’t extend that window. Within it, a repeated request with the same key returns the original response, unless the original returned 429 or a 5xx status. Those responses aren’t stored, so a retry with the same key is processed as a new request. If a request gets a 429 or 5xx, retry it with the same key and exponential backoff. After 24 hours, the key expires and a retry with it is processed as a new request, which can create a duplicate. Check the resource’s status before retrying an older request.

Payment Sessions

Session-linked refunds for returning captured funds

Webhooks

Real-time disbursement status events

API Reference

Full disbursement API

GET STARTED

AI AGENTS

WALLETS

PAYMENTS

STABLECOINS

TRADING

ONCHAIN TOOLS

CUSTOMERS

WEBHOOKS

CONSUMER APIS

BUSINESS APIS

INSTITUTIONAL APIS

When to use disbursements

Create a disbursement

Target types

Disbursement statuses

Response

Filtering

Webhooks

Idempotency

Payment Sessions

Webhooks

API Reference

​When to use disbursements

​Create a disbursement

​Target types

​Disbursement statuses

​Response

​Filtering

​Webhooks

​Idempotency

​Related

Payment Sessions

Webhooks

API Reference

When to use disbursements

Create a disbursement

Target types

Disbursement statuses

Response

Filtering

Webhooks

Idempotency

Related