Payments

Payment session webhook events and example payloads.

Payment webhooks track the lifecycle of a payment session.

Use these events to update order state, trigger fulfillment, or handle failed payments.

Field descriptions

Payment webhook events use data.session.

Field	Type	Description
data.session.id	string	Unique session identifier.
data.session.reference	string	Your order or payment reference.
data.session.title	string	Session title.
data.session.description	string | null	Optional session description.
data.session.state	'open' | 'closed'	Session state.
data.session.type	string	Session type.
data.session.amount	string	Requested amount.
data.session.currency	string	Requested currency.
data.session.settlements	object | null	Settlement breakdown when the session settles.
data.session.payment.status	string	Payment status for the session.
data.session.payment.asset	string	Crypto asset code.
data.session.payment.chain	string	Blockchain network.
data.session.payment.amount	string	Required crypto amount.
data.session.payment.amountReceived	string	Actual crypto amount received.
data.session.payment.conversionRate	string	Fiat to crypto conversion rate used.
data.session.payment.gasFee	string	Network gas fee.
data.session.payment.address	string	Deposit address.
data.session.payment.feePaidBy	'merchant' | 'customer'	Who pays the network fee.
data.session.customer	object	Customer information.
data.session.metadata	object | null	Custom metadata.
data.session.successUrl	string	Redirect URL used after success.
data.session.cancelUrl	string	Redirect URL used after cancellation.
data.session.createdAt	string	Creation timestamp.
data.session.expiresAt	string	Expiry timestamp.
data.session.completedAt	string | null	Completion timestamp when available.
data.failureReason	string	Failure reason for payment.failed.

Every payment session event includes customer, metadata, successUrl, and cancelUrl.

Events

• payment.completed
• payment.partial
• payment.expired
• payment.underpaid
• payment.failed

payment.completed

Sent when a payment session is fully paid.

Use this event to mark the order as paid.

This event is sent only when the full required amount is received.

{
  "event": "payment.completed",
  "data": {
    "session": {
      "id": "cs_123456789_abcdef",
      "reference": "ORDER-2024-001",
      "title": "Order #2024-001",
      "description": "Payment for premium subscription",
      "state": "closed",
      "type": "payment",
      "amount": "100.00",
      "currency": "USD",
      "settlements": {
        "currency": "NGN",
        "gross": {
          "amount": "150000.00",
          "conversionRate": "1500.00"
        },
        "fees": {
          "processing": {
            "amount": "1500.00",
            "paidBy": "merchant"
          },
          "gas": {
            "amount": "75.00",
            "paidBy": "customer"
          }
        },
        "net": {
          "amount": "148425.00"
        }
      },
      "payment": {
        "status": "completed",
        "asset": "USDT",
        "chain": "ethereum",
        "amount": "100.55",
        "amountReceived": "100.55",
        "conversionRate": "1.0055",
        "gasFee": "0.05",
        "address": "0x1234567890abcdef1234567890abcdef12345678",
        "feePaidBy": "customer"
      },
      "customer": {
        "id": "123e4567-e89b-12d3-a456-426614174000",
        "email": "[e-mail]",
        "phone": "[phone]",
        "firstName": "John",
        "lastName": "Doe"
      },
      "metadata": {
        "orderId": "ORDER-2024-001",
        "userId": "user_123"
      },
      "successUrl": "https://example.com/success",
      "cancelUrl": "https://example.com/cancel",
      "createdAt": "2024-01-15T10:30:00.000Z",
      "expiresAt": "2024-01-15T11:30:00.000Z",
      "completedAt": "2024-01-15T10:35:00.000Z"
    }
  }
}

payment.partial

Sent when a payment session receives less than the required amount and remains open.

Use this event to notify the customer, track the remaining balance, or keep the order on hold while the session can still accept more payments.

Compare data.session.payment.amountReceived with data.session.payment.amount to calculate the remaining amount due.

{
  "event": "payment.partial",
  "data": {
    "session": {
      "id": "cs_123456789_abcdef",
      "reference": "ORDER-2024-001",
      "title": "Order #2024-001",
      "description": "Payment for premium subscription",
      "state": "open",
      "type": "payment",
      "amount": "100.00",
      "currency": "USD",
      "settlements": null,
      "payment": {
        "status": "partial",
        "asset": "USDT",
        "chain": "ethereum",
        "amount": "100.55",
        "amountReceived": "50.25",
        "conversionRate": "1.0055",
        "gasFee": "0.05",
        "address": "0x1234567890abcdef1234567890abcdef12345678",
        "feePaidBy": "customer"
      },
      "customer": {
        "id": "123e4567-e89b-12d3-a456-426614174000",
        "email": "[e-mail]",
        "phone": "[phone]",
        "firstName": "John",
        "lastName": "Doe"
      },
      "metadata": {
        "orderId": "ORDER-2024-001",
        "userId": "user_123"
      },
      "successUrl": "https://example.com/success",
      "cancelUrl": "https://example.com/cancel",
      "createdAt": "2024-01-15T10:30:00.000Z",
      "expiresAt": "2024-01-15T11:30:00.000Z",
      "completedAt": null
    }
  }
}

