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": "[email protected]",
  "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": "2024-03-21T12:34:56Z",
  "session_token": "<string>",
  "signature": "<string>",
  "payment_session_headers": {
    "x-session-token": "<string>",
    "x-signature": "<string>"
  }
}

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.

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:

"[email protected]"

​
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
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
string<date-time>
Example:

"2024-03-21T12:34:56Z"

​
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