Skip to main content
WEBHOOK
paymentSessionChanged
{
  "eventType": "acceptance.payment_session.created",
  "eventId": "012d3456-a78b-01c2-d345-214503063000",
  "timestamp": "2025-06-15T11:58:00.000Z",
  "data": {
    "paymentSession": {
      "paymentSessionId": "paymentSession_82c879c1-84e1-44ed-a8c2-1ac239cf09ad",
      "entityId": "entity_af2937b0-9846-4fe7-bfe9-ccc22d935114",
      "amount": "1.00",
      "asset": "usdc",
      "target": {
        "address": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
        "network": "base"
      },
      "autoCapture": false,
      "expiries": {
        "authorizationExpiresAt": "2025-12-31T23:59:59.000Z",
        "captureExpiresAt": "2026-01-15T23:59:59.000Z",
        "refundExpiresAt": "2026-02-15T23:59:59.000Z"
      },
      "status": "created",
      "balances": {
        "capturable": "0",
        "captured": "0",
        "refundable": "0",
        "refunded": "0"
      },
      "externalReferenceId": "merchant-order-abc123",
      "metadata": {
        "customer_id": "cust_12345",
        "order_reference": "order-67890"
      },
      "createdAt": "2025-06-15T11:58:00.000Z",
      "updatedAt": "2025-06-15T11:58:00.000Z"
    }
  }
}

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 payment session summary with optional action details. The paymentSession field is always present. When the status change was triggered by an action, the corresponding detail field is also present.

Webhook event payload sent whenever a payment session's status changes. Each status transition has its own event type, allowing subscribers to selectively receive only the events they care about. When the transition was triggered by an action, the corresponding field (authorization, capture, void, or refund) is present with details.

​
eventType
enum<string>
required

The type of webhook event. Each payment session status transition maps to a distinct event type in the acceptance.payment_session.* family. Void event types are reserved for future use and are not yet emitted.

Available options:
acceptance.payment_session.created,
acceptance.payment_session.canceled,
acceptance.payment_session.authorization_pending,
acceptance.payment_session.authorization_succeeded,
acceptance.payment_session.authorization_failed,
acceptance.payment_session.capture_pending,
acceptance.payment_session.capture_succeeded,
acceptance.payment_session.capture_failed,
acceptance.payment_session.refund_pending,
acceptance.payment_session.refund_succeeded,
acceptance.payment_session.refund_failed,
acceptance.payment_session.void_pending,
acceptance.payment_session.void_succeeded,
acceptance.payment_session.void_failed
Example:

"acceptance.payment_session.authorization_succeeded"

​
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-06-15T12:01:00.000Z"

​
data
object
required

The data payload for a payment session webhook event. Always contains the paymentSession summary reflecting the session's current state. When the event was triggered by an action (authorization, capture, void, or refund), the corresponding optional field is present with the action details. For session-level events (created, canceled) no action field is included — the paymentSession.status value is sufficient.

Example:
{
  "paymentSession": {
    "paymentSessionId": "paymentSession_82c879c1-84e1-44ed-a8c2-1ac239cf09ad",
    "entityId": "entity_af2937b0-9846-4fe7-bfe9-ccc22d935114",
    "amount": "1.00",
    "asset": "usdc",
    "source": {
      "address": "0xAbC1234567890aBcDeF1234567890AbCdEf123456",
      "network": "base",
      "asset": "usdc"
    },
    "target": {
      "address": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
      "network": "base"
    },
    "autoCapture": false,
    "expiries": {
      "authorizationExpiresAt": "2025-12-31T23:59:59.000Z",
      "captureExpiresAt": "2026-01-15T23:59:59.000Z",
      "refundExpiresAt": "2026-02-15T23:59:59.000Z"
    },
    "status": "authorization_succeeded",
    "balances": {
      "capturable": "1.00",
      "captured": "0",
      "refundable": "0",
      "refunded": "0"
    },
    "externalReferenceId": "merchant-order-abc123",
    "metadata": {
      "customer_id": "cust_12345",
      "order_reference": "order-67890"
    },
    "createdAt": "2025-06-15T12:00:00.000Z",
    "updatedAt": "2025-06-15T12:01:00.000Z"
  },
  "authorization": {
    "authorizationId": "authorization_82c879c1-84e1-44ed-a8c2-1ac239cf09ad",
    "status": "succeeded",
    "amount": "1.00",
    "source": {
      "address": "0xAbC1234567890aBcDeF1234567890AbCdEf123456",
      "network": "base",
      "asset": "usdc"
    },
    "onchainTransactions": [
      {
        "transactionHash": "0xabc123def456789012345678901234567890abcdef1234567890abcdef123456",
        "network": "base"
      }
    ],
    "createdAt": "2025-06-15T12:00:30.000Z",
    "updatedAt": "2025-06-15T12:01:00.000Z"
  }
}

Response

Webhook received and processed successfully. Return a 200 status code to acknowledge receipt. If your endpoint does not return a 2xx status code, the webhook will be retried with exponential backoff.