Transfer status changed

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.

Body

application/json

The updated transfer object with the new status.

Webhook event payload sent when a transfer's status changes. This is the structure of the request body sent to your configured webhook URL.

eventType

enum<string>

required

The type of webhook event.

Available options:

transfer.status_changed

Example:

"transfer.status_changed"

eventId

string<uuid>

required

Unique identifier for this webhook event. Use this for idempotency.

Example:

"123e4567-e89b-12d3-a456-426614174000"

timestamp

string<date-time>

required

When this event occurred (ISO 8601 format).

Example:

"2025-01-01T00:05:00Z"

data

object

required

A Transfer represents all the information needed to execute a transfer and tracks the lifecycle of a transfer from initiation through completion or failure.

Show child attributes

data.transferId

string

required

The ID of the transfer.

Example:

"transfer_af2937b0-9846-4fe7-bfe9-ccc22d935114"

data.status

enum<string>

required

The current status of the transfer, indicating what action you need to take next.

Available options:

draft,

awaiting_funds,

processing,

completed,

failed,

canceled,

expired,

reversed

Example:

"draft"

data.source

Account · object

required

The source of the transfer.

Account
Payment Method

Show child attributes

data.source.accountId

string

required

The ID of the Account.

data.source.asset

string

required

The asset symbol.

Example:

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

data.target

Account · object

required

The target of the transfer.

Account
Payment Method
Onchain Address
Email Address

Show child attributes

data.target.accountId

string

required

The ID of the Account.

data.target.asset

string

required

The asset symbol.

Example:

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

data.amount

string

required

The amount to transfer in atomic units of the asset specified by asset.

Example:

"100.00"

data.asset

string

required

The symbol of the asset for the amount. This must be one of the assets of the source or target.

Example:

"usd"

data.createdAt

string<date-time>

required

The date and time the transfer was created.

Example:

"2025-01-01T00:00:00Z"

data.updatedAt

string<date-time>

required

The date and time the transfer was last updated.

Example:

"2025-01-01T00:00:00Z"

data.sourceAmount

string

The amount of the source asset that will be transferred out in atomic units.

Example:

"103.50"

data.sourceAsset

string

The asset symbol of the source amount.

Example:

"usd"

data.targetAmount

string

The amount of the target asset that will be transferred in atomic units.

Example:

"100.00"

data.targetAsset

string

The asset symbol of the target amount.

Example:

"usdc"

data.exchangeRate

object

Exchange rate information for currency conversion. The rate indicates how much of the target asset is equivalent to one unit of the source asset.

Show child attributes

data.exchangeRate.sourceAsset

string

required

The asset being converted from.

Example:

"usd"

data.exchangeRate.targetAsset

string

required

The asset being converted to.

Example:

"usdc"

data.exchangeRate.rate

string

required

The exchange rate value as a decimal string. Indicates how many units of the target asset equal one unit of the source asset.

Example:

"1"

Example:

{
  "sourceAsset": "usd",
  "targetAsset": "usdc",
  "rate": "1"
}

data.fees

object[]

The fees associated with this transfer. Different transfer types have different fee structures.

NOTE: These examples are not exhaustive.

Common examples:

Crypto transfers: Network fees (gas) paid in the native token
Fiat conversions: Processing fees + exchange fees in USD
Wire transfers: Wire fees ($15) + processing fees ($5) in USD
Crypto conversions: Spread fees paid in the source asset.

A single fee for a transfer.

Show child attributes

name

enum<string>

required

The name of the fee, indicating its purpose.

Available options:

network_fee,

processing_fee,

wire_fee,

exchange_fee,

spread_fee

Example:

"network_fee"

amount

string

required

The amount of the fee in units of the asset specified by asset.

Example:

"1500000"

asset

string

required

The asset symbol.

Example:

"btc"

Example:

[
  {
    "name": "processing_fee",
    "amount": "2.50",
    "asset": "usd"
  },
  {
    "name": "exchange_fee",
    "amount": "1.00",
    "asset": "usd"
  }
]

data.onchainTransactions

object[]

List of onchain transactions executed as part of this transfer. Present when the transfer involves onchain operations and has completed processing.

Represents a transaction that has been broadcast to a network. Contains the transaction hash and network to track a transaction's status and details.

Show child attributes

txHash

string

required

The unique transaction hash.

Example:

"0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef"

network

enum<string>

required

The blockchain network for the payment.

Available options:

base,

ethereum,

algorand,

aptos,

arbitrum,

avacchain,

noble,

optimism,

polygon,

solana,

stellar,

sui,

unichain

Example:

"base"

Example:

{
  "txHash": "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef",
  "network": "ethereum"
}

Example:

[
  {
    "txHash": "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef",
    "network": "ethereum"
  }
]

data.completedAt

string<date-time>

The date and time the transfer was completed.

Example:

"2025-01-01T00:05:00Z"

data.failureReason

string

The reason for failure, if the transfer failed. Only present when status is failed.

Example:

"Insufficient balance to complete this transfer."

data.reversalReason

enum<string>

The reason for reversal, if the transfer was reversed. Only present when status is reversed.

Available options:

user_requested,

compliance_reversal,

fraud_reversal,

network_reversal,

system_reversal

Example:

"user_requested"

data.cancellationReason

enum<string>

The reason for cancellation, if the transfer was canceled. Only present when status is canceled.

