Create a disbursement - Coinbase Developer Documentation

curl --request POST \
  --url https://api.cdp.coinbase.com/platform/v2/disbursements \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "source": {
    "accountId": "account_af2937b0-9846-4fe7-bfe9-ccc22d935114",
    "asset": "usdc"
  },
  "target": {
    "coinbaseUserId": "coinbase_user_abc123"
  },
  "amount": "25.00",
  "asset": "usdc",
  "reason": "Goodwill disbursement for delayed shipment.",
  "externalReferenceId": "disbursement-2026-04-1234",
  "customerDisplay": {
    "merchantName": "Acme Store",
    "referenceCode": "REF-ABC123"
  },
  "metadata": {
    "customer_id": "cust_12345",
    "order_id": "order_67890"
  }
}
'

{
  "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 disbursement for delayed shipment.",
  "externalReferenceId": "disbursement-2026-04-1234",
  "customerDisplay": {
    "merchantName": "Acme Store",
    "referenceCode": "REF-ABC123"
  },
  "metadata": {
    "customer_id": "cust_12345",
    "order_id": "order_67890"
  },
  "createdAt": "2026-04-17T17:00:00.000Z",
  "updatedAt": "2026-04-17T17:00:00.000Z"
}

{
  "errorType": "invalid_request",
  "errorMessage": "Invalid disbursement parameters."
}

{
  "errorType": "idempotency_error",
  "errorMessage": "Idempotency key '8e03978e-40d5-43e8-bc93-6894a57f9324' was already used with a different request payload. Please try again with a new idempotency key."
}

{
  "errorType": "internal_server_error",
  "errorMessage": "An internal server error occurred. Please try again later."
}

{
  "errorType": "bad_gateway",
  "errorMessage": "Bad gateway. Please try again later."
}

{
  "errorType": "service_unavailable",
  "errorMessage": "Service unavailable. Please try again later."
}

POST

disbursements

curl --request POST \
  --url https://api.cdp.coinbase.com/platform/v2/disbursements \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "source": {
    "accountId": "account_af2937b0-9846-4fe7-bfe9-ccc22d935114",
    "asset": "usdc"
  },
  "target": {
    "coinbaseUserId": "coinbase_user_abc123"
  },
  "amount": "25.00",
  "asset": "usdc",
  "reason": "Goodwill disbursement for delayed shipment.",
  "externalReferenceId": "disbursement-2026-04-1234",
  "customerDisplay": {
    "merchantName": "Acme Store",
    "referenceCode": "REF-ABC123"
  },
  "metadata": {
    "customer_id": "cust_12345",
    "order_id": "order_67890"
  }
}
'

{
  "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 disbursement for delayed shipment.",
  "externalReferenceId": "disbursement-2026-04-1234",
  "customerDisplay": {
    "merchantName": "Acme Store",
    "referenceCode": "REF-ABC123"
  },
  "metadata": {
    "customer_id": "cust_12345",
    "order_id": "order_67890"
  },
  "createdAt": "2026-04-17T17:00:00.000Z",
  "updatedAt": "2026-04-17T17:00:00.000Z"
}

{
  "errorType": "invalid_request",
  "errorMessage": "Invalid disbursement parameters."
}

{
  "errorType": "idempotency_error",
  "errorMessage": "Idempotency key '8e03978e-40d5-43e8-bc93-6894a57f9324' was already used with a different request payload. Please try again with a new idempotency key."
}

{
  "errorType": "internal_server_error",
  "errorMessage": "An internal server error occurred. Please try again later."
}

{
  "errorType": "bad_gateway",
  "errorMessage": "Bad gateway. Please try again later."
}

{
  "errorType": "service_unavailable",
  "errorMessage": "Service unavailable. Please try again later."
}

Authorizations

Authorization

string

header

required

A JWT signed using your CDP API Key Secret, encoded in base64. Refer to the Generate Bearer Token section of our Authentication docs for information on how to generate your Bearer Token.

Headers

X-Idempotency-Key

string

An optional string request header for making requests safely retryable. When included, duplicate requests with the same key will return identical responses. Refer to our Idempotency docs for more information on using idempotency keys.

Required string length: 1 - 128

Body

application/json

A request to create a disbursement.

source

Account · object

required

The source from which to fund the disbursement.

Show child attributes

Example:

{
  "accountId": "account_af2937b0-9846-4fe7-bfe9-ccc22d935114",
  "asset": "usdc"
}

