Get started

Payment links

A payment link is a URL you can send anywhere: a chat, an email, a bio or a QR code. Each time someone opens it, they get a fresh hosted checkout and pay by card, Apple Pay, Google Pay or crypto. You don't need a website or API keys, just a Polygon wallet.

Two ways to make a link#

	Without API keys	With API keys
How	Send `payout_address` with no signature, or use the link page	Sign the request like any other call
Paid to	The wallet in `payout_address`	Your merchant's payout wallet
Webhooks	None. Payouts arrive in your wallet automatically	Yes, to your `callback_url`
See the checkouts	In your wallet's history	`GET /v1/checkouts` and `GET /v1/payment-links/{id}`
Turn a link off	Not possible: make a single-use link if you need it to close	`POST /v1/payment-links/{id}/deactivate`

A link made without keys returns no credentials, so nobody, including you, can read its checkouts through the API. That is what makes it safe to create one from a public page.

Create a payment link#

POST/v1/payment-links

Parameter	Description
`payout_address`stringwithout keys	Your Polygon wallet, `0x` and 40 hex characters. Use a plain wallet you control (MetaMask, Rabby, a hardware wallet), not an exchange deposit address or a smart-contract wallet. Only for links made without keys; a signed request that sends it gets `400`.
`amount`string or nullrequired	The price with exactly two decimals, like `"25.00"`, from `1.00` up to your per-checkout limit (`1000.00` for new merchants). Send `null` to let the buyer enter the amount.
`min_amount`, `max_amount`string	Only with `amount: null`. The range the buyer may enter. Default `1.00` to your per-checkout limit.
`currency`stringrequired	Always `"USD"`.
`description`string	Optional plain text, at most 80 characters, shown to the buyer as Note from the seller. No links, web addresses or HTML.
`reusable`boolean	Default `true`: anyone may pay through the link, any number of times. `false`: the link closes after one successful payment.
`callback_url`string	Signed links only. HTTPS on one of your merchant origins. Webhooks for this link's checkouts go here. Leave it out for no webhooks.
`return_url`string	Signed links only. Where the buyer goes after paying, on your merchant origins. Default: a neutral Caravel Pay "Payment received" page.

Without API keys#

No headers beyond Content-Type. The answer is the link's id and URL, nothing else.

POST /v1/payment-links (no keys)

curl https://api.caravelpay.app/v1/payment-links \
  -H "Content-Type: application/json" \
  --data-binary '{
    "payout_address": "0x52908400098527886E0F7030069857D2E4169EE7",
    "amount": "25.00",
    "currency": "USD",
    "description": "Logo design, 2 rounds"
  }'

// Node.js 18+ (built-in fetch). No keys needed.
const res = await fetch("https://api.caravelpay.app/v1/payment-links", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    payout_address: "0x52908400098527886E0F7030069857D2E4169EE7",
    amount: "25.00",
    currency: "USD",
    description: "Logo design, 2 rounds",
  }),
});
const link = await res.json();
if (!res.ok) throw new Error(`${link.error.code}: ${link.error.message}`);
console.log(link.url); // share this

<?php
// PHP 7.4+ with the curl extension. No keys needed.
$ch = curl_init('https://api.caravelpay.app/v1/payment-links');
curl_setopt_array($ch, [
    CURLOPT_POST           => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT        => 15,
    CURLOPT_HTTPHEADER     => ['Content-Type: application/json'],
    CURLOPT_POSTFIELDS     => json_encode([
        'payout_address' => '0x52908400098527886E0F7030069857D2E4169EE7',
        'amount'         => '25.00',
        'currency'       => 'USD',
        'description'    => 'Logo design, 2 rounds',
    ], JSON_UNESCAPED_SLASHES),
]);
$link = json_decode((string) curl_exec($ch), true);
if (curl_getinfo($ch, CURLINFO_HTTP_CODE) !== 201) {
    throw new RuntimeException(($link['error']['code'] ?? 'error') . ': ' . ($link['error']['message'] ?? ''));
}
echo $link['url'], "\n"; // share this

# Python 3.8+ with requests (pip install requests). No keys needed.
import requests

res = requests.post("https://api.caravelpay.app/v1/payment-links", timeout=15, json={
    "payout_address": "0x52908400098527886E0F7030069857D2E4169EE7",
    "amount": "25.00",
    "currency": "USD",
    "description": "Logo design, 2 rounds",
})
link = res.json()
if res.status_code != 201:
    raise RuntimeError(f"{link['error']['code']}: {link['error']['message']}")
print(link["url"])  # share this

201 Created

