Event types

#The event object

Every delivery's body is one event:

{
  "id": "evt_4Qm8ZsUe2VhNc7RwTb1Y",
  "type": "payment.paid",
  "created": 1790381342,
  "livemode": true,
  "data": {
    "payment": {
      "id": "pay_7AAiYH0Ykt11ED4hmfiN",
      "mode": "live",
      "source": "api",
      "checkoutId": null,
      "planLabel": null,
      "description": "Pro Membership",
      "reference": "order_1042",
      "customerEmail": "buyer@example.com",
      "amount": "49.00",
      "currency": "USD",
      "status": "paid",
      "provider": "stripe",
      "providerName": "Stripe",
      "depositAddress": "0x5b0e8a3f2d1c4b7a9e6f0d3c2b1a4e7f8d9c0b1a",
      "payoutWallet": "0xF977814e90dA44bFA03b6295A0616a897441aceC",
      "feeBps": 150,
      "valueCoin": "47.53",
      "merchantReceived": "46.341750",
      "coin": "polygon_usdc",
      "holdReason": null,
      "holdAcceptable": false,
      "txidIn": "0x0c651ba1d59c7a32e8b1f4bd2c7e0e4f96a55d13a6b0f2d1c8e7a9b4f3d29b58",
      "txidOut": "0x8202d1373e0a9c4f1b6d5e2c7a8f9b0e1d2c3b4a5f6e7d8c9b0a1f2e3d7356ff",
      "metadata": { "user_id": "player_1042" },
      "customerName": null,
      "memo": null,
      "trackingUrl": null,
      "canceledAt": null,
      "successUrl": "https://yourstore.com/thanks?order={REFERENCE}&payment={PAYMENT_ID}",
      "createdAt": 1790380525000,
      "paidAt": 1790381342000,
      "expiresAt": 1790466925000,
      "url": "https://pay.railbed.io/p/pay_7AAiYH0Ykt11ED4hmfiN",
      "orderId": "ord_M4tQx8ZkP1vRn6WcLs2B"
    },
    "order": {
      "id": "ord_M4tQx8ZkP1vRn6WcLs2B",
      "mode": "live",
      "number": 1186,
      "displayNumber": "#1186",
      "source": "api",
      "checkoutId": null,
      "store": null,
      "status": "paid",
      "needsReview": false,
      "fulfillment": "none",
      "fulfilledAt": null,
      "customer": {
        "id": "cus_Q9wLm3TzX7bKc2VnR5Hd",
        "email": "buyer@example.com",
        "name": null,
        "erased": false
      },
      "summary": "Pro Membership",
      "lineCount": 1,
      "unitCount": 1,
      "currency": "USD",
      "subtotal": "49.00",
      "discount": "0.00",
      "discountCode": null,
      "shipping": "0.00",
      "shippingMethod": null,
      "tax": "0.00",
      "total": "49.00",
      "amountPaid": "49.00",
      "received": "46.341750",
      "shipTo": null,
      "billTo": null,
      "reference": "order_1042",
      "paymentId": "pay_7AAiYH0Ykt11ED4hmfiN",
      "attemptCount": 1,
      "createdAt": 1790380525000,
      "updatedAt": 1790381342000,
      "paidAt": 1790381342000,
      "items": [
        {
          "name": "Pro Membership",
          "variant": null,
          "sku": null,
          "quantity": 1,
          "unitAmount": "49.00",
          "amount": "49.00"
        }
      ]
    },
    "customer": {
      "id": "cus_Q9wLm3TzX7bKc2VnR5Hd",
      "mode": "live",
      "email": "buyer@example.com",
      "name": null,
      "phone": null,
      "location": null,
      "shipTo": null,
      "billTo": null,
      "storeAccounts": [],
      "firstSeenAt": 1790380525000,
      "erased": false
    }
  }
}

The payment, order and customer in an event are a snapshot. Events can arrive late or out of order, so when you need the current state, read the payment or the order.

The order's status already includes the event: on payment.paid it's paid. It follows all of the order's payments, so an event about one attempt can carry an order that another attempt has already paid, such as a payment.expired for a buyer's abandoned first try. Decide what to do from the event's type and the payment; use the order for what to deliver and where.

#Events

#payment.started

The buyer entered their email and was given a way to pay: Railbed assigned the payment's deposit address and locked the fee and the order's USD value. The payment is still open (it becomes pending when the buyer reaches a provider), and provider is usually still null.

Use it for abandoned-checkout follow-ups, or to show "awaiting payment" in your system. Never fulfil from it. A buyer who entered their email only now appears here first: data.customer and data.order.customer are set from it.

{
  "id": "evt_9sPq2XbLr5TtVn0KcWmE",
  "type": "payment.started",
  "created": 1790380611,
  "livemode": true,
  "data": {
    "payment": {
      "id": "pay_7AAiYH0Ykt11ED4hmfiN",
      "status": "open",
      "customerEmail": "buyer@example.com",
      "amount": "49.00",
      "currency": "USD",
      "provider": null,
      "depositAddress": "0x5b0e8a3f2d1c4b7a9e6f0d3c2b1a4e7f8d9c0b1a",
      "feeBps": 150
    }
  }
}

In Test mode, depositAddress is null: no real address is created.

#payment.paid