target

Disbursement Coinbase Target · object

required

The target receiving the disbursement.

Disbursement Coinbase Target
Disbursement Wallet Target

Show child attributes

Example:

{ "coinbaseUserId": "coinbase_user_abc123" }

amount

string

required

A decimal representation of the amount to disburse, denominated in asset.

Example:

"25.00"

asset

string

required

The symbol of the asset for the disbursement amount.

Required string length: 1 - 42

Example:

"usdc"

reason

string

Human-readable reason for the disbursement.

Example:

"Goodwill disbursement for delayed shipment."

externalReferenceId

string

An identifier from your system for tracking this disbursement. Not shown to the recipient. Must not contain personally identifiable information (PII) or payment credentials.

Maximum string length: 256

Example:

"disbursement-2026-04-1234"

customerDisplay

Operation Customer Display · object

Display information shown to the recipient for this disbursement. If referenceCode is omitted, one is generated.

Show child attributes

Example:

{ "referenceCode": "REF-ABC123" }

metadata

object

Optional metadata as key-value pairs. Use this to store additional structured information on a resource, such as customer IDs, order references, or any application-specific data. Up to 10 key/value pairs may be provided. Keys and values are both strings. Keys must be ≤ 40 characters; values must be ≤ 500 characters.

Show child attributes

Example:

{
  "customer_id": "cust_12345",
  "order_reference": "order-67890"
}

compliance

object

Compliance context for this disbursement. Carries recipient information required by some entity configurations to meet regulatory requirements.

Show child attributes

Example:

{
  "requesterIpAddress": "203.0.113.42",
  "recipient": {
    "name": "Jane Smith",
    "address": {
      "line1": "456 Oak Ave",
      "city": "Austin",
      "state": "TX",
      "postCode": "78701",
      "countryCode": "US"
    }
  }
}

Response

Successfully created disbursement.

A payment from a CDP account you own to a Coinbase user account or an onchain address, independent of a payment session.

disbursementId

string

required

The unique identifier of the disbursement.

Pattern: ^disbursement_[a-f0-9\-]{36}$

Example:

"disbursement_82c879c1-84e1-44ed-a8c2-1ac239cf09ad"

source

Account · object

required

The source from which the disbursement is funded.

Show child attributes

Example:

{
  "accountId": "account_af2937b0-9846-4fe7-bfe9-ccc22d935114",
  "asset": "usdc"
}

target

Disbursement Coinbase Target · object

required

The target receiving the disbursement.

Disbursement Coinbase Target
Disbursement Wallet Target

Show child attributes

Example:

{ "coinbaseUserId": "coinbase_user_abc123" }

amount

string

required

A decimal representation of the disbursed amount, denominated in asset.

Example:

"25.00"

asset

string

required

The symbol of the asset for the disbursement amount.

Required string length: 1 - 42

Example:

"usdc"

status

enum<string>

required

The current status of the disbursement.

Available options:

pending,

succeeded,

failed

Example:

"pending"

createdAt

string<date-time>

required

The UTC ISO 8601 timestamp at which the disbursement was created.

Example:

"2026-04-17T17:00:00.000Z"

updatedAt

string<date-time>

required

The UTC ISO 8601 timestamp at which the disbursement was last updated.

Example:

"2026-04-17T17:00:00.000Z"

reason

string

Human-readable reason for the disbursement.

Example:

"Goodwill disbursement for delayed shipment."

externalReferenceId

string

An identifier from your system for tracking this disbursement. Not shown to the recipient. Must not contain personally identifiable information (PII) or payment credentials.

Maximum string length: 256

Example:

"disbursement-2026-04-1234"

customerDisplay

Operation Customer Display · object

Display information shown to the recipient for this disbursement. If referenceCode was omitted when creating the disbursement, a generated code is returned.

Show child attributes

Example:

{ "referenceCode": "REF-ABC123" }

metadata

object

Show child attributes

Example:

{
  "customer_id": "cust_12345",
  "order_reference": "order-67890"
}

error

object

Error details, present only when the disbursement failed.

Show child attributes

Example:

{
  "code": "insufficient_funds",
  "message": "The source account does not have sufficient funds.",
  "occurredAt": "2026-04-17T17:01:00.000Z"
}

onchainTransactions

object[]

The onchain transactions associated with this disbursement.

Show child attributes

Example:

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