Create an invoice
curl --request POST \
--url https://api.pawpayments.com/api/v2/invoices \
--header 'Content-Type: application/json' \
--header 'x-api-key: <api-key>' \
--data '
{
"amount": 1,
"fiat_currency": "<string>",
"asset": "<string>",
"chain": "<string>",
"extra": "<string>",
"notify_url": "<string>",
"ttl": 3600,
"metadata": {},
"title": "<string>",
"description": "<string>",
"underpay_tolerance": 5,
"accepted_coins": [
"<string>"
],
"excluded_coins": [
"<string>"
],
"on_paid_url": "<string>",
"on_cancel_url": "<string>",
"price_modifier": 0,
"fee_bearer": "client",
"payer_info": {},
"permanent_address": false,
"user_id": "<string>"
}
'import requests
url = "https://api.pawpayments.com/api/v2/invoices"
payload = {
"amount": 1,
"fiat_currency": "<string>",
"asset": "<string>",
"chain": "<string>",
"extra": "<string>",
"notify_url": "<string>",
"ttl": 3600,
"metadata": {},
"title": "<string>",
"description": "<string>",
"underpay_tolerance": 5,
"accepted_coins": ["<string>"],
"excluded_coins": ["<string>"],
"on_paid_url": "<string>",
"on_cancel_url": "<string>",
"price_modifier": 0,
"fee_bearer": "client",
"payer_info": {},
"permanent_address": False,
"user_id": "<string>"
}
headers = {
"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: {'x-api-key': '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({
amount: 1,
fiat_currency: '<string>',
asset: '<string>',
chain: '<string>',
extra: '<string>',
notify_url: '<string>',
ttl: 3600,
metadata: {},
title: '<string>',
description: '<string>',
underpay_tolerance: 5,
accepted_coins: ['<string>'],
excluded_coins: ['<string>'],
on_paid_url: '<string>',
on_cancel_url: '<string>',
price_modifier: 0,
fee_bearer: 'client',
payer_info: {},
permanent_address: false,
user_id: '<string>'
})
};
fetch('https://api.pawpayments.com/api/v2/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.pawpayments.com/api/v2/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' => 1,
'fiat_currency' => '<string>',
'asset' => '<string>',
'chain' => '<string>',
'extra' => '<string>',
'notify_url' => '<string>',
'ttl' => 3600,
'metadata' => [
],
'title' => '<string>',
'description' => '<string>',
'underpay_tolerance' => 5,
'accepted_coins' => [
'<string>'
],
'excluded_coins' => [
'<string>'
],
'on_paid_url' => '<string>',
'on_cancel_url' => '<string>',
'price_modifier' => 0,
'fee_bearer' => 'client',
'payer_info' => [
],
'permanent_address' => false,
'user_id' => '<string>'
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"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.pawpayments.com/api/v2/invoices"
payload := strings.NewReader("{\n \"amount\": 1,\n \"fiat_currency\": \"<string>\",\n \"asset\": \"<string>\",\n \"chain\": \"<string>\",\n \"extra\": \"<string>\",\n \"notify_url\": \"<string>\",\n \"ttl\": 3600,\n \"metadata\": {},\n \"title\": \"<string>\",\n \"description\": \"<string>\",\n \"underpay_tolerance\": 5,\n \"accepted_coins\": [\n \"<string>\"\n ],\n \"excluded_coins\": [\n \"<string>\"\n ],\n \"on_paid_url\": \"<string>\",\n \"on_cancel_url\": \"<string>\",\n \"price_modifier\": 0,\n \"fee_bearer\": \"client\",\n \"payer_info\": {},\n \"permanent_address\": false,\n \"user_id\": \"<string>\"\n}")
req, _ := http.NewRequest("POST", url, payload)
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.pawpayments.com/api/v2/invoices")
.header("x-api-key", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"amount\": 1,\n \"fiat_currency\": \"<string>\",\n \"asset\": \"<string>\",\n \"chain\": \"<string>\",\n \"extra\": \"<string>\",\n \"notify_url\": \"<string>\",\n \"ttl\": 3600,\n \"metadata\": {},\n \"title\": \"<string>\",\n \"description\": \"<string>\",\n \"underpay_tolerance\": 5,\n \"accepted_coins\": [\n \"<string>\"\n ],\n \"excluded_coins\": [\n \"<string>\"\n ],\n \"on_paid_url\": \"<string>\",\n \"on_cancel_url\": \"<string>\",\n \"price_modifier\": 0,\n \"fee_bearer\": \"client\",\n \"payer_info\": {},\n \"permanent_address\": false,\n \"user_id\": \"<string>\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.pawpayments.com/api/v2/invoices")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["x-api-key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"amount\": 1,\n \"fiat_currency\": \"<string>\",\n \"asset\": \"<string>\",\n \"chain\": \"<string>\",\n \"extra\": \"<string>\",\n \"notify_url\": \"<string>\",\n \"ttl\": 3600,\n \"metadata\": {},\n \"title\": \"<string>\",\n \"description\": \"<string>\",\n \"underpay_tolerance\": 5,\n \"accepted_coins\": [\n \"<string>\"\n ],\n \"excluded_coins\": [\n \"<string>\"\n ],\n \"on_paid_url\": \"<string>\",\n \"on_cancel_url\": \"<string>\",\n \"price_modifier\": 0,\n \"fee_bearer\": \"client\",\n \"payer_info\": {},\n \"permanent_address\": false,\n \"user_id\": \"<string>\"\n}"
response = http.request(request)
puts response.read_body{
"ok": true,
"result": {
"accepted_coins": [
"usdt_tron",
"usdc_eth"
],
"address_from": null,
"address_to": "TXk2Y5...redacted",
"amount": 49.5,
"asset": "usdt_tron",
"billing_type": "fiat",
"created_at": 1763398800,
"description": "1 month subscription",
"excluded_coins": null,
"expires_at": 1763400600,
"external_id": "f2c8a3d1-4b7e-4f8a-9c1d-2e3b4a5c6d7e",
"extra": "order-12345",
"fee_bearer": "merchant",
"fiat_amount": 50,
"fiat_currency": "USD",
"initial_amount": 49.5,
"initial_asset": "usdt_tron",
"initial_fiat_amount": 50,
"metadata": {
"customer_id": "u_42"
},
"notify_url": "https://shop.example.com/webhook/paw",
"on_cancel_url": "https://shop.example.com/cancel",
"on_paid_url": "https://shop.example.com/thanks",
"order_id": "65f1c3a4e8b1c2d3a4b5c6d7",
"original_amount": 50,
"payer_info": null,
"payment_url": "https://pay.pawpayments.com/checkout/f2c8a3d1-4b7e-4f8a-9c1d-2e3b4a5c6d7e",
"permanent_address_id": null,
"price_modifier": -1,
"processed_at": null,
"received_amount": 0,
"status": "created",
"title": "Premium plan",
"txid": null,
"type": "token",
"underpay_tolerance": 0.01,
"user_id": null
}
}{
"error": {
"code": "VALIDATION_ERROR",
"details": [
{
"field": "amount",
"message": "Field required"
}
],
"message": "Validation failed"
},
"ok": false
}{
"error": {
"code": "VALIDATION_ERROR",
"details": [
{
"field": "amount",
"message": "Field required"
}
],
"message": "Validation failed"
},
"ok": false
}{
"error": {
"code": "VALIDATION_ERROR",
"details": [
{
"field": "amount",
"message": "Field required"
}
],
"message": "Validation failed"
},
"ok": false
}{
"error": {
"code": "VALIDATION_ERROR",
"details": [
{
"field": "amount",
"message": "Field required"
}
],
"message": "Validation failed"
},
"ok": false
}Invoices
Create an invoice
Creates a new invoice. If asset is omitted, the customer picks the currency on the hosted checkout (the deposit address is allocated only after the choice is made).
POST
/
api
/
v2
/
invoices
Create an invoice
curl --request POST \
--url https://api.pawpayments.com/api/v2/invoices \
--header 'Content-Type: application/json' \
--header 'x-api-key: <api-key>' \
--data '
{
"amount": 1,
"fiat_currency": "<string>",
"asset": "<string>",
"chain": "<string>",
"extra": "<string>",
"notify_url": "<string>",
"ttl": 3600,
"metadata": {},
"title": "<string>",
"description": "<string>",
"underpay_tolerance": 5,
"accepted_coins": [
"<string>"
],
"excluded_coins": [
"<string>"
],
"on_paid_url": "<string>",
"on_cancel_url": "<string>",
"price_modifier": 0,
"fee_bearer": "client",
"payer_info": {},
"permanent_address": false,
"user_id": "<string>"
}
'import requests
url = "https://api.pawpayments.com/api/v2/invoices"
payload = {
"amount": 1,
"fiat_currency": "<string>",
"asset": "<string>",
"chain": "<string>",
"extra": "<string>",
"notify_url": "<string>",
"ttl": 3600,
"metadata": {},
"title": "<string>",
"description": "<string>",
"underpay_tolerance": 5,
"accepted_coins": ["<string>"],
"excluded_coins": ["<string>"],
"on_paid_url": "<string>",
"on_cancel_url": "<string>",
"price_modifier": 0,
"fee_bearer": "client",
"payer_info": {},
"permanent_address": False,
"user_id": "<string>"
}
headers = {
"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: {'x-api-key': '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({
amount: 1,
fiat_currency: '<string>',
asset: '<string>',
chain: '<string>',
extra: '<string>',
notify_url: '<string>',
ttl: 3600,
metadata: {},
title: '<string>',
description: '<string>',
underpay_tolerance: 5,
accepted_coins: ['<string>'],
excluded_coins: ['<string>'],
on_paid_url: '<string>',
on_cancel_url: '<string>',
price_modifier: 0,
fee_bearer: 'client',
payer_info: {},
permanent_address: false,
user_id: '<string>'
})
};
fetch('https://api.pawpayments.com/api/v2/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.pawpayments.com/api/v2/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' => 1,
'fiat_currency' => '<string>',
'asset' => '<string>',
'chain' => '<string>',
'extra' => '<string>',
'notify_url' => '<string>',
'ttl' => 3600,
'metadata' => [
],
'title' => '<string>',
'description' => '<string>',
'underpay_tolerance' => 5,
'accepted_coins' => [
'<string>'
],
'excluded_coins' => [
'<string>'
],
'on_paid_url' => '<string>',
'on_cancel_url' => '<string>',
'price_modifier' => 0,
'fee_bearer' => 'client',
'payer_info' => [
],
'permanent_address' => false,
'user_id' => '<string>'
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"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.pawpayments.com/api/v2/invoices"
payload := strings.NewReader("{\n \"amount\": 1,\n \"fiat_currency\": \"<string>\",\n \"asset\": \"<string>\",\n \"chain\": \"<string>\",\n \"extra\": \"<string>\",\n \"notify_url\": \"<string>\",\n \"ttl\": 3600,\n \"metadata\": {},\n \"title\": \"<string>\",\n \"description\": \"<string>\",\n \"underpay_tolerance\": 5,\n \"accepted_coins\": [\n \"<string>\"\n ],\n \"excluded_coins\": [\n \"<string>\"\n ],\n \"on_paid_url\": \"<string>\",\n \"on_cancel_url\": \"<string>\",\n \"price_modifier\": 0,\n \"fee_bearer\": \"client\",\n \"payer_info\": {},\n \"permanent_address\": false,\n \"user_id\": \"<string>\"\n}")
req, _ := http.NewRequest("POST", url, payload)
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.pawpayments.com/api/v2/invoices")
.header("x-api-key", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"amount\": 1,\n \"fiat_currency\": \"<string>\",\n \"asset\": \"<string>\",\n \"chain\": \"<string>\",\n \"extra\": \"<string>\",\n \"notify_url\": \"<string>\",\n \"ttl\": 3600,\n \"metadata\": {},\n \"title\": \"<string>\",\n \"description\": \"<string>\",\n \"underpay_tolerance\": 5,\n \"accepted_coins\": [\n \"<string>\"\n ],\n \"excluded_coins\": [\n \"<string>\"\n ],\n \"on_paid_url\": \"<string>\",\n \"on_cancel_url\": \"<string>\",\n \"price_modifier\": 0,\n \"fee_bearer\": \"client\",\n \"payer_info\": {},\n \"permanent_address\": false,\n \"user_id\": \"<string>\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.pawpayments.com/api/v2/invoices")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["x-api-key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"amount\": 1,\n \"fiat_currency\": \"<string>\",\n \"asset\": \"<string>\",\n \"chain\": \"<string>\",\n \"extra\": \"<string>\",\n \"notify_url\": \"<string>\",\n \"ttl\": 3600,\n \"metadata\": {},\n \"title\": \"<string>\",\n \"description\": \"<string>\",\n \"underpay_tolerance\": 5,\n \"accepted_coins\": [\n \"<string>\"\n ],\n \"excluded_coins\": [\n \"<string>\"\n ],\n \"on_paid_url\": \"<string>\",\n \"on_cancel_url\": \"<string>\",\n \"price_modifier\": 0,\n \"fee_bearer\": \"client\",\n \"payer_info\": {},\n \"permanent_address\": false,\n \"user_id\": \"<string>\"\n}"
response = http.request(request)
puts response.read_body{
"ok": true,
"result": {
"accepted_coins": [
"usdt_tron",
"usdc_eth"
],
"address_from": null,
"address_to": "TXk2Y5...redacted",
"amount": 49.5,
"asset": "usdt_tron",
"billing_type": "fiat",
"created_at": 1763398800,
"description": "1 month subscription",
"excluded_coins": null,
"expires_at": 1763400600,
"external_id": "f2c8a3d1-4b7e-4f8a-9c1d-2e3b4a5c6d7e",
"extra": "order-12345",
"fee_bearer": "merchant",
"fiat_amount": 50,
"fiat_currency": "USD",
"initial_amount": 49.5,
"initial_asset": "usdt_tron",
"initial_fiat_amount": 50,
"metadata": {
"customer_id": "u_42"
},
"notify_url": "https://shop.example.com/webhook/paw",
"on_cancel_url": "https://shop.example.com/cancel",
"on_paid_url": "https://shop.example.com/thanks",
"order_id": "65f1c3a4e8b1c2d3a4b5c6d7",
"original_amount": 50,
"payer_info": null,
"payment_url": "https://pay.pawpayments.com/checkout/f2c8a3d1-4b7e-4f8a-9c1d-2e3b4a5c6d7e",
"permanent_address_id": null,
"price_modifier": -1,
"processed_at": null,
"received_amount": 0,
"status": "created",
"title": "Premium plan",
"txid": null,
"type": "token",
"underpay_tolerance": 0.01,
"user_id": null
}
}{
"error": {
"code": "VALIDATION_ERROR",
"details": [
{
"field": "amount",
"message": "Field required"
}
],
"message": "Validation failed"
},
"ok": false
}{
"error": {
"code": "VALIDATION_ERROR",
"details": [
{
"field": "amount",
"message": "Field required"
}
],
"message": "Validation failed"
},
"ok": false
}{
"error": {
"code": "VALIDATION_ERROR",
"details": [
{
"field": "amount",
"message": "Field required"
}
],
"message": "Validation failed"
},
"ok": false
}{
"error": {
"code": "VALIDATION_ERROR",
"details": [
{
"field": "amount",
"message": "Field required"
}
],
"message": "Validation failed"
},
"ok": false
}Authorizations
Body
application/json
Required range:
x > 0Invoice settlement mode. STATIC — fixed-price service purchase: the invoice expects exactly amount. An underpayment moves it to partially_paid (NOT finalized) so the client can top up to the full amount; the address keeps listening until the invoice expires or reaches success/paid_over. VARY — open-ended balance top-up: any incoming payment finalises the invoice (success if it covers amount, partially_paid (finalized) if less). Required value when permanent_address=true.
Available options:
VARY, STATIC Required string length:
1 - 64Pattern:
^[A-Za-z0-9_-]{1,64}$Maximum string length:
500Required range:
300 <= x <= 86400Maximum string length:
150Maximum string length:
500Required range:
0 <= x <= 10Maximum string length:
500Maximum string length:
500Required range:
-90 <= x <= 90Available options:
merchant, client Available options:
native_v2, cryptomus, heleket, nowpayments, coinpayments, coinpayments_v2 If true, bind this invoice to the permanent deposit address for (merchant, user_id, asset family). The address is created on first use and reused thereafter. Requires billing_type=VARY and a non-empty user_id. If asset is provided the address is allocated immediately; if omitted, the address is allocated when the customer selects a currency on the hosted checkout. XMR is not supported for permanent addresses.
External user identifier — required when permanent_address=true.
Required string length:
1 - 128Response
Created
Show child attributes
Show child attributes
Example:
{ "accepted_coins": ["usdt_tron", "usdc_eth"], "address_from": null, "address_to": "TXk2Y5...redacted", "amount": 49.5, "asset": "usdt_tron", "billing_type": "fiat", "created_at": 1763398800, "description": "1 month subscription", "excluded_coins": null, "expires_at": 1763400600, "external_id": "f2c8a3d1-4b7e-4f8a-9c1d-2e3b4a5c6d7e", "extra": "order-12345", "fee_bearer": "merchant", "fiat_amount": 50, "fiat_currency": "USD", "initial_amount": 49.5, "initial_asset": "usdt_tron", "initial_fiat_amount": 50, "metadata": { "customer_id": "u_42" }, "notify_url": "https://shop.example.com/webhook/paw", "on_cancel_url": "https://shop.example.com/cancel", "on_paid_url": "https://shop.example.com/thanks", "order_id": "65f1c3a4e8b1c2d3a4b5c6d7", "original_amount": 50, "payer_info": null, "payment_url": "https://pay.pawpayments.com/checkout/f2c8a3d1-4b7e-4f8a-9c1d-2e3b4a5c6d7e", "permanent_address_id": null, "price_modifier": -1, "processed_at": null, "received_amount": 0, "status": "created", "title": "Premium plan", "txid": null, "type": "token", "underpay_tolerance": 0.01, "user_id": null }
⌘I