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
}
}
]
}
}
'import requests
url = "https://api-beta.pepay.io/api/v1/invoices"
payload = {
"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 }
}
] }
}
headers = {
"Idempotency-Key": "<idempotency-key>",
"x-api-key": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {
'Idempotency-Key': '<idempotency-key>',
'x-api-key': '<api-key>',
'Content-Type': 'application/json'
},
body: JSON.stringify({
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}
}
]
}
})
};
fetch('https://api-beta.pepay.io/api/v1/invoices', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api-beta.pepay.io/api/v1/invoices",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'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
]
]
]
]
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"Idempotency-Key: <idempotency-key>",
"x-api-key: <api-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api-beta.pepay.io/api/v1/invoices"
payload := strings.NewReader("{\n \"amount_usd\": 99.99,\n \"description\": \"Premium Plan Subscription\",\n \"customer_id\": \"<string>\",\n \"metadata\": {\n \"order_id\": \"ORD-123\",\n \"items\": [\n {\n \"id\": \"SKU-1\",\n \"qty\": 2\n }\n ]\n },\n \"expires_in\": 43200000,\n \"receiver_override_enable\": true,\n \"receiver_override_address\": \"0x1111111111111111111111111111111111111111\",\n \"invoice_title\": \"Monthly Subscription - Premium Plan\",\n \"invoice_footer\": \"Thank you for your business!\",\n \"customer_email\": \"customer@example.com\",\n \"payment_return_url\": \"https://merchant.example.com/checkout/complete\",\n \"payment_return_url_enabled\": true,\n \"questions\": {\n \"questions\": [\n {\n \"id\": \"q1\",\n \"question\": \"Email address\",\n \"type\": \"email\",\n \"validation\": {\n \"required\": true\n }\n }\n ]\n }\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Idempotency-Key", "<idempotency-key>")
req.Header.Add("x-api-key", "<api-key>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api-beta.pepay.io/api/v1/invoices")
.header("Idempotency-Key", "<idempotency-key>")
.header("x-api-key", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"amount_usd\": 99.99,\n \"description\": \"Premium Plan Subscription\",\n \"customer_id\": \"<string>\",\n \"metadata\": {\n \"order_id\": \"ORD-123\",\n \"items\": [\n {\n \"id\": \"SKU-1\",\n \"qty\": 2\n }\n ]\n },\n \"expires_in\": 43200000,\n \"receiver_override_enable\": true,\n \"receiver_override_address\": \"0x1111111111111111111111111111111111111111\",\n \"invoice_title\": \"Monthly Subscription - Premium Plan\",\n \"invoice_footer\": \"Thank you for your business!\",\n \"customer_email\": \"customer@example.com\",\n \"payment_return_url\": \"https://merchant.example.com/checkout/complete\",\n \"payment_return_url_enabled\": true,\n \"questions\": {\n \"questions\": [\n {\n \"id\": \"q1\",\n \"question\": \"Email address\",\n \"type\": \"email\",\n \"validation\": {\n \"required\": true\n }\n }\n ]\n }\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api-beta.pepay.io/api/v1/invoices")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Idempotency-Key"] = '<idempotency-key>'
request["x-api-key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"amount_usd\": 99.99,\n \"description\": \"Premium Plan Subscription\",\n \"customer_id\": \"<string>\",\n \"metadata\": {\n \"order_id\": \"ORD-123\",\n \"items\": [\n {\n \"id\": \"SKU-1\",\n \"qty\": 2\n }\n ]\n },\n \"expires_in\": 43200000,\n \"receiver_override_enable\": true,\n \"receiver_override_address\": \"0x1111111111111111111111111111111111111111\",\n \"invoice_title\": \"Monthly Subscription - Premium Plan\",\n \"invoice_footer\": \"Thank you for your business!\",\n \"customer_email\": \"customer@example.com\",\n \"payment_return_url\": \"https://merchant.example.com/checkout/complete\",\n \"payment_return_url_enabled\": true,\n \"questions\": {\n \"questions\": [\n {\n \"id\": \"q1\",\n \"question\": \"Email address\",\n \"type\": \"email\",\n \"validation\": {\n \"required\": true\n }\n }\n ]\n }\n}"
response = http.request(request)
puts response.read_body{
"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>"
}
}{
"success": false,
"error": {
"message": "Amount must be between $0.01 and $1,000,000",
"details": {},
"timestamp": 1711024496,
"traceId": "a1b2c3d4e5f6"
}
}{
"success": false,
"error": {
"message": "Authentication required",
"timestamp": 123,
"traceId": "<string>"
}
}{
"success": false,
"error": {
"message": "Idempotency key already used",
"timestamp": 123,
"traceId": "<string>"
}
}{
"success": false,
"error": {
"message": "Failed to create invoice",
"timestamp": 123,
"traceId": "<string>"
}
}Merchant
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 --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
}
}
]
}
}
'import requests
url = "https://api-beta.pepay.io/api/v1/invoices"
payload = {
"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 }
}
] }
}
headers = {
"Idempotency-Key": "<idempotency-key>",
"x-api-key": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {
'Idempotency-Key': '<idempotency-key>',
'x-api-key': '<api-key>',
'Content-Type': 'application/json'
},
body: JSON.stringify({
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}
}
]
}
})
};
fetch('https://api-beta.pepay.io/api/v1/invoices', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api-beta.pepay.io/api/v1/invoices",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'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
]
]
]
]
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"Idempotency-Key: <idempotency-key>",
"x-api-key: <api-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api-beta.pepay.io/api/v1/invoices"
payload := strings.NewReader("{\n \"amount_usd\": 99.99,\n \"description\": \"Premium Plan Subscription\",\n \"customer_id\": \"<string>\",\n \"metadata\": {\n \"order_id\": \"ORD-123\",\n \"items\": [\n {\n \"id\": \"SKU-1\",\n \"qty\": 2\n }\n ]\n },\n \"expires_in\": 43200000,\n \"receiver_override_enable\": true,\n \"receiver_override_address\": \"0x1111111111111111111111111111111111111111\",\n \"invoice_title\": \"Monthly Subscription - Premium Plan\",\n \"invoice_footer\": \"Thank you for your business!\",\n \"customer_email\": \"customer@example.com\",\n \"payment_return_url\": \"https://merchant.example.com/checkout/complete\",\n \"payment_return_url_enabled\": true,\n \"questions\": {\n \"questions\": [\n {\n \"id\": \"q1\",\n \"question\": \"Email address\",\n \"type\": \"email\",\n \"validation\": {\n \"required\": true\n }\n }\n ]\n }\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Idempotency-Key", "<idempotency-key>")
req.Header.Add("x-api-key", "<api-key>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api-beta.pepay.io/api/v1/invoices")
.header("Idempotency-Key", "<idempotency-key>")
.header("x-api-key", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"amount_usd\": 99.99,\n \"description\": \"Premium Plan Subscription\",\n \"customer_id\": \"<string>\",\n \"metadata\": {\n \"order_id\": \"ORD-123\",\n \"items\": [\n {\n \"id\": \"SKU-1\",\n \"qty\": 2\n }\n ]\n },\n \"expires_in\": 43200000,\n \"receiver_override_enable\": true,\n \"receiver_override_address\": \"0x1111111111111111111111111111111111111111\",\n \"invoice_title\": \"Monthly Subscription - Premium Plan\",\n \"invoice_footer\": \"Thank you for your business!\",\n \"customer_email\": \"customer@example.com\",\n \"payment_return_url\": \"https://merchant.example.com/checkout/complete\",\n \"payment_return_url_enabled\": true,\n \"questions\": {\n \"questions\": [\n {\n \"id\": \"q1\",\n \"question\": \"Email address\",\n \"type\": \"email\",\n \"validation\": {\n \"required\": true\n }\n }\n ]\n }\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api-beta.pepay.io/api/v1/invoices")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Idempotency-Key"] = '<idempotency-key>'
request["x-api-key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"amount_usd\": 99.99,\n \"description\": \"Premium Plan Subscription\",\n \"customer_id\": \"<string>\",\n \"metadata\": {\n \"order_id\": \"ORD-123\",\n \"items\": [\n {\n \"id\": \"SKU-1\",\n \"qty\": 2\n }\n ]\n },\n \"expires_in\": 43200000,\n \"receiver_override_enable\": true,\n \"receiver_override_address\": \"0x1111111111111111111111111111111111111111\",\n \"invoice_title\": \"Monthly Subscription - Premium Plan\",\n \"invoice_footer\": \"Thank you for your business!\",\n \"customer_email\": \"customer@example.com\",\n \"payment_return_url\": \"https://merchant.example.com/checkout/complete\",\n \"payment_return_url_enabled\": true,\n \"questions\": {\n \"questions\": [\n {\n \"id\": \"q1\",\n \"question\": \"Email address\",\n \"type\": \"email\",\n \"validation\": {\n \"required\": true\n }\n }\n ]\n }\n}"
response = http.request(request)
puts response.read_body{
"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>"
}
}{
"success": false,
"error": {
"message": "Amount must be between $0.01 and $1,000,000",
"details": {},
"timestamp": 1711024496,
"traceId": "a1b2c3d4e5f6"
}
}{
"success": false,
"error": {
"message": "Authentication required",
"timestamp": 123,
"traceId": "<string>"
}
}{
"success": false,
"error": {
"message": "Idempotency key already used",
"timestamp": 123,
"traceId": "<string>"
}
}{
"success": false,
"error": {
"message": "Failed to create invoice",
"timestamp": 123,
"traceId": "<string>"
}
}Authorizations
API key for authentication
Headers
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 in USD
Required range:
0.01 <= x <= 1000000Example:
99.99
Description of the invoice
Maximum string length:
255Example:
"Premium Plan Subscription"
Optional customer identifier
Maximum string length:
255Additional structured data (max 512 bytes)
Example:
{
"order_id": "ORD-123",
"items": [{ "id": "SKU-1", "qty": 2 }]
}
Optional expiration time in milliseconds (default 12 hours, max 30 days)
Required range:
1 <= x <= 2592000000Example:
43200000
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
Pass-through address to receive the merchant settlement amount.
Example:
"0x1111111111111111111111111111111111111111"
Optional custom title for the invoice. Defaults to the merchant's company_name if not provided.
Maximum string length:
255Example:
"Monthly Subscription - Premium Plan"
Optional custom footer text for the invoice. Defaults to the merchant's company_name if not provided.
Maximum string length:
255Example:
"Thank you for your business!"
Optional customer email address for receipts and notifications.
Maximum string length:
255Example:
"customer@example.com"
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:
2048Pattern:
^https://Example:
"https://merchant.example.com/checkout/complete"
Controls whether the return URL is used. When false, no redirect is applied even if a URL is set.
Example:
true
Optional questions to collect during checkout (max 5 questions, max 512 bytes).
Show child attributes
Show child attributes
Response
Invoice created successfully
Unique identifier for the invoice
Example:
"123e4567-e89b-12d3-a456-426614174000"
Hosted payment page URL (valid until expires_at)
Expiration timestamp (epoch seconds).
Example:
1711024496
Payment session token (send as x-session-token to /api/v1/payments/*)
Payment session signature (send as x-signature to /api/v1/payments/*)
Convenience mapping of required payment session headers
Show child attributes
Show child attributes
Was this page helpful?
⌘I