Create a payment order

A payment order connects a business order in your system to the Taria Pay payment flow. When your server creates a payment intent, it receives a paymentId and a checkoutUrl.

• With Hosted Checkout, the frontend redirects to checkoutUrl.
• With the Checkout Button, the button on your page opens checkoutUrl.
• With the Checkout Panel, the frontend passes paymentId to <CheckoutPanel />.

Who makes the request

The request must come from your server. Never call the Taria Pay API directly from the browser, and never put an API key in frontend code, mobile app bundles, or public repositories.

Recommended fields

Field	Required	Description
orderId	Required	Your own order ID; must be unique within your merchant account
amount	Required	The order amount; a string is recommended
currency	Required	USDC, USDT, or EURC
successUrl	Recommended	Where the buyer returns after paying
cancelUrl	Recommended	Where the buyer returns after canceling
customer	Optional	Buyer email, name, and other details
metadata	Optional	Your business context, e.g. a cart ID
paymentMethods	Optional	Controls which payment methods the checkout page shows, see below
expiresAt	Optional	Order expiration time, ISO-8601 format

SDK example

const paymentIntent = await tariapay.paymentIntents.create({
  orderId: "order_1001",
  amount: "12.50",
  currency: "USDC",
  successUrl: "https://merchant.example/success",
  cancelUrl: "https://merchant.example/cancel",
  customer: {
    email: "buyer@example.com",
    name: "Alice",
  },
  metadata: {
    cartId: "cart_12",
  },
});

return {
  paymentId: paymentIntent.paymentId,
  checkoutUrl: paymentIntent.checkoutUrl,
};

REST example

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",
      "name": "Alice"
    },
    "metadata": {
      "cartId": "cart_12"
    }
  }'

Controlling the checkout's payment methods

By default the checkout page offers both wallet payment and direct transfer (on supported networks), with the transfer section collapsed. You can adjust this per order with the optional paymentMethods field:

{
  "orderId": "order_1001",
  "amount": "12.50",
  "currency": "USDC",
  "paymentMethods": {
    "wallet": true,
    "transfer": true,
    "transferDefaultOpen": true
  }
}

Field	Default	Description
wallet	true	Show the connect-wallet payment module
transfer	true	Offer direct transfer; false also makes the server reject transfer requests for this order
transferDefaultOpen	false	Render the transfer section expanded; forced on when wallet is false

Rules and fail-safes:

• wallet and transfer cannot both be false — that returns a 400.
• Both switches are enforced server-side, not just hidden in the UI: the endpoint behind a disabled method returns 403.
• Direct transfer remains subject to network support. If you set wallet: false but the network the order is currently on does not support transfer, the checkout automatically falls back to showing the wallet module — and accepts wallet payments on it — so the buyer always has a way to pay. Switching to a transfer-capable network hides the wallet module again.
• Omitting the field keeps today's behavior exactly; existing integrations need no changes.

Important rules

• A single payment order supports both wallet payments and direct transfers (the checkout page shows an order-specific deposit address); you do not need to pass any payment-method fields. Both methods produce identical payment results and webhook events. To adjust the presentation, see paymentMethods above; for background see Supported payment methods.
• orderId must be unique within your merchant account.
• Creating the same orderId again usually returns a conflict error.
• checkoutUrl looks like https://checkout.tariapay.com/pi_<uuid>. Always use the value returned by the API as-is — do not construct checkout URLs yourself. The paymentId itself is a plain UUID with no prefix.
• Merchants do not need to submit an on-chain settlement address.
• You usually do not need to pass chainId when creating a payment order; the checkout page shows the payment networks currently available.
• Never treat successUrl as the final payment result.

Next steps

• Handling on the frontend: Redirect to checkout
• Payment button or Checkout Panel: Checkout Button and Checkout Panel
• Updating orders after payment: Receive payment results