Skip to main content
WEBHOOK
onrampTransactionFailed
{
  "eventType": "onramp.transaction.updated",
  "transactionId": "1f087a54-ff1f-62e8-9f85-aa77ac0499a5",
  "status": "ONRAMP_TRANSACTION_STATUS_IN_PROGRESS",
  "purchaseCurrency": "USDC",
  "purchaseNetwork": "ethereum",
  "purchaseAmount": {
    "currency": "USD",
    "value": "5.00"
  },
  "paymentTotal": {
    "currency": "USD",
    "value": "5.00"
  },
  "paymentTotalUsd": {
    "currency": "USD",
    "value": "5.00"
  },
  "paymentSubtotal": {
    "currency": "USD",
    "value": "5.00"
  },
  "coinbaseFee": {
    "currency": "USD",
    "value": "5.00"
  },
  "networkFee": {
    "currency": "USD",
    "value": "5.00"
  },
  "exchangeRate": {
    "currency": "USD",
    "value": "5.00"
  },
  "txHash": "0x",
  "createdAt": "2025-09-02T02:34:13Z",
  "completedAt": "0001-01-01T00:00:00Z",
  "country": "US",
  "userId": "4132b63ee21128686458155b28570289",
  "paymentMethod": "CARD",
  "walletAddress": "0xe0512E358C347cc2b1A42d057065CE642068b7Ba",
  "type": "ONRAMP_TRANSACTION_TYPE_BUY_AND_SEND",
  "userType": "USER_TYPE_GUEST",
  "partnerUserRef": "example_user_ref",
  "contractAddress": "",
  "failureReason": "FAILURE_REASON_UNSPECIFIED",
  "endPartnerName": "",
  "errorCode": "ERROR_CODE_UNSPECIFIED"
}

Authorizations

​
X-Hook0-Signature
string
header
required

HMAC-SHA256 signature of the raw request body, computed using your webhook secret. Webhook receivers should always verify this header before processing the event. The header value is hex-encoded and prefixed by the algorithm and timestamp, e.g. t=1700000000,v1=abc123... (refer to the Webhook Security docs for the exact verification algorithm).

This scheme applies to webhook delivery (outbound POSTs from CDP to your endpoint), not to inbound CDP API requests.

Body

application/json

The onramp.transaction.failed webhook event payload.

Webhook payload for all onramp transaction events (created, updated, success, failed). Shape depends on transaction type — standard flow (guest checkout / authorized) uses OnrampTransactionPayload, Headless API (Apple Pay / Google Pay) uses OnrampOrderPayload. Distinguish by presence of orderId (Headless) vs transactionId (standard).

​
eventType
string
required

The webhook event type.

Example:

"onramp.transaction.updated"

​
transactionId
string
required

Unique transaction identifier.

Example:

"1f087a54-ff1f-62e8-9f85-aa77ac0499a5"

​
status
enum<string>
required

Current status of the transaction.

Available options:
ONRAMP_TRANSACTION_STATUS_UNSPECIFIED,
ONRAMP_TRANSACTION_STATUS_CREATED,
ONRAMP_TRANSACTION_STATUS_IN_PROGRESS,
ONRAMP_TRANSACTION_STATUS_SUCCESS,
ONRAMP_TRANSACTION_STATUS_FAILED,
ONRAMP_TRANSACTION_STATUS_AWAITING_AUTH,
ONRAMP_TRANSACTION_STATUS_AWAITING_PAYMENT
Example:

"ONRAMP_TRANSACTION_STATUS_IN_PROGRESS"

​
purchaseCurrency
string

The crypto currency purchased (e.g., "USDC", "ETH").

Example:

"USDC"

​
purchaseNetwork
string

The blockchain network for the purchase (e.g., "ethereum", "base").

Example:

"ethereum"

​
purchaseAmount
object

A monetary amount with currency.

Example:
{ "currency": "USD", "value": "5.00" }
​
paymentTotal
object

A monetary amount with currency.

Example:
{ "currency": "USD", "value": "5.00" }
​
paymentTotalUsd
object

A monetary amount with currency.

Example:
{ "currency": "USD", "value": "5.00" }
​
paymentSubtotal
object

A monetary amount with currency.

Example:
{ "currency": "USD", "value": "5.00" }
​
coinbaseFee
object

A monetary amount with currency.

Example:
{ "currency": "USD", "value": "5.00" }
​
networkFee
object

A monetary amount with currency.

Example:
{ "currency": "USD", "value": "5.00" }
​
exchangeRate
object

A monetary amount with currency.

Example:
{ "currency": "USD", "value": "5.00" }
​
txHash
string

The onchain transaction hash of the send (0x-prefixed for EVM).

Example:

"0x"

​
createdAt
string<date-time>

When the transaction was created.

Example:

"2025-09-02T02:34:13Z"

​
completedAt
string<date-time>

When the transaction completed (uses send_started_at for early success).

Example:

"0001-01-01T00:00:00Z"

​
country
string

The user's country code.

Example:

"US"

​
userId
string

Hashed user identifier (entity hash for guest, user ID for authed).

Example:

"4132b63ee21128686458155b28570289"

​
paymentMethod
enum<string>

The payment method used.

Available options:
UNSPECIFIED,
CARD,
ACH_BANK_ACCOUNT,
APPLE_PAY,
FIAT_WALLET,
CRYPTO_ACCOUNT,
GUEST_CHECKOUT_CARD,
PAYPAL,
RTP,
GUEST_CHECKOUT_APPLE_PAY,
GUEST_CHECKOUT_GOOGLE_PAY
Example:

"CARD"

​
walletAddress
string

The destination wallet address.

Example:

"0xe0512E358C347cc2b1A42d057065CE642068b7Ba"

​
type
enum<string>

The type of onramp transaction.

Available options:
ONRAMP_TRANSACTION_TYPE_UNSPECIFIED,
ONRAMP_TRANSACTION_TYPE_BUY_AND_SEND,
ONRAMP_TRANSACTION_TYPE_SEND
Example:

"ONRAMP_TRANSACTION_TYPE_BUY_AND_SEND"

​
userType
enum<string>

Whether the user is authed or guest.

Available options:
USER_TYPE_UNSPECIFIED,
USER_TYPE_AUTHED,
USER_TYPE_GUEST
Example:

"USER_TYPE_GUEST"

​
partnerUserRef
string

The partnerUserId provided when initializing the onramp session.

Example:

"example_user_ref"

​
contractAddress
string

The token contract address (populated when asset metadata is available).

Example:

""

​
failureReason
enum<string>

The reason for failure (if applicable).

Available options:
FAILURE_REASON_UNSPECIFIED,
FAILURE_REASON_BUY_FAILED,
FAILURE_REASON_SEND_FAILED
Example:

"FAILURE_REASON_UNSPECIFIED"

​
endPartnerName
string

The name of the developer app.

Example:

""

​
errorCode
string

Error code for the transaction failure (if applicable).

Example:

"ERROR_CODE_UNSPECIFIED"

Response

Webhook received and processed successfully.