Skip to main content
POST
/
api
/
commerce
/
merchant
/
checkout
/
invoice
Step 3 - Create invoice and order
curl --request POST \
  --url https://api-beta.pepay.io/api/commerce/merchant/checkout/invoice \
  --header 'Content-Type: application/json' \
  --header 'x-commerce-api-key: <api-key>' \
  --data '
{
  "customer_id": "cust_123456",
  "estimateId": "550e8400-e29b-41d4-a716-446655440000",
  "addressId": "550e8400-e29b-41d4-a716-446655440222",
  "refundDestinationWalletAddressBsc": "0x0000000000000000000000000000000000000001"
}
'
{
  "success": true,
  "data": {
    "orderId": "550e8400-e29b-41d4-a716-446655440333",
    "invoiceId": "550e8400-e29b-41d4-a716-446655440111",
    "invoiceUrl": "https://pay.example.com/pay?session=...&signature=...",
    "session": "550e8400-e29b-41d4-a716-446655440444",
    "signature": "<signatureHash>.<timestamp>",
    "payment_session_headers": {
      "x-session-token": "550e8400-e29b-41d4-a716-446655440444",
      "x-signature": "<signatureHash>.<timestamp>"
    },
    "merchantId": 123,
    "networkEnvironment": "devnet",
    "customerId": "cust_123456",
    "amount": 13.99,
    "status": "unpaid",
    "expiresAt": "2025-12-16T00:20:00.000Z",
    "endpoints": {
      "checkOrder": "/api/commerce/merchant/orders/550e8400-e29b-41d4-a716-446655440333",
      "checkPayment": "/api/commerce/merchant/payments/550e8400-e29b-41d4-a716-446655440333/status",
      "cancelOrder": "/api/commerce/merchant/orders/550e8400-e29b-41d4-a716-446655440333/cancel"
    }
  }
}

​
Overview

Use this endpoint to convert a validated checkout payload into an invoice your customer can pay.

​
Authentication

Commerce merchant checkout endpoints use x-commerce-api-key.

​
Request

​
SDK

const invoice = await pepay.commerce.checkout.createInvoice({
  // Provide the checkout payload you validated via estimate/address steps
});

​
cURL

curl -X POST "https://api-beta.pepay.io/api/commerce/merchant/checkout/invoice" \
  -H "x-commerce-api-key: ck_..." \
  -H "Idempotency-Key: 123e4567-e89b-42d3-a456-556642440000" \
  -H "Content-Type: application/json" \
  -d '{}'

​
Response

{
  "success": true,
  "data": {
    "orderId": "550e8400-e29b-41d4-a716-446655440111",
    "invoiceId": "550e8400-e29b-41d4-a716-446655440000",
    "invoiceUrl": "https://<payment-iframe-host>/pay?session=pst_...&signature=sig_...",
    "session": "pst_...",
    "signature": "sig_...",
    "payment_session_headers": {
      "x-session-token": "pst_...",
      "x-signature": "sig_..."
    },
    "merchantId": 123,
    "networkEnvironment": "devnet",
    "status": "unpaid"
  }
}

​
Errors

  • 400 invalid checkout payload
  • 401 missing/invalid commerce auth

​
Examples

  • Follow the 3-step flow: estimate → address → invoice to ensure totals/shipping are validated before invoice creation. Next: Payment session details

Authorizations

​
x-commerce-api-key
string
header
required

Legacy alias for commerce-scoped API keys. Prefer x-api-key with scope=commerce.

Body

application/json

Step 3 request. Creates the final invoice + commerce order from an existing estimate + address.

​
customer_id
string
required
Example:

"cust_123456"

​
estimateId
string<uuid>
required
​
addressId
string<uuid>
required
​
webhookUrl
string<uri> | null

Deprecated/ignored; use merchant webhook configuration endpoints instead.

​
refundDestinationWalletAddressBsc
string | null

Optional BSC destination address for refunds (0x…).

Example:

"0x0000000000000000000000000000000000000001"

Response

200 - application/json

Invoice created successfully

​
success
boolean
Example:

true

​
data
object

Step 3 result. Contains invoice URL and payment session headers.