Create a payment
curl --request POST \
--url https://api.example.com/v1/payments \
--header 'Content-Type: application/json' \
--header 'X-API-Key: <api-key>' \
--data '
{
"externalId": "INV-2026-00042",
"amount": "12500.00",
"currency": "USD",
"sellerExternalId": "seller-42",
"buyer": {
"email": "buyer@acme.com",
"name": "ACME Imports LLC",
"country": "US"
},
"returnUrl": "https://shop.example.com/orders/42/return",
"metadata": {
"orderId": "order_42",
"source": "storefront"
},
"display": {
"title": "Order #42 — green coffee, 18t",
"lineItems": [
{
"description": "Green coffee, 18t",
"quantity": "1",
"unitPrice": "12500.00",
"subtotal": "12500.00"
}
]
}
}
'import requests
url = "https://api.example.com/v1/payments"
payload = {
"externalId": "INV-2026-00042",
"amount": "12500.00",
"currency": "USD",
"sellerExternalId": "seller-42",
"buyer": {
"email": "buyer@acme.com",
"name": "ACME Imports LLC",
"country": "US"
},
"returnUrl": "https://shop.example.com/orders/42/return",
"metadata": {
"orderId": "order_42",
"source": "storefront"
},
"display": {
"title": "Order #42 — green coffee, 18t",
"lineItems": [
{
"description": "Green coffee, 18t",
"quantity": "1",
"unitPrice": "12500.00",
"subtotal": "12500.00"
}
]
}
}
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({
externalId: 'INV-2026-00042',
amount: '12500.00',
currency: 'USD',
sellerExternalId: 'seller-42',
buyer: {email: 'buyer@acme.com', name: 'ACME Imports LLC', country: 'US'},
returnUrl: 'https://shop.example.com/orders/42/return',
metadata: {orderId: 'order_42', source: 'storefront'},
display: {
title: 'Order #42 — green coffee, 18t',
lineItems: [
{
description: 'Green coffee, 18t',
quantity: '1',
unitPrice: '12500.00',
subtotal: '12500.00'
}
]
}
})
};
fetch('https://api.example.com/v1/payments', 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.example.com/v1/payments",
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([
'externalId' => 'INV-2026-00042',
'amount' => '12500.00',
'currency' => 'USD',
'sellerExternalId' => 'seller-42',
'buyer' => [
'email' => 'buyer@acme.com',
'name' => 'ACME Imports LLC',
'country' => 'US'
],
'returnUrl' => 'https://shop.example.com/orders/42/return',
'metadata' => [
'orderId' => 'order_42',
'source' => 'storefront'
],
'display' => [
'title' => 'Order #42 — green coffee, 18t',
'lineItems' => [
[
'description' => 'Green coffee, 18t',
'quantity' => '1',
'unitPrice' => '12500.00',
'subtotal' => '12500.00'
]
]
]
]),
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.example.com/v1/payments"
payload := strings.NewReader("{\n \"externalId\": \"INV-2026-00042\",\n \"amount\": \"12500.00\",\n \"currency\": \"USD\",\n \"sellerExternalId\": \"seller-42\",\n \"buyer\": {\n \"email\": \"buyer@acme.com\",\n \"name\": \"ACME Imports LLC\",\n \"country\": \"US\"\n },\n \"returnUrl\": \"https://shop.example.com/orders/42/return\",\n \"metadata\": {\n \"orderId\": \"order_42\",\n \"source\": \"storefront\"\n },\n \"display\": {\n \"title\": \"Order #42 — green coffee, 18t\",\n \"lineItems\": [\n {\n \"description\": \"Green coffee, 18t\",\n \"quantity\": \"1\",\n \"unitPrice\": \"12500.00\",\n \"subtotal\": \"12500.00\"\n }\n ]\n }\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.example.com/v1/payments")
.header("X-API-Key", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"externalId\": \"INV-2026-00042\",\n \"amount\": \"12500.00\",\n \"currency\": \"USD\",\n \"sellerExternalId\": \"seller-42\",\n \"buyer\": {\n \"email\": \"buyer@acme.com\",\n \"name\": \"ACME Imports LLC\",\n \"country\": \"US\"\n },\n \"returnUrl\": \"https://shop.example.com/orders/42/return\",\n \"metadata\": {\n \"orderId\": \"order_42\",\n \"source\": \"storefront\"\n },\n \"display\": {\n \"title\": \"Order #42 — green coffee, 18t\",\n \"lineItems\": [\n {\n \"description\": \"Green coffee, 18t\",\n \"quantity\": \"1\",\n \"unitPrice\": \"12500.00\",\n \"subtotal\": \"12500.00\"\n }\n ]\n }\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.example.com/v1/payments")
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 \"externalId\": \"INV-2026-00042\",\n \"amount\": \"12500.00\",\n \"currency\": \"USD\",\n \"sellerExternalId\": \"seller-42\",\n \"buyer\": {\n \"email\": \"buyer@acme.com\",\n \"name\": \"ACME Imports LLC\",\n \"country\": \"US\"\n },\n \"returnUrl\": \"https://shop.example.com/orders/42/return\",\n \"metadata\": {\n \"orderId\": \"order_42\",\n \"source\": \"storefront\"\n },\n \"display\": {\n \"title\": \"Order #42 — green coffee, 18t\",\n \"lineItems\": [\n {\n \"description\": \"Green coffee, 18t\",\n \"quantity\": \"1\",\n \"unitPrice\": \"12500.00\",\n \"subtotal\": \"12500.00\"\n }\n ]\n }\n}"
response = http.request(request)
puts response.read_body{
"id": "ckxinv042",
"externalId": "INV-2026-00042",
"status": "awaiting_buyer",
"amount": "12500.00",
"currency": "USD",
"hostedPaymentUrl": "https://pay.caratuva.com/i/ckpub042",
"buyer": {
"id": "ckbuy001",
"email": "buyer@acme.com",
"name": "ACME Imports LLC",
"country": "US",
"kycStatus": "not_started"
},
"returnUrl": "https://shop.example.com/orders/42/return",
"metadata": {
"orderId": "order_42",
"source": "storefront"
},
"display": {
"title": "Order #42 — green coffee, 18t",
"lineItems": [
{
"description": "Green coffee, 18t",
"quantity": "1",
"unitPrice": "12500.00",
"subtotal": "12500.00"
}
]
},
"paymentChain": "base",
"paymentAddress": "0x5fbe…a91c",
"brlSettledAmount": null,
"fxRateAtSettlement": null,
"expiresAt": null,
"cancelReason": null,
"createdAt": "2026-06-30T12:00:00.000Z",
"updatedAt": "2026-06-30T12:00:00.000Z"
}{
"statusCode": 400,
"error": "AmountBelowMinimum",
"message": "The amount is below the bank-transfer on-ramp minimum (also: the seller is not ready-to-collect, or neither buyerExternalId nor a buyer object was provided)."
}Payments
Create a payment
Integrator-facing: keep your own CMS and push a thin intent describing what to collect, where to settle, and what to render on the hosted buyer-portal page. Caratuva runs the payment, mandatory buyer KYC, on-chain transfer, and PIX off-ramp. Name the seller with sellerExternalId (a ready-to-collect connected account) and the buyer with either buyerExternalId (a pre-created account, KYC reused) or a buyer object (email required, KYC’d at pay-time). Send an Idempotency-Key header to make retries safe. Returns the hostedPaymentUrl to forward to your customer.
POST
/
v1
/
payments
Create a payment
curl --request POST \
--url https://api.example.com/v1/payments \
--header 'Content-Type: application/json' \
--header 'X-API-Key: <api-key>' \
--data '
{
"externalId": "INV-2026-00042",
"amount": "12500.00",
"currency": "USD",
"sellerExternalId": "seller-42",
"buyer": {
"email": "buyer@acme.com",
"name": "ACME Imports LLC",
"country": "US"
},
"returnUrl": "https://shop.example.com/orders/42/return",
"metadata": {
"orderId": "order_42",
"source": "storefront"
},
"display": {
"title": "Order #42 — green coffee, 18t",
"lineItems": [
{
"description": "Green coffee, 18t",
"quantity": "1",
"unitPrice": "12500.00",
"subtotal": "12500.00"
}
]
}
}
'import requests
url = "https://api.example.com/v1/payments"
payload = {
"externalId": "INV-2026-00042",
"amount": "12500.00",
"currency": "USD",
"sellerExternalId": "seller-42",
"buyer": {
"email": "buyer@acme.com",
"name": "ACME Imports LLC",
"country": "US"
},
"returnUrl": "https://shop.example.com/orders/42/return",
"metadata": {
"orderId": "order_42",
"source": "storefront"
},
"display": {
"title": "Order #42 — green coffee, 18t",
"lineItems": [
{
"description": "Green coffee, 18t",
"quantity": "1",
"unitPrice": "12500.00",
"subtotal": "12500.00"
}
]
}
}
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({
externalId: 'INV-2026-00042',
amount: '12500.00',
currency: 'USD',
sellerExternalId: 'seller-42',
buyer: {email: 'buyer@acme.com', name: 'ACME Imports LLC', country: 'US'},
returnUrl: 'https://shop.example.com/orders/42/return',
metadata: {orderId: 'order_42', source: 'storefront'},
display: {
title: 'Order #42 — green coffee, 18t',
lineItems: [
{
description: 'Green coffee, 18t',
quantity: '1',
unitPrice: '12500.00',
subtotal: '12500.00'
}
]
}
})
};
fetch('https://api.example.com/v1/payments', 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.example.com/v1/payments",
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([
'externalId' => 'INV-2026-00042',
'amount' => '12500.00',
'currency' => 'USD',
'sellerExternalId' => 'seller-42',
'buyer' => [
'email' => 'buyer@acme.com',
'name' => 'ACME Imports LLC',
'country' => 'US'
],
'returnUrl' => 'https://shop.example.com/orders/42/return',
'metadata' => [
'orderId' => 'order_42',
'source' => 'storefront'
],
'display' => [
'title' => 'Order #42 — green coffee, 18t',
'lineItems' => [
[
'description' => 'Green coffee, 18t',
'quantity' => '1',
'unitPrice' => '12500.00',
'subtotal' => '12500.00'
]
]
]
]),
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.example.com/v1/payments"
payload := strings.NewReader("{\n \"externalId\": \"INV-2026-00042\",\n \"amount\": \"12500.00\",\n \"currency\": \"USD\",\n \"sellerExternalId\": \"seller-42\",\n \"buyer\": {\n \"email\": \"buyer@acme.com\",\n \"name\": \"ACME Imports LLC\",\n \"country\": \"US\"\n },\n \"returnUrl\": \"https://shop.example.com/orders/42/return\",\n \"metadata\": {\n \"orderId\": \"order_42\",\n \"source\": \"storefront\"\n },\n \"display\": {\n \"title\": \"Order #42 — green coffee, 18t\",\n \"lineItems\": [\n {\n \"description\": \"Green coffee, 18t\",\n \"quantity\": \"1\",\n \"unitPrice\": \"12500.00\",\n \"subtotal\": \"12500.00\"\n }\n ]\n }\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.example.com/v1/payments")
.header("X-API-Key", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"externalId\": \"INV-2026-00042\",\n \"amount\": \"12500.00\",\n \"currency\": \"USD\",\n \"sellerExternalId\": \"seller-42\",\n \"buyer\": {\n \"email\": \"buyer@acme.com\",\n \"name\": \"ACME Imports LLC\",\n \"country\": \"US\"\n },\n \"returnUrl\": \"https://shop.example.com/orders/42/return\",\n \"metadata\": {\n \"orderId\": \"order_42\",\n \"source\": \"storefront\"\n },\n \"display\": {\n \"title\": \"Order #42 — green coffee, 18t\",\n \"lineItems\": [\n {\n \"description\": \"Green coffee, 18t\",\n \"quantity\": \"1\",\n \"unitPrice\": \"12500.00\",\n \"subtotal\": \"12500.00\"\n }\n ]\n }\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.example.com/v1/payments")
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 \"externalId\": \"INV-2026-00042\",\n \"amount\": \"12500.00\",\n \"currency\": \"USD\",\n \"sellerExternalId\": \"seller-42\",\n \"buyer\": {\n \"email\": \"buyer@acme.com\",\n \"name\": \"ACME Imports LLC\",\n \"country\": \"US\"\n },\n \"returnUrl\": \"https://shop.example.com/orders/42/return\",\n \"metadata\": {\n \"orderId\": \"order_42\",\n \"source\": \"storefront\"\n },\n \"display\": {\n \"title\": \"Order #42 — green coffee, 18t\",\n \"lineItems\": [\n {\n \"description\": \"Green coffee, 18t\",\n \"quantity\": \"1\",\n \"unitPrice\": \"12500.00\",\n \"subtotal\": \"12500.00\"\n }\n ]\n }\n}"
response = http.request(request)
puts response.read_body{
"id": "ckxinv042",
"externalId": "INV-2026-00042",
"status": "awaiting_buyer",
"amount": "12500.00",
"currency": "USD",
"hostedPaymentUrl": "https://pay.caratuva.com/i/ckpub042",
"buyer": {
"id": "ckbuy001",
"email": "buyer@acme.com",
"name": "ACME Imports LLC",
"country": "US",
"kycStatus": "not_started"
},
"returnUrl": "https://shop.example.com/orders/42/return",
"metadata": {
"orderId": "order_42",
"source": "storefront"
},
"display": {
"title": "Order #42 — green coffee, 18t",
"lineItems": [
{
"description": "Green coffee, 18t",
"quantity": "1",
"unitPrice": "12500.00",
"subtotal": "12500.00"
}
]
},
"paymentChain": "base",
"paymentAddress": "0x5fbe…a91c",
"brlSettledAmount": null,
"fxRateAtSettlement": null,
"expiresAt": null,
"cancelReason": null,
"createdAt": "2026-06-30T12:00:00.000Z",
"updatedAt": "2026-06-30T12:00:00.000Z"
}{
"statusCode": 400,
"error": "AmountBelowMinimum",
"message": "The amount is below the bank-transfer on-ramp minimum (also: the seller is not ready-to-collect, or neither buyerExternalId nor a buyer object was provided)."
}Authorizations
apiKeybearer
Headers
Body
application/json
Required string length:
1 - 200Pattern:
^\d+(\.\d{1,2})?$Required string length:
1 - 200Required string length:
3Required string length:
1 - 200Show child attributes
Show child attributes
Show child attributes
Show child attributes
Show child attributes
Show child attributes
Show child attributes
Show child attributes
Response
Payment created
Available options:
draft, awaiting_approval, approved, awaiting_buyer, buyer_kyc_pending, buyer_kyc_approved, buyer_kyc_rejected, fx_quoted, fx_expired, on_ramp_pending, on_ramp_failed, fiat_received, on_chain_confirmed, offramp_pending, offramp_failed, settled, partial_payment, expired, cancelled, restored, manual_review Show child attributes
Show child attributes
Show child attributes
Show child attributes
Show child attributes
Show child attributes
Show child attributes
Show child attributes
⌘I