{
  "id": "lnk_K7Q2ZX4PRBM5TW3NHJ6D",
  "url": "https://pay.caravelpay.app/l/lnk_K7Q2ZX4PRBM5TW3NHJ6D"
}

Links for the same wallet share one behind-the-scenes merchant, with the same 2% Caravel fee and limits as any new merchant. The wallet is checked the same way as at connect: sanctioned addresses, contracts and Caravel Pay's own addresses are refused with 400 invalid_request, param: "payout_address". Each IP address may create 30 links an hour.

With API keys#

Signed like any request. The link belongs to your merchant: its checkouts show up in GET /v1/checkouts, and webhooks go to its callback_url.

POST /v1/payment-links (signed)

BODY='{"amount":"49.00","currency":"USD","description":"Workshop seat","reusable":false,"callback_url":"https://shop.example/webhooks/caravel"}'
TS=$(date +%s)
SIG=$(printf '%s\n%s\n%s\n%s' "$TS" POST /v1/payment-links "$BODY" \
  | openssl dgst -sha256 -hmac "$CARAVEL_SECRET" | awk '{print $NF}')

curl https://api.caravelpay.app/v1/payment-links \
  -H "Content-Type: application/json" \
  -H "Caravel-Merchant: $CARAVEL_MERCHANT" \
  -H "Caravel-Timestamp: $TS" \
  -H "Caravel-Signature: $SIG" \
  --data-binary "$BODY"

import { caravel } from "./caravel.mjs"; // signing helper from the Quickstart

const link = await caravel("POST", "/v1/payment-links", {
  amount: "49.00",
  currency: "USD",
  description: "Workshop seat",
  reusable: false,
  callback_url: "https://shop.example/webhooks/caravel",
});

require __DIR__ . '/caravel.php'; // signing helper from the Quickstart

$link = caravel('POST', '/v1/payment-links', [
    'amount'       => '49.00',
    'currency'     => 'USD',
    'description'  => 'Workshop seat',
    'reusable'     => false,
    'callback_url' => 'https://shop.example/webhooks/caravel',
]);

from caravel import caravel  # signing helper from the Quickstart

link = caravel("POST", "/v1/payment-links", {
    "amount": "49.00",
    "currency": "USD",
    "description": "Workshop seat",
    "reusable": False,
    "callback_url": "https://shop.example/webhooks/caravel",
})

201 Created

{
  "id": "lnk_M5TW3NHJ6DK7Q2ZX4PRB",
  "url": "https://pay.caravelpay.app/l/lnk_M5TW3NHJ6DK7Q2ZX4PRB",
  "status": "active",
  "amount": "49.00",
  "min_amount": null,
  "max_amount": null,
  "currency": "USD",
  "description": "Workshop seat",
  "reusable": false,
  "return_url": null,
  "callback_url": "https://shop.example/webhooks/caravel",
  "payments_count": 0,
  "checkouts_count": 0,
  "created_at": "2026-11-09T21:04:12Z",
  "deactivated_at": null
}

Let the buyer choose the amount#

Send "amount": null for tips, donations or invoices of varying size. The buyer first sees a short "Enter the amount to pay" step, then the normal checkout. Set min_amount and max_amount to narrow the range.

Request body

{
  "payout_address": "0x52908400098527886E0F7030069857D2E4169EE7",
  "amount": null,
  "min_amount": "5.00",
  "max_amount": "250.00",
  "currency": "USD",
  "description": "Tips for the crew"
}

The payment link object#

Returned by the signed calls. Links made without keys return only id and url.

Field	Description
`id`string	`lnk_` and 20 characters.
`url`string	The link to share.
`status`string	`active`, `completed` (a single-use link that has been paid) or `deactivated`.
`amount`string or null	The fixed price, or `null` when the buyer enters it.
`min_amount`, `max_amount`string or null	The buyer's range for an open amount; `null` for a fixed price.
`currency`string	`"USD"`.
`description`string or null	The note shown to the buyer.
`reusable`boolean	Whether more than one payment may be made.
`return_url`, `callback_url`string or null	As sent.
`payments_count`integer	Checkouts from this link that are paid.
`checkouts_count`integer	Checkouts opened from this link, paid or not.
`created_at`, `deactivated_at`string	ISO 8601 UTC. `deactivated_at` is `null` until you deactivate the link.

Retrieve a payment link#

GET/v1/payment-links/{id}

Signed, with an empty body. A link that isn't yours answers 404 not_found, exactly like one that doesn't exist.

GET /v1/payment-links/{id}

