Create an invoice

Creates a new invoice and returns a payment URL for the checkout/payment session integration. The idempotency key must be a v4 UUID generated on the client side. Optionally set a pass-through settlement address using receiver_override_* fields. Example UUID v4 generation in JavaScript:

import { v4 as uuidv4 } from 'uuid';
const idempotencyKey = uuidv4();

POST /api/v1/invoices

Create an invoice

cURL

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": "[e-mail]",
  "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
        }
      }
    ]
  }
}
'

201

{
  "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:

"[e-mail]"

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).

Show child attributes

Response

201

application/json

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

Show child attributes