API reference

The Merchant API is used by your server to create and query payment orders. API keys must be stored server-side.

Base URL

https://api.tariapay.com/v1

Authentication

Bearer token is recommended:

Authorization: Bearer tpk_...

Also accepted for compatibility:

x-api-key: tpk_...

If the API key is missing, invalid, or revoked, the API returns 401.

Core endpoints

Method	Path	Purpose
POST	/payment-intents	Create a new payment order
GET	/payment-intents	List orders, or look up by orderId
GET	/payment-intents/:paymentId	Retrieve a single payment order
POST	/payment-intents/:paymentId/refunds	Refund a confirmed payment in full to the original payer wallet
GET	/refunds	List merchant refunds

Public checkout endpoints

These endpoints are used by Hosted Checkout, the Checkout Button, and the Checkout Panel; ordinary merchants normally don't call them directly. The Button path only needs your server to return the checkoutUrl; only the Panel path requires passing the paymentId to the frontend.

Method	Path	Purpose
GET	/checkout/v1/payment-intents/:paymentId	Read public checkout data
POST	/checkout/v1/payment-intents/:paymentId/attempts	Create the payment configuration after the buyer selects a network and currency
POST	/checkout/v1/payment-intents/:paymentId/sync	Sync the on-chain receipt after the buyer submits a transaction
POST	/checkout/v1/payment-intents/:paymentId/transfer-status	Transfer payments: check whether funds have arrived at the order's dedicated deposit address

The :paymentId on these public endpoints accepts both the bare UUID and the pi_<uuid> form. The legacy /prepare endpoint is kept for compatibility only — do not use it in new integrations.

Subscription endpoints

For merchants with their own customer system managing subscriptions — see Subscriptions (API).

Method	Path	Purpose
POST	/subscription-plans	Create a plan (price object)
GET	/subscription-plans	List plans
GET	/subscription-plans/:planId	Retrieve a single plan
PATCH	/subscription-plans/:planId	Update a plan
POST	/subscriptions	Open a subscription for a customer; returns the subscription, invoice, and payment link
GET	/subscriptions	List subscriptions, filterable by customerId / planId
GET	/subscriptions/:id	Retrieve a single subscription
GET	/subscriptions/:id/invoices	List a subscription's billing-period invoices
POST	/subscriptions/:id/cancel	Cancel a subscription

Creating a payment order

curl -X POST "https://api.tariapay.com/v1/payment-intents" \
  -H "Authorization: Bearer tpk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "orderId": "order_1001",
    "amount": "12.50",
    "currency": "USDC",
    "successUrl": "https://merchant.example/success",
    "cancelUrl": "https://merchant.example/cancel",
    "customer": {
      "email": "buyer@example.com"
    },
    "metadata": {
      "cartId": "cart_12"
    }
  }'

Request fields

Field	Required	Description
orderId	Required	Order ID from your business system
amount	Required	Order amount; a string is recommended
currency	Required	USDC, USDT, or EURC
customer	Optional	{ email?, name? }
successUrl	Recommended	URL to return the buyer to your site after payment
cancelUrl	Recommended	URL to return the buyer to your site after canceling
metadata	Optional	Merchant-defined key-value pairs
paymentMethods	Optional	{ wallet?, transfer?, transferDefaultOpen? } — controls which payment methods the checkout shows, see Create a payment
expiresAt	Optional	ISO-8601 timestamp

Response structure

{
  "paymentIntent": {
    "paymentId": "b1985d0b-2026-4f8c-bf75-59ea53fe5466",
    "id": "b1985d0b-2026-4f8c-bf75-59ea53fe5466",
    "status": "requires_payment",
    "orderId": "order_1001",
    "amount": "12.50",
    "currency": "USDC",
    "checkoutUrl": "https://checkout.tariapay.com/pi_b1985d0b-2026-4f8c-bf75-59ea53fe5466",
    "successUrl": "https://merchant.example/success",
    "cancelUrl": "https://merchant.example/cancel",
    "customer": {
      "email": "buyer@example.com",
      "name": "Alice"
    },
    "metadata": {
      "cartId": "cart_12"
    },
    "txHash": null,
    "paidAt": null,
    "expiresAt": null,
    "createdAt": "2026-03-30T00:00:00.000Z",
    "updatedAt": "2026-03-30T00:00:00.000Z"
  }
}

Payment order IDs and checkout URLs

• paymentId is the bare UUID without a prefix. Use this value when calling the Merchant API (queries, refunds).
• checkoutUrl is the typed-prefix checkout address, of the form https://checkout.tariapay.com/pi_<uuid> (pl_ for payment links, su_ for subscription plans). Hand it to the buyer exactly as returned — never construct checkout URLs yourself. The path format may change between versions, and the checkoutUrl returned by the API is always the authoritative form.
• Older checkout links you previously saved or shared (such as /payment-intents/<uuid> or /paylink/<slug>) remain valid indefinitely — they will not break or redirect.

Issuing a refund

Refunds must be initiated from your server. The current API performs a full refund to the original payer: the chain, currency, amount, and destination wallet all come from the confirmed original payment — the caller cannot override the refund address.

const refund = await tariapay.paymentIntents.refund(
  "b1985d0b-2026-4f8c-bf75-59ea53fe5466",
  { reason: "Customer canceled the order" },
);

curl -X POST "https://api.tariapay.com/v1/payment-intents/b1985d0b-2026-4f8c-bf75-59ea53fe5466/refunds" \
  -H "Authorization: Bearer tpk_..." \
  -H "Content-Type: application/json" \
  -d '{"reason":"Customer canceled the order"}'

A refund first atomically reserves the funds from your available balance for the payment's chain and currency. If the balance is insufficient, the API returns 422; after the on-chain submission it returns processing or completed, and repeated requests never transfer funds twice.

Error structure

{
  "error": {
    "type": "invalid_request_error",
    "code": "order_id_conflict",
    "message": "orderId already exists for merchant",
    "requestId": "req_123"
  }
}

Common errors

Status code	Common causes
400	Missing or malformed request fields
401	API key missing, invalid, or revoked
409	orderId already exists
422	Merchant's available balance is insufficient for the refund
500	Server error — record the requestId and contact support

Next steps

• Integration steps: Quickstart
• Payment button or Checkout Panel: Checkout Button and Checkout Panel
• Payment results: Receiving payment results