Create Charge

Creates a new payment charge.

POST /v1/charges

Request

Headers

Header	Required	Description
X-API-Key	Yes	Your API key
Content-Type	Yes	Must be application/json

Body Parameters

Parameter	Type	Required	Description
orderId	string	Yes	Your unique order identifier. Must be unique per merchant.
amount	string	Yes	Payment amount in USDC (e.g., "25.00")
description	string	No	Description of the payment
customerId	string	No	ID of an existing Customer to associate with this charge
successUrl	string	No	URL to redirect the customer after successful payment
cancelUrl	string	No	URL to redirect the customer if they cancel the payment
metadata	object	No	Arbitrary key-value pairs for your use

Redirect URLs

When successUrl is provided, the customer will be automatically redirected after payment completion with the following query parameters:

• chargeId - The charge ID

• orderId - Your order ID

• status - The payment status (e.g., "completed")

Example redirect: https://yourstore.com/success?chargeId=chrg_abc&orderId=order-123&status=completed

When cancelUrl is provided, a cancel button will appear on the payment page, redirecting customers with similar query parameters and status=cancelled.

Note: Always use webhooks as the source of truth for payment confirmation. Do not rely solely on the redirect for order fulfillment.

Example Request

curl -X POST https://api.bedrock.io/v1/charges \
  -H "X-API-Key: sk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "orderId": "order-123",
    "amount": "25.00",
    "description": "Premium subscription",
    "customerId": "cus_abc123def456",
    "successUrl": "https://yourstore.com/checkout/success",
    "cancelUrl": "https://yourstore.com/checkout",
    "metadata": {
      "productId": "prod_789"
    }
  }'

Response

Success (201 Created)

{
  "id": "chrg_abc123def456",
  "orderId": "order-123",
  "amount": "25.00",
  "amountReceived": null,
  "feeAmount": null,
  "netAmount": null,
  "currency": "USDC",
  "status": "PENDING",
  "cloneAddress": null,
  "chainId": null,
  "paymentUrl": "https://pay.bedrock.io/chrg_abc123def456",
  "explorerUrl": null,
  "feeBps": 100,
  "flushTxHash": null,
  "expiresAt": "2024-01-15T12:30:00Z",
  "createdAt": "2024-01-15T12:00:00Z",
  "completedAt": null,
  "deployedAt": null,
  "successUrl": "https://yourstore.com/checkout/success",
  "cancelUrl": "https://yourstore.com/checkout",
  "customer": {
    "id": "cus_abc123def456",
    "email": "[email protected]",
    "name": "John Doe"
  }
}

Errors

Status	Code	Description
400	invalid_amount	Amount must be a positive number
400	duplicate_order_id	Order ID already exists for this merchant
401	unauthorized	Invalid or missing API key
403	merchant_inactive	Merchant account is not active

Example Error Response

{
  "statusCode": 400,
  "message": "Order ID \"order-123\" already exists for this merchant",
  "error": "Bad Request"
}

Notes

• The cloneAddress and chainId will be null until the customer selects a chain on the payment page

• The charge expires after 30 minutes if no chain is selected

• Once a chain is selected, the charge expires after 5 minutes

• Use the orderId to correlate payments with your orders