The money arrived and passed Railbed's checks: at least 90% of the order's value in a dollar coin and, from the processor's signed notice, the right deposit address, your wallet in the payout and a transaction never used before. Or you accepted a held payment as paid. This is the event to fulfil from.

• The full payload is the example in The event object.
• status is paid and paidAt is set.
• valueCoin, coin and txidIn say what arrived; txidOut and merchantReceived say what was forwarded to you.
• If the processor's notice is late, Railbed's scheduled status check can confirm the payment on the coin and amount first. The notice's details are checked when it arrives and fill in txidIn and merchantReceived in a payment.updated; a notice that doesn't match is flagged on the payment's timeline in the dashboard.
• For a held payment you accepted, merchantReceived stays null and no payment.updated follows.

#payment.held

Money arrived but failed a check, most often because less arrived than 90% of the order's value. Don't fulfil. The payment waits for you in the dashboard.

• holdReason says what failed, in plain words.
• holdAcceptable says whether you can Accept as paid in the dashboard. It's false when the evidence shows the money went somewhere else, for example to a wallet that isn't yours.
• If you accept it, a payment.paid follows for the same payment.

{
  "id": "evt_Hq3nW8ZkT1cVbR6sYp0M",
  "type": "payment.held",
  "created": 1790381342,
  "livemode": true,
  "data": {
    "payment": {
      "id": "pay_Kx81mQv2PzR0dT7eWcYa",
      "status": "held",
      "amount": "49.00",
      "currency": "USD",
      "provider": "stripe",
      "valueCoin": "24.50",
      "coin": "polygon_usdc",
      "holdReason": "The provider sent 24.50 USDC, below 90% of the order’s 49.00 USD value.",
      "holdAcceptable": true,
      "paidAt": null
    }
  }
}

#payment.updated

A paid payment's settlement details arrived after it was confirmed: txidIn, valueCoin, coin and merchantReceived are now filled in. The status stays paid. Update your records; there's nothing to fulfil again.

#payment.failed

The payment reached a terminal failure. Today this is sent in Test mode only, for an explicit API simulation with outcome: "failed". The Test provider's declined-card action keeps the payment open and sends no failed event. Live card providers don't report declines, so a live payment the buyer never completes ends as payment.expired. After a terminal failure, let the buyer try again with a new session.

#payment.expired

Nobody paid before the payment's expiresAt: 24 hours for API sessions, or the lifetime chosen for a payment link. It's sent within five minutes of expiry.

It's not always the end. A provider that delivers late still settles the payment, and a payment.paid or payment.held follows. Release reserved stock if you like, but keep the order able to complete.

#payment.canceled

You canceled a payment link in the dashboard before anyone had gone to a provider. The payment's status is expired and canceledAt is set.

#ping

Sent only when you choose Send test event and pick ping (Test endpoints) or Send ping (Live endpoints). data.payment, data.order and data.customer are null. Use it to check the address, the secret and your signature code.

{
  "id": "evt_T2rVx9KcQm4NwLb7Ez0P",
  "type": "ping",
  "created": 1790380800,
  "livemode": false,
  "data": { "payment": null, "order": null, "customer": null }
}

#Typical sequences

Events can arrive out of order, so handle each one on its own merits, and never undo a paid order because of a later event. When you ship goods, deliver each order once, keyed on data.order.id: a buyer who pays two sessions for one order sends two payment.paid events for it.

#The payment object

Webhook payloads carry the payment, order and customer in the dashboard's shape: camelCase names and timestamps in milliseconds (the event's own created is Unix seconds). The API's payment has the same facts in snake_case with Unix seconds.

#The order object

data.order is the order the payment belongs to, with its items. It has the API order's facts in camelCase, plus a few the dashboard uses.

For every payment attempt's id, read the order: the API's order lists them in payment_ids. A store order's data.order looks like this in part:

{
  "id": "ord_Vd3kR8mQ1xTn6LpZs0Wa",
  "displayNumber": "#1042",
  "store": {
    "platform": "woocommerce",
    "id": "3f6c1a2e-8b4d-4e9a-9c7f-2d5b8e1a4c60",
    "name": "yourstore.com",
    "url": "https://yourstore.com/",
    "orderId": "1042",
    "orderNumber": "1042",
    "orderUrl": "https://yourstore.com/wp-admin/post.php?post=1042&action=edit",
    "customerId": "88"
  },
  "status": "paid",
  "fulfillment": "unfulfilled",
  "total": "135.31",
  "shipTo": {
    "name": "Maya Okafor",
    "line1": "418 Linden Avenue",
    "line2": "Apt 3B",
    "city": "Portland",
    "region": "OR",
    "postalCode": "97214",
    "country": "US"
  },
  "items": [
    {
      "name": "Magnesium glycinate",
      "variant": "120 capsules",
      "sku": "HN-MG-120",
      "quantity": 2,
      "unitAmount": "32.00",
      "amount": "64.00"
    }
  ]
}

#The customer object

data.customer is the order's customer, with their contact details as they were when the event happened. It's null until the buyer has given an email.

Their order counts, what they've spent and your private note are never sent in webhooks. For counts and totals, read the customer.

When you delete a customer's details, they're also removed from the bodies kept in your delivery log: a resend carries null in their place. Events already delivered can't be recalled.