Webhook Events

Bedrock sends webhooks for the following events.

charge.pending

Sent when a new charge is created.

{
  "event": "charge.pending",
  "timestamp": "2024-01-15T12:00:00Z",
  "data": {
    "id": "chrg_abc123def456",
    "orderId": "order-123",
    "amount": "25.00",
    "status": "PENDING",
    "paymentUrl": "https://pay.bedrock.io/chrg_abc123def456",
    "expiresAt": "2024-01-15T12:30:00Z"
  }
}

charge.partial

Sent when a partial payment is received (less than the requested amount).

{
  "event": "charge.partial",
  "timestamp": "2024-01-15T12:10:00Z",
  "data": {
    "id": "chrg_abc123def456",
    "orderId": "order-123",
    "amount": "25.00",
    "amountReceived": "15.00",
    "amountRemaining": "10.00",
    "percentReceived": "60.00",
    "status": "PARTIAL",
    "cloneAddress": "0x1234...",
    "chainId": 8453,
    "payerAddress": "0xabc...",
    "paymentCount": 1,
    "expiresAt": "2024-01-15T12:25:00Z"
  }
}

When a partial payment is received, the expiry is extended by the merchant's configured partialExpiryExtensionMins (default: 15 minutes) to allow the customer to complete the payment.

charge.received

Sent when full payment is detected on the blockchain.

{
  "event": "charge.received",
  "timestamp": "2024-01-15T12:10:00Z",
  "data": {
    "id": "chrg_abc123def456",
    "orderId": "order-123",
    "amount": "25.00",
    "amountReceived": "25.00",
    "status": "RECEIVED",
    "cloneAddress": "0x1234...",
    "chainId": 8453,
    "payerAddress": "0xabc..."
  }
}

charge.completed

Sent when payment is settled to the merchant.

{
  "event": "charge.completed",
  "timestamp": "2024-01-15T12:15:00Z",
  "data": {
    "id": "chrg_abc123def456",
    "orderId": "order-123",
    "amount": "25.00",
    "amountReceived": "25.00",
    "feeAmount": "0.25",
    "netAmount": "24.75",
    "status": "COMPLETED",
    "cloneAddress": "0x1234...",
    "chainId": 8453,
    "flushTxHash": "0xabcd...",
    "completedAt": "2024-01-15T12:15:00Z"
  }
}

This is the most important event - use it to fulfill customer orders.

charge.underpaid

Sent when a charge with partial payment expires and the partial amount is flushed to the merchant.

{
  "event": "charge.underpaid",
  "timestamp": "2024-01-15T12:30:00Z",
  "data": {
    "id": "chrg_abc123def456",
    "orderId": "order-123",
    "amount": "25.00",
    "amountReceived": "15.00",
    "amountRemaining": "10.00",
    "percentReceived": "60.00",
    "feeAmount": "0.15",
    "netAmount": "14.85",
    "status": "UNDERPAID",
    "cloneAddress": "0x1234...",
    "chainId": 8453,
    "payerAddress": "0xabc...",
    "flushTxHash": "0xabcd...",
    "completedAt": "2024-01-15T12:30:00Z"
  }
}

When a charge is underpaid, the partial payment is automatically flushed to the merchant's settlement address. The merchant is responsible for handling refunds to the customer if needed. Use the payerAddress field to identify who sent the payment.

charge.expired

Sent when a charge expires without any payment received.

{
  "event": "charge.expired",
  "timestamp": "2024-01-15T12:30:00Z",
  "data": {
    "id": "chrg_abc123def456",
    "orderId": "order-123",
    "amount": "25.00",
    "status": "EXPIRED"
  }
}

charge.cancelled

Sent when a charge is cancelled by the merchant.

{
  "event": "charge.cancelled",
  "timestamp": "2024-01-15T12:20:00Z",
  "data": {
    "id": "chrg_abc123def456",
    "orderId": "order-123",
    "amount": "25.00",
    "status": "CANCELLED"
  }
}

Event Data Fields

All events include these common fields in data:

Field	Type	Description
id	string	Charge ID
orderId	string	Your order ID
amount	string	Requested amount
status	string	Current status

Partial Payment Fields

These fields are included in charge.partial and charge.underpaid events:

Field	Type	Description
amountReceived	string	Total amount received so far
amountRemaining	string	Amount still needed for full payment
percentReceived	string	Percentage of requested amount received
payerAddress	string	Wallet address that sent the payment
paymentCount	number	Number of payment transactions received

Settlement Fields

These fields are included in charge.completed and charge.underpaid events:

Field	Type	Description
feeAmount	string	Protocol fee deducted
netAmount	string	Amount sent to merchant after fee
flushTxHash	string	Transaction hash of the settlement
completedAt	string	ISO timestamp of settlement