Available options:

user_canceled,

system_canceled,

expired,

compliance_canceled,

risk_canceled,

duplicate_canceled,

insufficient_funds_canceled

Example:

"user_canceled"

data.lastError

object

Detailed information about the last error that occurred while processing this transfer. Only present when status is failed.

Show child attributes

data.lastError.code

string

A specific error code identifying the type of error.

Example:

"insufficient_funds"

data.lastError.message

string

A human-readable description of the error.

Example:

"The source account does not have sufficient funds for this transfer."

data.lastError.param

string

The parameter that caused this error, if applicable.

Example:

"source.accountId"

data.lastError.details

object

Additional context about the error.

Show child attributes

data.lastError.details.availableBalance

string

Available balance when error is insufficient_funds.

Example:

"50.00"

data.lastError.details.requiredAmount

string

Required amount when error is insufficient_funds.

Example:

"100.00"

data.lastError.details.retryAfter

integer

Seconds to wait before retrying when rate limited.

Example:

300

Example:

{
  "code": "insufficient_funds",
  "message": "The source account does not have sufficient funds for this transfer.",
  "param": "source.accountId",
  "details": {
    "availableBalance": "50.00",
    "requiredAmount": "100.00"
  }
}

data.expiresAt

string<date-time>

The date and time when this transfer will expire if not executed. Only present for draft and awaiting_funds statuses. After expiration, the transfer will move to expired status.

Example:

"2025-01-01T00:15:00Z"

data.executedAt

string<date-time>

The date and time the transfer was executed and moved to processing. Only present when status has progressed beyond draft.

Example:

"2025-01-01T00:01:30Z"

data.validateOnly

boolean

(Preview, not yet supported) If true, validates the transfer without initiating it. If the request is valid, a 2xx will be returned. If the request is invalid, a 4xx error will be returned. The response will include an errorType, for e.g. invalid_target if the specified target cannot receive funds.

Example:

false

data.metadata

object

(Preview, not yet supported) Key-value pairs of metadata about the transfer. Up to 5 key/value pairs may be provided. Each key and value must be less than or equal 100 characters.

Example:

{
  "invoiceId": "12345",
  "reference": "Payment for invoice #12345"
}

data.travelRule

object

(Preview, not yet supported) Required Travel Rule fields differ by region. These requirements are determined based on which Coinbase entity the customer has signed the service agreement for.

Show child attributes

data.travelRule.originator

object

Originator (sender) party.

Show child attributes

data.travelRule.originator.name

string

Full name of the party.

Example:

"John Doe"

data.travelRule.originator.address

object

Address information for travel rule compliance.

Show child attributes

data.travelRule.originator.address.address1

string

Primary address line.

Example:

"123 Main St"

data.travelRule.originator.address.address2

string

Secondary address line (optional).

Example:

"Unit 201"

data.travelRule.originator.address.city

string

City name.

Example:

"Luxembourg"

data.travelRule.originator.address.postalCode

string

Postal or ZIP code.

Example:

"L-1234"

data.travelRule.originator.address.country

string

Two-letter ISO country code.

Example:

"LU"

Example:

{
  "address1": "123 Main St",
  "address2": "Unit 201",
  "city": "Luxembourg",
  "postalCode": "L-1234",
  "country": "LU"
}

data.travelRule.originator.financialInstitution

string

Name of the financial institution (optional).

Example:

"Citibank"

Example:

{
  "name": "John Doe",
  "address": {
    "address1": "123 Main St",
    "address2": "Unit 201",
    "city": "Luxembourg",
    "postalCode": "L-1234",
    "country": "LU"
  }
}

data.travelRule.beneficiary

object

Beneficiary (receiver) party.

Show child attributes

data.travelRule.beneficiary.name

string

Full name of the party.

Example:

"John Doe"

data.travelRule.beneficiary.address

object

Address information for travel rule compliance.

Show child attributes

data.travelRule.beneficiary.address.address1

string

Primary address line.

Example:

"123 Main St"

data.travelRule.beneficiary.address.address2

string

Secondary address line (optional).

Example:

"Unit 201"

data.travelRule.beneficiary.address.city

string

City name.

Example:

"Luxembourg"

data.travelRule.beneficiary.address.postalCode

string

Postal or ZIP code.

Example:

"L-1234"

data.travelRule.beneficiary.address.country

string

Two-letter ISO country code.

Example:

"LU"

Example:

{
  "address1": "123 Main St",
  "address2": "Unit 201",
  "city": "Luxembourg",
  "postalCode": "L-1234",
  "country": "LU"
}

Example:

{
  "name": "John Doe",
  "address": {
    "address1": "123 Main St",
    "address2": "Unit 201",
    "city": "Luxembourg",
    "postalCode": "L-1234",
    "country": "LU"
  }
}

Example:

{
  "originator": {
    "name": "John Doe",
    "address": {
      "address1": "123 Main St",
      "address2": "Unit 201",
      "city": "Luxembourg",
      "postalCode": "L-1234",
      "country": "LU"
    },
    "financialInstitution": "Citibank"
  },
  "beneficiary": {
    "name": "Jane Smith",
    "address": {
      "address1": "456 Oak Ave",
      "city": "Paris",
      "postalCode": "75001",
      "country": "FR"
    }
  }
}

CDP PAYMENTS API

REST API

Authorizations

Body