Payment Flow

This guide explains the complete payment flow from charge creation to settlement.

Overview

┌─────────────┐     ┌─────────────┐     ┌─────────────┐     ┌─────────────┐
│   Merchant  │     │   Bedrock   │     │  Customer   │     │ Blockchain  │
└──────┬──────┘     └──────┬──────┘     └──────┬──────┘     └──────┬──────┘
       │                   │                   │                   │
       │ Create Charge     │                   │                   │
       │──────────────────>│                   │                   │
       │                   │                   │                   │
       │ Return paymentUrl │                   │                   │
       │<──────────────────│                   │                   │
       │                   │                   │                   │
       │ Redirect customer │                   │                   │
       │───────────────────────────────────────>                   │
       │                   │                   │                   │
       │                   │   Select chain    │                   │
       │                   │<──────────────────│                   │
       │                   │                   │                   │
       │                   │  Deploy clone     │                   │
       │                   │──────────────────────────────────────>│
       │                   │                   │                   │
       │                   │   Show address    │                   │
       │                   │──────────────────>│                   │
       │                   │                   │                   │
       │                   │                   │  Send USDC        │
       │                   │                   │──────────────────>│
       │                   │                   │                   │
       │                   │  Detect payment   │                   │
       │                   │<──────────────────────────────────────│
       │                   │                   │                   │
       │                   │  Flush to merchant│                   │
       │                   │──────────────────────────────────────>│
       │                   │                   │                   │
       │   Webhook         │                   │                   │
       │<──────────────────│                   │                   │
       │                   │                   │                   │
       │ Fulfill order     │                   │                   │
       │──────────────────>│                   │                   │
       │                   │                   │                   │

Step-by-Step

1. Merchant Creates Charge

curl -X POST https://api.bedrock.io/v1/charges \
  -H "X-API-Key: sk_live_..." \
  -d '{"orderId": "order-123", "amount": "25.00"}'

At this point:

• Charge status: PENDING

• No clone deployed

• 30-minute expiration timer starts

2. Customer Visits Payment Page

Customer is redirected to paymentUrl. They see:

• Payment amount

• List of supported chains (Base, Optimism, etc.)

3. Customer Selects Chain

When the customer clicks a chain:

• Clone contract is deployed on that chain

• Clone address is generated

• 5-minute payment timer starts

Behind the scenes:

// Clone is deployed via factory
factory.deployPaymentClone(orderId, merchantAddress)

4. Customer Sends Payment

Customer sends USDC to the clone address using:

• Connected wallet (one-click)

• Manual transfer from any wallet/exchange

5. Payment Detection

Bedrock monitors the blockchain for incoming USDC:

• Webhook from Alchemy detects the transfer

• Charge status updates to RECEIVED

• charge.received webhook sent to merchant

6. Automatic Settlement

The relayer triggers the flush function:

// Flush sends funds to merchant minus fee
clone.flush(usdcAddress, merchantAddress)

Settlement breakdown:

• Customer sent: 25.00 USDC

• Protocol fee (1%): 0.25 USDC

• Merchant receives: 24.75 USDC

7. Merchant Receives Webhook

{
  "event": "charge.completed",
  "data": {
    "orderId": "order-123",
    "amountReceived": "25.00",
    "netAmount": "24.75",
    "flushTxHash": "0x..."
  }
}

8. Order Fulfillment

Merchant fulfills the order based on the webhook.

Timing

Phase	Duration
Charge creation → Chain selection	Up to 30 minutes
Chain selection → Payment	Up to 5 minutes
Payment → Settlement	~30 seconds
Settlement → Webhook	~5 seconds

Partial Payments

Bedrock supports partial payment detection and handling. When a customer sends less than the requested amount, the system tracks it and gives them time to complete the payment.

Partial Payment Flow

┌─────────────┐     ┌─────────────┐     ┌─────────────┐
│   Customer  │     │   Bedrock   │     │  Merchant   │
└──────┬──────┘     └──────┬──────┘     └──────┬──────┘
       │                   │                   │
       │ Sends 15 USDC     │                   │
       │ (amount: 25)      │                   │
       │──────────────────>│                   │
       │                   │                   │
       │                   │ charge.partial    │
       │                   │ webhook           │
       │                   │──────────────────>│
       │                   │                   │
       │                   │ Extend expiry     │
       │                   │ (+15 minutes)     │
       │                   │                   │
       │ Sends 10 USDC     │                   │
       │──────────────────>│                   │
       │                   │                   │
       │                   │ charge.received   │
       │                   │ (full amount)     │
       │                   │──────────────────>│
       │                   │                   │

Expiry Behavior

When a partial payment is received:

1. Expiry is extended by the merchant's partialExpiryExtensionMins setting (default: 15 minutes)

2. charge.partial webhook is sent with remaining amount

3. Customer can send additional payments to complete

If the extended expiry passes without full payment:

1. Partial amount is automatically flushed to merchant

2. Status changes to UNDERPAID

3. charge.underpaid webhook is sent with payer address

4. Merchant handles refund if needed

Merchant Configuration

Merchants can configure partial payment behavior:

Setting	Default	Description
acceptPartialPayments	true	Whether to track partial payments
underpaymentThresholdBps	9500	Treat as full if >= this % (95%)
partialExpiryExtensionMins	15	Minutes to extend expiry
minPaymentAmountUsd	0.10	Ignore dust below this amount

Near-Complete Payments

If a customer sends >= 95% of the requested amount (configurable via underpaymentThresholdBps), the payment is treated as complete. This helps avoid edge cases where tiny rounding errors would mark payments as partial.

Error Scenarios

Customer doesn't select chain

• Charge expires after 30 minutes

• charge.expired webhook sent

• No gas spent (no clone deployed)

Customer doesn't pay after chain selection

• Charge expires after 5 minutes

• charge.expired webhook sent

• Clone deployment gas was spent

Customer sends partial payment

• Charge status changes to PARTIAL

• charge.partial webhook sent

• Expiry extended to allow completion

• If not completed: funds flushed to merchant, charge.underpaid webhook sent

Customer sends wrong amount (overpayment)

• Payment is still processed

• amountReceived reflects actual amount

• Merchant decides how to handle excess

Customer sends to expired charge

• Funds go to clone contract

• Manual recovery may be needed

• Contact Bedrock support