LINK=lnk_M5TW3NHJ6DK7Q2ZX4PRB
TS=$(date +%s)
SIG=$(printf '%s\n%s\n%s\n%s' "$TS" GET "/v1/payment-links/$LINK" "" \
  | openssl dgst -sha256 -hmac "$CARAVEL_SECRET" | awk '{print $NF}')

curl "https://api.caravelpay.app/v1/payment-links/$LINK" \
  -H "Caravel-Merchant: $CARAVEL_MERCHANT" \
  -H "Caravel-Timestamp: $TS" \
  -H "Caravel-Signature: $SIG"

const link = await caravel("GET", "/v1/payment-links/lnk_M5TW3NHJ6DK7Q2ZX4PRB");
console.log(link.status, link.payments_count);

$link = caravel('GET', '/v1/payment-links/lnk_M5TW3NHJ6DK7Q2ZX4PRB');
echo $link['status'], ' ', $link['payments_count'], "\n";

link = caravel("GET", "/v1/payment-links/lnk_M5TW3NHJ6DK7Q2ZX4PRB")
print(link["status"], link["payments_count"])

Deactivate a payment link#

POST/v1/payment-links/{id}/deactivate

Signed, with an empty body or {}. The link stops opening new checkouts at once and buyers see "This payment link is no longer active". Checkouts that were already open can still be paid, and those payouts reach you as usual. Calling it again changes nothing. There is no way to turn a link back on: create a new one.

POST /v1/payment-links/{id}/deactivate

LINK=lnk_M5TW3NHJ6DK7Q2ZX4PRB
TS=$(date +%s)
SIG=$(printf '%s\n%s\n%s\n%s' "$TS" POST "/v1/payment-links/$LINK/deactivate" "" \
  | openssl dgst -sha256 -hmac "$CARAVEL_SECRET" | awk '{print $NF}')

curl -X POST "https://api.caravelpay.app/v1/payment-links/$LINK/deactivate" \
  -H "Caravel-Merchant: $CARAVEL_MERCHANT" \
  -H "Caravel-Timestamp: $TS" \
  -H "Caravel-Signature: $SIG"

const link = await caravel("POST", "/v1/payment-links/lnk_M5TW3NHJ6DK7Q2ZX4PRB/deactivate");

$link = caravel('POST', '/v1/payment-links/lnk_M5TW3NHJ6DK7Q2ZX4PRB/deactivate');

link = caravel("POST", "/v1/payment-links/lnk_M5TW3NHJ6DK7Q2ZX4PRB/deactivate")

200 OK (excerpt)

{
  "id": "lnk_M5TW3NHJ6DK7Q2ZX4PRB",
  "status": "deactivated",
  "deactivated_at": "2026-11-10T09:30:00Z"
}

What the buyer sees#

They open the link. A fixed price continues straight to the checkout; an open amount asks for the amount first.
The hosted checkout shows the amount and your note, never a store name or logo, and lets them pay by card, Apple Pay, Google Pay or crypto. Any card provider fee is shown before they pay.
After paying they land on a neutral "Payment received" page (or your return_url for a signed link).

Every opening creates a new checkout with order id lnk_…-1, lnk_…-2 and so on. A buyer who opens the link again in the same browser session gets their unpaid checkout back instead of a new one. Each checkout expires 60 minutes after it opens, like any other.

Webhooks and reconciliation#

For a signed link with a callback_url, each checkout sends the usual webhooks; the checkout's order_id starts with the link id. Links made without keys send no webhooks: watch your wallet, where each payout arrives automatically.

Single-use links: the link closes after its first paid checkout, and while a payment is confirming nobody else can start one. A buyer who opened the link earlier can still finish their checkout, and that payment reaches you as usual.

Fees#

The same as any payment: you receive the amount minus the flat 2% Caravel Pay fee, in your wallet, automatically once the payment confirms. The buyer pays their card provider's fee, shown to them before they pay.

Errors#

Code	When
`invalid_amount` 400	`amount`, `min_amount` or `max_amount` isn't a two-decimal string in range, or `min_amount` is above `max_amount`.
`invalid_request` 400	A missing or unknown field, a bad `payout_address` or wallet, or a `description` with a link, HTML or more than 80 characters. `param` names the field.
`invalid_url` 400	`callback_url` or `return_url` isn't HTTPS on your merchant origins.
`unsupported_currency` 400	`currency` isn't `"USD"`.
`merchant_paused` 403	Payments to this wallet or merchant are paused.
`not_found` 404	No link with that id belongs to your merchant.
`limit_exceeded` 409	The wallet already receives payouts for the most merchants allowed.
`rate_limited` 429	Too many links from your address. Wait for `Retry-After`.

All codes and the retry rules are on Errors.