Skip to main content
POST
/
api
/
v1
/
invoices
Create an invoice
curl --request POST \
  --url https://api-beta.pepay.io/api/v1/invoices \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "amount_usd": 99.99,
  "description": "Premium Plan Subscription",
  "customer_id": "<string>",
  "metadata": {
    "order_id": "ORD-123",
    "items": [
      {
        "id": "SKU-1",
        "qty": 2
      }
    ]
  },
  "expires_in": 43200000,
  "receiver_override_enable": true,
  "receiver_override_address": "0x1111111111111111111111111111111111111111",
  "invoice_title": "Monthly Subscription - Premium Plan",
  "invoice_footer": "Thank you for your business!",
  "customer_email": "customer@example.com",
  "payment_return_url": "https://merchant.example.com/checkout/complete",
  "payment_return_url_enabled": true,
  "questions": {
    "questions": [
      {
        "id": "q1",
        "question": "Email address",
        "type": "email",
        "validation": {
          "required": true
        }
      }
    ]
  }
}
'
{
  "invoice_id": "123e4567-e89b-12d3-a456-426614174000",
  "payment_url": "<string>",
  "expires_at": 1711024496,
  "session_token": "<string>",
  "signature": "<string>",
  "payment_session_headers": {
    "x-session-token": "<string>",
    "x-signature": "<string>"
  }
}

​
Overview

Use this endpoint to create an invoice and start a payment flow for your customer. Notes:
  • expires_in is milliseconds (default 12 hours, max 30 days).

​
Authentication

  • Merchant server auth: x-api-key or Authorization: Bearer <jwt>
  • Safe retries: include an Idempotency-Key header on POST requests.

​
Request

​
SDK

const invoice = await pepay.invoices.create({
  amount_usd: 49.99,
  description: 'Starter plan',
  expires_in: 12 * 60 * 60 * 1000
});

​
cURL

curl -X POST "https://api-beta.pepay.io/api/v1/invoices" \
  -H "x-api-key: sk_live_..." \
  -H "Idempotency-Key: 123e4567-e89b-42d3-a456-556642440000" \
  -H "Content-Type: application/json" \
  -d '{"amount_usd":49.99,"description":"Starter plan","expires_in":43200000}'

​
Response

{
  "invoice_id": "550e8400-e29b-41d4-a716-446655440000",
  "payment_url": "https://<payment-iframe-host>/pay?session=pst_...&signature=sig_...",
  "expires_at": 1766322000,
  "session_token": "pst_...",
  "signature": "sig_...",
  "payment_session_headers": {
    "x-session-token": "pst_...",
    "x-signature": "sig_..."
  }
}

​
Errors

  • 400 invalid parameters (missing/invalid amount, invalid metadata, etc.)
  • 401 missing/invalid merchant auth
  • 409 idempotency conflict (retry with the same Idempotency-Key to safely reuse the original request)

​
Examples

  • Browser checkout: use session_token + signature to call /api/v1/payments/* endpoints without exposing server API keys.
Next: List invoices

Authorizations

​
x-api-key
string
header
required

API key for authentication

Headers

​
Idempotency-Key
string<uuid>
required

A v4 UUID to prevent duplicate requests. Must be unique for each request.

Pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$
Example:

"123e4567-e89b-42d3-a456-556642440000"

Body

application/json
​
amount_usd
number<float>
required

Amount in USD

Required range: 0.01 <= x <= 1000000
Example:

99.99

​
description
string

Description of the invoice

Maximum string length: 255
Example:

"Premium Plan Subscription"

​
customer_id
string

Optional customer identifier

Maximum string length: 255
​
metadata
object

Additional structured data (max 512 bytes)

Example:
{
  "order_id": "ORD-123",
  "items": [{ "id": "SKU-1", "qty": 2 }]
}
​
expires_in
number

Optional expiration time in milliseconds (default 12 hours, max 30 days)

Required range: 1 <= x <= 2592000000
Example:

43200000

​
receiver_override_enable
boolean

When true, the invoice will use a receiver override (pass-through) address for merchant settlement. Requires receiver_override_address. The settlement network is derived from the merchant's configured settlement token (or the system default).

Example:

true

​
receiver_override_address
string

Pass-through address to receive the merchant settlement amount.

Example:

"0x1111111111111111111111111111111111111111"

​
invoice_title
string

Optional custom title for the invoice. Defaults to the merchant's company_name if not provided.

Maximum string length: 255
Example:

"Monthly Subscription - Premium Plan"

​
invoice_footer
string

Optional custom footer text for the invoice. Defaults to the merchant's company_name if not provided.

Maximum string length: 255
Example:

"Thank you for your business!"

​
customer_email
string<email>

Optional customer email address for receipts and notifications.

Maximum string length: 255
Example:

"customer@example.com"

​
payment_return_url
string<uri>

Optional return URL for hosted checkout to redirect after payment. Must be HTTPS. If omitted, the merchant default return URL may be used.

Maximum string length: 2048
Pattern: ^https://
Example:

"https://merchant.example.com/checkout/complete"

​
payment_return_url_enabled
boolean

Controls whether the return URL is used. When false, no redirect is applied even if a URL is set.

Example:

true

​
questions
object

Optional questions to collect during checkout (max 5 questions, max 512 bytes).

Response

Invoice created successfully

​
invoice_id
string<uuid>

Unique identifier for the invoice

Example:

"123e4567-e89b-12d3-a456-426614174000"

​
payment_url
string<uri>

Hosted payment page URL (valid until expires_at)

​
expires_at
integer

Expiration timestamp (epoch seconds).

Example:

1711024496

​
session_token
string

Payment session token (send as x-session-token to /api/v1/payments/*)

​
signature
string

Payment session signature (send as x-signature to /api/v1/payments/*)

​
payment_session_headers
object

Convenience mapping of required payment session headers