pineplechainDocs

Guides

Payment links

XRP charges with a ready-made checkout: direct, or with escrow for orders with delivery.

A payment link (invoice) is a charge with its own checkout page. It can be direct, where the XRP goes straight to your wallet, or use escrow, where the funds stay locked on the XRPL until delivery.

Create a link

curl -X POST https://api.pineplechain.com/v1/invoices \
  -H "x-api-key: $PINEPLECHAIN_API_KEY" \
  -H "content-type: application/json" \
  -H "idempotency-key: order-1842" \
  -d '{ "amount": "250", "description": "Order #1842", "expires_in_hours": 48 }'
FieldTypeRequiredDescription
amountstringyesAmount in XRP, up to 6 decimals. Minimum "0.001".
descriptionstringnoUp to 200 characters. Shown on the checkout.
expires_in_hoursintegerno1 to 720. Default: 72.
kinddirect or escrownoDefault: direct.
cancel_afterISO dateescrow onlyBetween 1 hour and 365 days from now.
metadataobjectnoUp to 20 keys (40 characters) with values up to 500 characters.

Before you create

The receiving wallet must be connected and activated on the XRPL (otherwise: 422). In production, the business needs an approved verification (403 kyb-required) and no overdue invoice (402 fees-overdue).

Direct or escrow

Directopenpaid

The customer sends a Payment to your wallet, and the charge becomes paid once the XRPL validates the transaction.

Escrowopenlockedreleasingreleased

The funds are locked in an XRPL escrow. The payer releases them on the checkout once the order arrives. If they do not release by cancel_after, the funds go back to them (refunding › refunded). An escrow link stops accepting payments 30 minutes before cancel_after.

Escrow link
curl -X POST https://api.pineplechain.com/v1/invoices \
  -H "x-api-key: $PINEPLECHAIN_API_KEY" \
  -H "content-type: application/json" \
  -H "idempotency-key: pedido-1843" \
  -d '{
    "amount": "1200",
    "description": "Order #1843",
    "kind": "escrow",
    "cancel_after": "2026-11-15T12:00:00Z"
  }'

Any link still open can end as expired (past expires_at) or cancelled.

Retrieve, list and cancel

GET/invoices/{id}

Retrieves a link. Every call re-reads the XRPL.

GET/invoices

Lists links, newest first. status filter.

POST/invoices/{id}/cancellations

Cancels a link that is still open. No body.

curl "https://api.pineplechain.com/v1/invoices?limit=20&status=paid" \
  -H "x-api-key: $PINEPLECHAIN_API_KEY"

Something wrong on this page? Let us know.