eventId, eventType, timestamp, and data. For payment session events, data.paymentSession always contains a session summary. For action-triggered events, the corresponding action detail is also included as a sibling field: data.authorization, data.capture, data.void, or data.refund.
Payment session events
- Authorization Succeeded
- Authorization Failed
- Capture Succeeded
- Refund Succeeded
- Void Succeeded
- Canceled
Buyer’s funds are held. Ready to capture.
{
"eventId": "evt_a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"eventType": "acceptance.payment_session.authorization_succeeded",
"timestamp": "2026-05-16T12:02:00Z",
"data": {
"paymentSession": {
"paymentSessionId": "paymentSession_82c879c1-84e1-44ed-a8c2-1ac239cf09ad",
"entityId": "entity_af2937b0-9846-4fe7-bfe9-ccc22d935114",
"status": "authorization_succeeded",
"amount": "100.00",
"asset": "usdc",
"target": {
"accountId": "account_af2937b0-9846-4fe7-bfe9-ccc22d935114",
"asset": "usd"
},
"source": {
"address": "0xAbC1234567890aBcDeF1234567890AbCdEf123456",
"network": "base"
},
"balances": {
"capturable": "100.00",
"captured": "0",
"refundable": "0",
"refunded": "0"
},
"externalReferenceId": "order-12345",
"metadata": {
"customer_id": "cust_12345"
},
"createdAt": "2026-05-16T12:00:00.000Z",
"updatedAt": "2026-05-16T12:02:00.000Z"
},
"authorization": {
"authorizationId": "authorization_93d980d2-95f2-55fe-b9d3-2bd340cf10be",
"status": "succeeded",
"amount": "100.00",
"source": {
"address": "0xAbC1234567890aBcDeF1234567890AbCdEf123456",
"network": "base"
},
"onchainTransactions": [
{
"transactionHash": "0xabc123def456789012345678901234567890abcdef1234567890abcdef123456",
"network": "base"
}
],
"createdAt": "2026-05-16T12:01:00.000Z",
"updatedAt": "2026-05-16T12:02:00.000Z"
}
}
}
Authorization could not be completed.
{
"eventId": "evt_b2c3d4e5-f6a7-8901-bcde-f12345678901",
"eventType": "acceptance.payment_session.authorization_failed",
"timestamp": "2026-05-16T12:02:00Z",
"data": {
"paymentSession": {
"paymentSessionId": "paymentSession_82c879c1-84e1-44ed-a8c2-1ac239cf09ad",
"entityId": "entity_af2937b0-9846-4fe7-bfe9-ccc22d935114",
"status": "authorization_failed",
"amount": "100.00",
"asset": "usdc",
"target": {
"accountId": "account_af2937b0-9846-4fe7-bfe9-ccc22d935114",
"asset": "usd"
},
"balances": {
"capturable": "0",
"captured": "0",
"refundable": "0",
"refunded": "0"
},
"createdAt": "2026-05-16T12:00:00.000Z",
"updatedAt": "2026-05-16T12:02:00.000Z"
},
"authorization": {
"authorizationId": "authorization_93d980d2-95f2-55fe-b9d3-2bd340cf10be",
"status": "failed",
"amount": "100.00",
"error": {
"code": "insufficient_funds",
"message": "The payer does not have sufficient funds.",
"occurredAt": "2026-05-16T12:02:00.000Z"
},
"createdAt": "2026-05-16T12:01:00.000Z",
"updatedAt": "2026-05-16T12:02:00.000Z"
}
}
}
Funds captured and settled.
{
"eventId": "evt_c3d4e5f6-a7b8-9012-cdef-123456789012",
"eventType": "acceptance.payment_session.capture_succeeded",
"timestamp": "2026-05-16T12:06:00Z",
"data": {
"paymentSession": {
"paymentSessionId": "paymentSession_82c879c1-84e1-44ed-a8c2-1ac239cf09ad",
"entityId": "entity_af2937b0-9846-4fe7-bfe9-ccc22d935114",
"status": "capture_succeeded",
"amount": "100.00",
"asset": "usdc",
"target": {
"accountId": "account_af2937b0-9846-4fe7-bfe9-ccc22d935114",
"asset": "usd"
},
"source": {
"address": "0xAbC1234567890aBcDeF1234567890AbCdEf123456",
"network": "base"
},
"balances": {
"capturable": "0",
"captured": "100.00",
"refundable": "100.00",
"refunded": "0"
},
"externalReferenceId": "order-12345",
"createdAt": "2026-05-16T12:00:00.000Z",
"updatedAt": "2026-05-16T12:06:00.000Z"
},
"capture": {
"captureId": "capture_a4eaa1f3-c6a4-77f9-d1f5-4df562df32df",
"status": "succeeded",
"amount": "100.00",
"onchainTransactions": [
{
"transactionHash": "0xdef456abc789012345678901234567890abcdef1234567890abcdef12345678",
"network": "base"
}
],
"createdAt": "2026-05-16T12:05:00.000Z",
"updatedAt": "2026-05-16T12:06:00.000Z"
}
}
}
Captured funds returned to the buyer.
{
"eventId": "evt_d4e5f6a7-b8c9-0123-def0-234567890123",
"eventType": "acceptance.payment_session.refund_succeeded",
"timestamp": "2026-05-16T14:00:00Z",
"data": {
"paymentSession": {
"paymentSessionId": "paymentSession_82c879c1-84e1-44ed-a8c2-1ac239cf09ad",
"entityId": "entity_af2937b0-9846-4fe7-bfe9-ccc22d935114",
"status": "refund_succeeded",
"amount": "100.00",
"asset": "usdc",
"target": {
"accountId": "account_af2937b0-9846-4fe7-bfe9-ccc22d935114",
"asset": "usd"
},
"source": {
"address": "0xAbC1234567890aBcDeF1234567890AbCdEf123456",
"network": "base"
},
"balances": {
"capturable": "0",
"captured": "100.00",
"refundable": "50.00",
"refunded": "50.00"
},
"externalReferenceId": "order-12345",
"createdAt": "2026-05-16T12:00:00.000Z",
"updatedAt": "2026-05-16T14:00:00.000Z"
},
"refund": {
"refundId": "refund_b5fbb2f4-d7a5-88af-e2f6-5ef673ef43ef",
"status": "succeeded",
"amount": "50.00",
"reason": "Customer returned item",
"onchainTransactions": [
{
"transactionHash": "0x012345678901234567890abcdef1234567890abcdef1234567890abcdef1234",
"network": "base"
}
],
"createdAt": "2026-05-16T13:55:00.000Z",
"updatedAt": "2026-05-16T14:00:00.000Z"
}
}
}
Uncaptured authorized funds released back to the buyer.
{
"eventId": "evt_e5f6a7b8-c9d0-1234-ef01-345678901234",
"eventType": "acceptance.payment_session.void_succeeded",
"timestamp": "2026-05-16T12:35:00Z",
"data": {
"paymentSession": {
"paymentSessionId": "paymentSession_82c879c1-84e1-44ed-a8c2-1ac239cf09ad",
"entityId": "entity_af2937b0-9846-4fe7-bfe9-ccc22d935114",
"status": "void_succeeded",
"amount": "100.00",
"asset": "usdc",
"target": {
"accountId": "account_af2937b0-9846-4fe7-bfe9-ccc22d935114",
"asset": "usd"
},
"balances": {
"capturable": "0",
"captured": "0",
"refundable": "0",
"refunded": "0"
},
"createdAt": "2026-05-16T12:00:00.000Z",
"updatedAt": "2026-05-16T12:35:00.000Z"
},
"void": {
"voidId": "void_c6gcc3g5-e8b6-99bg-f3g7-6fg784fg54fg",
"status": "succeeded",
"amount": "100.00",
"onchainTransactions": [
{
"transactionHash": "0x789012345678901234567890abcdef1234567890abcdef1234567890abcdef12",
"network": "base"
}
],
"createdAt": "2026-05-16T12:30:00.000Z",
"updatedAt": "2026-05-16T12:35:00.000Z"
}
}
}
Void webhook events are reserved for future use and are not yet emitted.
Session canceled before authorization. Session-level events like this one have no action detail field — the
paymentSession.status value is sufficient.{
"eventId": "evt_f6a7b8c9-d0e1-2345-f012-456789012345",
"eventType": "acceptance.payment_session.canceled",
"timestamp": "2026-05-16T12:10:00Z",
"data": {
"paymentSession": {
"paymentSessionId": "paymentSession_82c879c1-84e1-44ed-a8c2-1ac239cf09ad",
"entityId": "entity_af2937b0-9846-4fe7-bfe9-ccc22d935114",
"status": "canceled",
"amount": "100.00",
"asset": "usdc",
"target": {
"accountId": "account_af2937b0-9846-4fe7-bfe9-ccc22d935114",
"asset": "usd"
},
"balances": {
"capturable": "0",
"captured": "0",
"refundable": "0",
"refunded": "0"
},
"createdAt": "2026-05-16T12:00:00.000Z",
"updatedAt": "2026-05-16T12:10:00.000Z"
}
}
}
Disbursement events
- Succeeded
- Failed
Disbursement settled onchain.
{
"eventId": "evt_g7b8c9d0-e1f2-3456-0123-567890123456",
"eventType": "acceptance.disbursement.succeeded",
"timestamp": "2026-05-16T17:05:00Z",
"data": {
"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": "succeeded",
"reason": "Goodwill credit for delayed shipment",
"externalReferenceId": "credit-2026-05-1234",
"metadata": {
"customer_id": "cust_12345"
},
"onchainTransactions": [
{
"transactionHash": "0xabc123def456789012345678901234567890abcdef1234567890abcdef123456",
"network": "base"
}
],
"createdAt": "2026-05-16T17:00:00.000Z",
"updatedAt": "2026-05-16T17:05:00.000Z"
}
}
Disbursement could not be completed.
{
"eventId": "evt_h8c9d0e1-f2a3-4567-1234-678901234567",
"eventType": "acceptance.disbursement.failed",
"timestamp": "2026-05-16T17:01:00Z",
"data": {
"disbursementId": "disbursement_93d980d2-95f2-55fe-b9d3-2bd340cf10be",
"source": {
"accountId": "account_af2937b0-9846-4fe7-bfe9-ccc22d935114",
"asset": "usdc"
},
"target": {
"coinbaseUserId": "coinbase_user_def456"
},
"amount": "50.00",
"asset": "usdc",
"status": "failed",
"reason": "Refund for order cancellation",
"error": {
"code": "insufficient_funds",
"message": "The source account does not have sufficient funds.",
"occurredAt": "2026-05-16T17:01:00.000Z"
},
"createdAt": "2026-05-16T17:00:00.000Z",
"updatedAt": "2026-05-16T17:01:00.000Z"
}
}
Mandate events
For mandate events,data.mandate always contains the full mandate. Approval events also include data.approval, and revocation events include data.revocation. The created and canceled events carry only the mandate.
- Approval Succeeded
- Canceled
The customer approved the mandate. You can now authorize payments with it.
{
"eventId": "evt_i9d0e1f2-a3b4-5678-2345-789012345678",
"eventType": "acceptance.mandate.approval_succeeded",
"timestamp": "2026-06-15T12:05:00Z",
"data": {
"mandate": {
"mandateId": "mandate_82c879c1-84e1-44ed-a8c2-1ac239cf09ad",
"asset": "usdc",
"source": {
"address": "0xAbC1234567890aBcDeF1234567890AbCdEf123456",
"network": "base",
"asset": "usdc"
},
"policy": {
"maxPerAuthorization": "50.00",
"maxPerPeriod": {
"amount": "100.00",
"period": "month"
}
},
"status": "approval_succeeded",
"metadata": {
"customer_id": "cust_12345"
},
"approvedAt": "2026-06-15T12:05:00.000Z",
"createdAt": "2026-06-15T12:00:00.000Z",
"updatedAt": "2026-06-15T12:05:00.000Z"
},
"approval": {
"approvalId": "approval_5f0e9d8c-7b6a-4321-fedc-ba0987654321",
"status": "succeeded",
"source": {
"address": "0xAbC1234567890aBcDeF1234567890AbCdEf123456",
"network": "base",
"asset": "usdc"
},
"onchainTransactions": [
{
"transactionHash": "0xabc123def456789012345678901234567890abcdef1234567890abcdef123456",
"network": "base"
}
],
"createdAt": "2026-06-15T12:04:00.000Z",
"updatedAt": "2026-06-15T12:05:00.000Z"
}
}
}
You canceled the mandate. No further payments can be authorized with it.
{
"eventId": "evt_j0e1f2a3-b4c5-6789-3456-890123456789",
"eventType": "acceptance.mandate.canceled",
"timestamp": "2026-08-21T14:02:00Z",
"data": {
"mandate": {
"mandateId": "mandate_82c879c1-84e1-44ed-a8c2-1ac239cf09ad",
"asset": "usdc",
"source": {
"address": "0xAbC1234567890aBcDeF1234567890AbCdEf123456",
"network": "base",
"asset": "usdc"
},
"policy": {
"maxPerAuthorization": "50.00",
"maxPerPeriod": {
"amount": "100.00",
"period": "month"
}
},
"status": "canceled",
"metadata": {
"customer_id": "cust_12345"
},
"approvedAt": "2026-06-15T12:05:00.000Z",
"canceledAt": "2026-08-21T14:02:00.000Z",
"createdAt": "2026-06-15T12:00:00.000Z",
"updatedAt": "2026-08-21T14:02:00.000Z"
}
}
}
OAuth and identity events
These events apply to Pay with Coinbase. Keys indata can change over time, so ignore keys you don’t recognize.
- Sign-in completed
- MFA completed
- MFA canceled
- Token revoked
- User updated
- User deleted
The customer signed in or signed up, and consented on Coinbase. Call
confirm-link next.{
"eventId": "9b2e4f1a-6c3d-4e8b-a7f0-2d5c8e1b4a93",
"eventType": "oauth.sign_in.completed",
"timestamp": "2026-08-12T09:10:00Z",
"data": {
"clientId": "YOUR_OAUTH_CLIENT_ID",
"externalReferenceId": "link_ref_123",
"intent": "signin"
}
}
externalReferenceId is the external_reference you sent to init-oauth-session. intent is signup or signin, the flow Coinbase sent the customer to. It’s omitted when Coinbase can’t determine the flow, so don’t require it. signup doesn’t prove that the customer created a new account.The customer completed the 2FA challenge. Submit the authorization next.
{
"eventId": "4c8a1e2f-7b3d-4f9a-8e6c-1d2b3a4c5e6f",
"eventType": "oauth.mfa.completed",
"timestamp": "2026-08-12T09:12:00Z",
"data": {
"clientId": "YOUR_OAUTH_CLIENT_ID",
"externalReferenceId": "order-12345"
}
}
externalReferenceId is the operationParameters.externalReferenceId you sent when you started the authorization challenge, not the linking reference. Set it on every challenge so you can match the event to the payment.The customer abandoned the 2FA challenge. Start a new challenge to retry.
{
"eventId": "5d9b2f3a-8c4e-4a0b-9f7d-2e3c4b5d6f7a",
"eventType": "oauth.mfa.canceled",
"timestamp": "2026-08-12T09:12:00Z",
"data": {
"clientId": "YOUR_OAUTH_CLIENT_ID",
"externalReferenceId": "order-12345"
}
}
The customer disconnected your app from their Coinbase account. It doesn’t fire when you call The payload has no Coinbase user ID. Find the customer with
/oauth2/revoke.{
"eventId": "123e4567-e89b-12d3-a456-426614174000",
"eventType": "oauth.token.revoked",
"timestamp": "2025-06-15T12:00:15.000Z",
"data": {
"clientId": "YOUR_OAUTH_CLIENT_ID",
"externalReferenceId": "link_ref_123"
}
}
externalReferenceId, the external_reference you sent to init-oauth-session.Don’t rely on this event alone. Also treat invalid_grant on refresh as a revoked link. A 401 on authorization can mean the access token expired, so refresh once and retry first.The customer changed their Coinbase profile.
changedFields lists what changed: name, email, address, or nickname. The new values aren’t included, so fetch the profile with the customer’s OAuth token.{
"eventId": "3a7f8b2e-1c4d-4e9a-b5f6-d8a2c0e7f194",
"eventType": "identity.user.updated",
"timestamp": "2026-08-12T09:15:00Z",
"data": {
"coinbaseUserId": "38d54acb-0868-431c-a88e-1ffcb62655eb",
"changedFields": ["name", "address"]
}
}
The customer’s Coinbase account was closed and their personal data removed. The event can arrive some time after closure, and no further events follow. Stop processing payments for this customer.
{
"eventId": "7e1c9a4b-2f6d-4b8e-9a3c-5d0f2e8b1c76",
"eventType": "identity.user.deleted",
"timestamp": "2026-08-12T09:15:00Z",
"data": {
"coinbaseUserId": "38d54acb-0868-431c-a88e-1ffcb62655eb"
}
}
This page shows full incoming webhook request bodies (
eventId, eventType, timestamp, data). See the API Reference for complete field definitions.Related
Webhook Subscriptions
Create and manage webhook subscriptions
Verification
Verify webhook signatures