curl --request GET \
--url https://api.natural.com/payment-requests \
--header 'Authorization: Bearer <token>'import requests
url = "https://api.natural.com/payment-requests"
headers = {"Authorization": "Bearer <token>"}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};
fetch('https://api.natural.com/payment-requests', 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.natural.com/payment-requests",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://api.natural.com/payment-requests"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("Authorization", "Bearer <token>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.get("https://api.natural.com/payment-requests")
.header("Authorization", "Bearer <token>")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.natural.com/payment-requests")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'
response = http.request(request)
puts response.read_body{
"data": [
{
"type": "paymentRequest",
"id": "prq_019cd1798d7a68fe07c972bed48fb7fd",
"attributes": {
"amount": 2500,
"currency": "USD",
"fee": null,
"status": "OPEN",
"payerCanPay": true,
"payerCanDecline": true,
"description": "Invoice 7",
"tags": {
"invoice_id": "inv_7"
},
"requesterName": "Acme Payments",
"requesterEmail": "billing@acmepayments.com",
"requesterAvatarUrl": "https://ntl-public-assets-prod.s3.us-west-2.amazonaws.com/party-avatars/pty_019cd1798d617f65a79cb965dda9eac3/2026-01-04_ab12cd34ef56ab90.webp",
"requesterHandle": "@acme",
"walletName": "Operating",
"payerName": "Ada Lovelace",
"payerEmail": "ada@example.com",
"payerPhone": "+14155550100",
"payerAvatarUrl": "https://static.natural.com/avatars/ada-lovelace.png",
"payerHandle": "@ada-lovelace",
"payerPartyId": "pty_019cd1798d681091fcf1dc98afb72d01",
"payerIdentifierType": "email",
"payerIdentifier": "ada@example.com",
"initiatorParty": {
"id": "pty_019cd1798d617f65a79cb965dda9eac3",
"name": "Acme Payments",
"handle": "@acme"
},
"paymentLinkUrl": "https://www.natural.com/pay/token_123",
"transactionId": null,
"expiresAt": null,
"createdAt": "2026-04-15T00:00:00.000Z",
"updatedAt": "2026-04-15T00:00:00.000Z"
},
"relationships": {
"initiatorAgent": {
"data": {
"type": "agent",
"id": "agt_019cd1798d637a4da75dce386343931d"
}
},
"requesterParty": {
"data": {
"type": "party",
"id": "pty_019cd1798d617f65a79cb965dda9eac3"
}
},
"wallet": {
"data": {
"type": "wallet",
"id": "wal_019cd1798d714ce765e0486a417c23dc"
}
},
"payerParty": {
"data": {
"type": "party",
"id": "pty_019cd1798d681091fcf1dc98afb72d01"
}
},
"payerAgent": {
"data": null
},
"payment": {
"data": null
}
}
}
],
"meta": {
"pagination": {
"hasMore": false,
"nextCursor": null
}
}
}{
"errors": [
{
"code": "invalid_value",
"detail": "The information you entered isn't valid. Please check it and try again.",
"status": "400",
"meta": {
"supportId": "req_a1b2c3d4e5f6"
}
}
]
}{
"errors": [
{
"code": "unauthenticated",
"detail": "Authentication is required.",
"status": "401",
"meta": {
"supportId": "req_a1b2c3d4e5f6"
}
}
]
}{
"errors": [
{
"code": "forbidden",
"detail": "You do not have permission to perform this action.",
"status": "403",
"meta": {
"supportId": "req_a1b2c3d4e5f6"
}
}
]
}{
"errors": [
{
"code": "not_found",
"detail": "The requested resource was not found.",
"status": "404",
"meta": {
"supportId": "req_a1b2c3d4e5f6"
}
}
]
}{
"errors": [
{
"code": "conflict",
"detail": "The request conflicts with the current resource state.",
"status": "409",
"meta": {
"supportId": "req_a1b2c3d4e5f6"
}
}
]
}{
"errors": [
{
"code": "invalid_value",
"detail": "Too big: expected string to have <=80 characters",
"status": "422",
"source": {
"pointer": "/data/attributes/description"
},
"meta": {
"supportId": "req_a1b2c3d4e5f6"
}
}
]
}{
"errors": [
{
"code": "mfa_required",
"detail": "MFA verification required",
"status": "428",
"meta": {
"supportId": "req_a1b2c3d4e5f6"
}
}
]
}{
"errors": [
{
"code": "rate_limited",
"detail": "Too many requests. Please try again later.",
"status": "429",
"meta": {
"supportId": "req_a1b2c3d4e5f6"
}
}
]
}{
"errors": [
{
"code": "server_error",
"detail": "Something went wrong.",
"status": "500",
"meta": {
"supportId": "req_a1b2c3d4e5f6"
}
}
]
}{
"errors": [
{
"code": "not_implemented",
"detail": "This operation is not available.",
"status": "501",
"meta": {
"supportId": "req_a1b2c3d4e5f6"
}
}
]
}{
"errors": [
{
"code": "bad_gateway",
"detail": "We couldn't complete that request because one of Natural's services returned an unexpected response. Please try again.",
"status": "502",
"meta": {
"supportId": "req_a1b2c3d4e5f6"
}
}
]
}{
"errors": [
{
"code": "service_unavailable",
"detail": "The service is temporarily unavailable.",
"status": "503",
"meta": {
"supportId": "req_a1b2c3d4e5f6"
}
}
]
}List payment requests
List outgoing payment requests
curl --request GET \
--url https://api.natural.com/payment-requests \
--header 'Authorization: Bearer <token>'import requests
url = "https://api.natural.com/payment-requests"
headers = {"Authorization": "Bearer <token>"}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};
fetch('https://api.natural.com/payment-requests', 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.natural.com/payment-requests",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://api.natural.com/payment-requests"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("Authorization", "Bearer <token>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.get("https://api.natural.com/payment-requests")
.header("Authorization", "Bearer <token>")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.natural.com/payment-requests")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'
response = http.request(request)
puts response.read_body{
"data": [
{
"type": "paymentRequest",
"id": "prq_019cd1798d7a68fe07c972bed48fb7fd",
"attributes": {
"amount": 2500,
"currency": "USD",
"fee": null,
"status": "OPEN",
"payerCanPay": true,
"payerCanDecline": true,
"description": "Invoice 7",
"tags": {
"invoice_id": "inv_7"
},
"requesterName": "Acme Payments",
"requesterEmail": "billing@acmepayments.com",
"requesterAvatarUrl": "https://ntl-public-assets-prod.s3.us-west-2.amazonaws.com/party-avatars/pty_019cd1798d617f65a79cb965dda9eac3/2026-01-04_ab12cd34ef56ab90.webp",
"requesterHandle": "@acme",
"walletName": "Operating",
"payerName": "Ada Lovelace",
"payerEmail": "ada@example.com",
"payerPhone": "+14155550100",
"payerAvatarUrl": "https://static.natural.com/avatars/ada-lovelace.png",
"payerHandle": "@ada-lovelace",
"payerPartyId": "pty_019cd1798d681091fcf1dc98afb72d01",
"payerIdentifierType": "email",
"payerIdentifier": "ada@example.com",
"initiatorParty": {
"id": "pty_019cd1798d617f65a79cb965dda9eac3",
"name": "Acme Payments",
"handle": "@acme"
},
"paymentLinkUrl": "https://www.natural.com/pay/token_123",
"transactionId": null,
"expiresAt": null,
"createdAt": "2026-04-15T00:00:00.000Z",
"updatedAt": "2026-04-15T00:00:00.000Z"
},
"relationships": {
"initiatorAgent": {
"data": {
"type": "agent",
"id": "agt_019cd1798d637a4da75dce386343931d"
}
},
"requesterParty": {
"data": {
"type": "party",
"id": "pty_019cd1798d617f65a79cb965dda9eac3"
}
},
"wallet": {
"data": {
"type": "wallet",
"id": "wal_019cd1798d714ce765e0486a417c23dc"
}
},
"payerParty": {
"data": {
"type": "party",
"id": "pty_019cd1798d681091fcf1dc98afb72d01"
}
},
"payerAgent": {
"data": null
},
"payment": {
"data": null
}
}
}
],
"meta": {
"pagination": {
"hasMore": false,
"nextCursor": null
}
}
}{
"errors": [
{
"code": "invalid_value",
"detail": "The information you entered isn't valid. Please check it and try again.",
"status": "400",
"meta": {
"supportId": "req_a1b2c3d4e5f6"
}
}
]
}{
"errors": [
{
"code": "unauthenticated",
"detail": "Authentication is required.",
"status": "401",
"meta": {
"supportId": "req_a1b2c3d4e5f6"
}
}
]
}{
"errors": [
{
"code": "forbidden",
"detail": "You do not have permission to perform this action.",
"status": "403",
"meta": {
"supportId": "req_a1b2c3d4e5f6"
}
}
]
}{
"errors": [
{
"code": "not_found",
"detail": "The requested resource was not found.",
"status": "404",
"meta": {
"supportId": "req_a1b2c3d4e5f6"
}
}
]
}{
"errors": [
{
"code": "conflict",
"detail": "The request conflicts with the current resource state.",
"status": "409",
"meta": {
"supportId": "req_a1b2c3d4e5f6"
}
}
]
}{
"errors": [
{
"code": "invalid_value",
"detail": "Too big: expected string to have <=80 characters",
"status": "422",
"source": {
"pointer": "/data/attributes/description"
},
"meta": {
"supportId": "req_a1b2c3d4e5f6"
}
}
]
}{
"errors": [
{
"code": "mfa_required",
"detail": "MFA verification required",
"status": "428",
"meta": {
"supportId": "req_a1b2c3d4e5f6"
}
}
]
}{
"errors": [
{
"code": "rate_limited",
"detail": "Too many requests. Please try again later.",
"status": "429",
"meta": {
"supportId": "req_a1b2c3d4e5f6"
}
}
]
}{
"errors": [
{
"code": "server_error",
"detail": "Something went wrong.",
"status": "500",
"meta": {
"supportId": "req_a1b2c3d4e5f6"
}
}
]
}{
"errors": [
{
"code": "not_implemented",
"detail": "This operation is not available.",
"status": "501",
"meta": {
"supportId": "req_a1b2c3d4e5f6"
}
}
]
}{
"errors": [
{
"code": "bad_gateway",
"detail": "We couldn't complete that request because one of Natural's services returned an unexpected response. Please try again.",
"status": "502",
"meta": {
"supportId": "req_a1b2c3d4e5f6"
}
}
]
}{
"errors": [
{
"code": "service_unavailable",
"detail": "The service is temporarily unavailable.",
"status": "503",
"meta": {
"supportId": "req_a1b2c3d4e5f6"
}
}
]
}Authorizations
Bearer authentication: send your API key, agent key, or OAuth access token as Authorization: Bearer <credential>.
Headers
Caller-chosen identifier for the agent run, session, or conversation, required when an agent moves money.
1024Query Parameters
Maximum results per page.
1 <= x <= 100Cursor from the previous page.
1024Customer party to act for (pty_*). Omit to act as your own party. To act for another party, pass the ID of a party that has authorized you to act on its behalf.
^pty_[0-9a-f]{32}$Whether to include completed payment requests.
Whether to include canceled payment requests.
Limit the list to one outgoing group. Open is still waiting on the payer. Completed is in flight or settled and not returned. Closed is failed, declined, canceled, expired, and returned. When set, this replaces includeCompleted and includeCanceled.
open, completed, closed Only payment requests created by this agent (agt_*).
^agt_[0-9a-f]{32}$Only payment requests addressed to this agent (agt_*) as payer.
^agt_[0-9a-f]{32}$Was this page helpful?