payment.expired

Sent when a payment session closes with no payment received.

Use this event to expire checkout state.

{
  "event": "payment.expired",
  "data": {
    "session": {
      "id": "cs_123456789_abcdef",
      "reference": "ORDER-2024-001",
      "title": "Order #2024-001",
      "description": "Payment for premium subscription",
      "state": "closed",
      "type": "payment",
      "amount": "100.00",
      "currency": "USD",
      "settlements": null,
      "payment": {
        "status": "expired",
        "asset": "USDT",
        "chain": "ethereum",
        "amount": "100.55",
        "amountReceived": "0",
        "conversionRate": "1.0055",
        "gasFee": "0.05",
        "address": "0x1234567890abcdef1234567890abcdef12345678",
        "feePaidBy": "customer"
      },
      "customer": {
        "id": "123e4567-e89b-12d3-a456-426614174000",
        "email": "[e-mail]",
        "phone": "[phone]",
        "firstName": "John",
        "lastName": "Doe"
      },
      "metadata": {
        "orderId": "ORDER-2024-001",
        "userId": "user_123"
      },
      "successUrl": "https://example.com/success",
      "cancelUrl": "https://example.com/cancel",
      "createdAt": "2024-01-15T10:30:00.000Z",
      "expiresAt": "2024-01-15T11:30:00.000Z",
      "completedAt": null
    }
  }
}

payment.underpaid

Sent when a payment session closes with less than the required amount.

Use this event when the session is final but still short.

Check data.session.payment.amountReceived for the actual amount received.

{
  "event": "payment.underpaid",
  "data": {
    "session": {
      "id": "cs_123456789_abcdef",
      "reference": "ORDER-2024-001",
      "title": "Order #2024-001",
      "description": "Payment for premium subscription",
      "state": "closed",
      "type": "payment",
      "amount": "100.00",
      "currency": "USD",
      "settlements": null,
      "payment": {
        "status": "partial",
        "asset": "USDT",
        "chain": "ethereum",
        "amount": "100.55",
        "amountReceived": "40.00",
        "conversionRate": "1.0055",
        "gasFee": "0.05",
        "address": "0x1234567890abcdef1234567890abcdef12345678",
        "feePaidBy": "customer"
      },
      "customer": {
        "id": "123e4567-e89b-12d3-a456-426614174000",
        "email": "[e-mail]",
        "phone": "[phone]",
        "firstName": "John",
        "lastName": "Doe"
      },
      "metadata": {
        "orderId": "ORDER-2024-001",
        "userId": "user_123"
      },
      "successUrl": "https://example.com/success",
      "cancelUrl": "https://example.com/cancel",
      "createdAt": "2024-01-15T10:30:00.000Z",
      "expiresAt": "2024-01-15T11:30:00.000Z",
      "completedAt": null
    }
  }
}

payment.failed

Sent when a payment session is rejected after a compliance or AML failure.

Use this event to stop fulfillment and surface the failure.

Check data.failureReason for the rejection reason.

{
  "event": "payment.failed",
  "data": {
    "session": {
      "id": "cs_123456789_abcdef",
      "reference": "ORDER-2024-001",
      "title": "Order #2024-001",
      "description": "Payment for premium subscription",
      "state": "closed",
      "type": "payment",
      "amount": "100.00",
      "currency": "USD",
      "settlements": null,
      "payment": {
        "status": "failed",
        "asset": "USDT",
        "chain": "ethereum",
        "amount": "100.55",
        "amountReceived": "100.55",
        "conversionRate": "1.0055",
        "gasFee": "0.05",
        "address": "0x1234567890abcdef1234567890abcdef12345678",
        "feePaidBy": "customer"
      },
      "customer": {
        "id": "123e4567-e89b-12d3-a456-426614174000",
        "email": "[e-mail]",
        "phone": "[phone]",
        "firstName": "John",
        "lastName": "Doe"
      },
      "metadata": {
        "orderId": "ORDER-2024-001",
        "userId": "user_123"
      },
      "successUrl": "https://example.com/success",
      "cancelUrl": "https://example.com/cancel",
      "createdAt": "2024-01-15T10:30:00.000Z",
      "expiresAt": "2024-01-15T11:30:00.000Z",
      "completedAt": null
    },
    "failureReason": "Session contained flagged transactions"
  }
}