Hosted Checkout
Create a checkout session, redirect the customer, and verify payment from your server.
- 1. Your backend to Tapaya: Create session.
- 2. Tapaya to Your backend: Session ID and URL.
- 3. Your backend to Your frontend: Redirect to Checkout.
- 4. Your frontend to Tapaya: Open Checkout and pay.
- 5. Tapaya to Your frontend: Return to your shop.
- 6. Your backend to Tapaya: Retrieve session.
- 7. Tapaya to Your backend: Payment status.
- 8. Your backend to Your frontend: Show verified result.
Before you start
Pick the key that matches who runs your backend. Keep either key on your server; Checkout Security lists the server-side rules.
One shop
Use a merchant checkout key. It selects its merchant, and the examples here use it.
Many merchants
Use the organization Secret key and send a merchant token with every request.
Then, in Checkout in the Tapaya Platform:
- Add your merchant and check that it shows Ready. See Checkout settings.
- Register your shop as an allowed website, with default success and cancel URLs, for the key you chose. The
examples use
https://shop.example.
Return URLs follow the key
Merchant-key sessions use the merchant's return URLs. Sessions created with the organization Secret key use the organization's return destinations instead. The two are never combined.
Accept a payment
All three options create the same Checkout sessions with the same credentials. Pick one; every step below follows your choice.
Set up your server
Set TAPAYA_CHECKOUT_API_URL to https://api.sandbox.tapaya.com and store your key in TAPAYA_CHECKOUT_API_KEY.
Call the API from your server runtime's fetch, never from the customer's browser. The examples read these values
through process.env; adapt that lookup if your runtime uses a different secrets interface.
Create a helper that checks HTTP errors before returning the response body:
const apiUrl = process.env.TAPAYA_CHECKOUT_API_URL;
const apiKey = process.env.TAPAYA_CHECKOUT_API_KEY;
async function checkoutRequest(path, options = {}) {
const response = await fetch(new URL(path, apiUrl), {
...options,
headers: {
...options.headers,
Authorization: `Bearer ${apiKey}`,
},
redirect: 'error',
cache: 'no-store',
signal: AbortSignal.timeout(8000),
});
if (!response.ok) {
throw new Error(`Checkout request failed (${response.status})`);
}
return response.json();
}Create a session
Calculate the order total on your server, including tax and shipping. Persist the order and a unique
checkoutAttemptKey before making the request, and load order from that stored snapshot. merchantOrderId
is required. Supply the customer's email or phone from your stored order in customer.
const session = await checkoutRequest('/merchant/checkout-sessions', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'Idempotency-Key': order.checkoutAttemptKey,
},
body: JSON.stringify({
merchantOrderId: order.id,
amount: order.totalInMinorUnits,
currency: order.currency,
customer: { email: order.customer.email, phone: order.customer.phone },
successUrl: 'https://shop.example/checkout/return',
cancelUrl: 'https://shop.example/checkout/cancel',
}),
});The response contains the session's id and hosted url. For item summaries, tax breakdowns, customer details,
and every response field, see Create a Checkout Session.
If the request fails or times out, retry with the same key and an unchanged body. Never generate a new key for an uncertain result: a changed body with the same key returns HTTP 409.
Automatic retries
The Node.js SDK retries up to twice after a connection error, a timeout, or HTTP 429, 502, 503, or 504, with the same key and body. Across separate calls or restarts, pass your persisted key: omitting it generates a new one per call. See Idempotency and retries.
Redirect the customer
Persist session.id with your order as its checkoutSessionId, then send the browser to session.url with HTTP
303. Use the URL unchanged rather than constructing it.
// First persist session.id as the order's checkoutSessionId.
return Response.redirect(session.url, 303);If your framework uses a different response API, send HTTP 303 with session.url in the Location header. With
cURL, open the returned url in your browser to test the payment by hand.
Verify the payment
In your return handler, resolve the order from your application's authenticated checkout context and retrieve its stored session from your server. Do this on the cancel URL too: a visit to either URL proves nothing.
const current = await checkoutRequest(
`/merchant/checkout-sessions/${encodeURIComponent(order.checkoutSessionId)}`,
);
if (
current.id !== order.checkoutSessionId ||
current.merchantOrderId !== order.id ||
current.amount !== order.totalInMinorUnits ||
current.currency !== order.currency
) {
throw new Error('Checkout session does not match the order');
}
const paid = current.paymentStatus === 'successful';Fulfill once, and only when paid
Record the payment and fulfill the order only when the session matches your stored order and paymentStatus is
successful, and record it atomically so it happens once. If retrieval fails or the payment is unresolved, keep
the session ID and check again. See Payment status.
Fulfill the order
Receive checkout session webhooks even when the customer never returns. Keep retrieving unresolved sessions as a recovery path.
Once the session matches your order and is paid, ship the goods or grant access. That is the whole flow:
- Your server creates a session
- The customer pays on Tapaya's page
- They return to your site
- You verify, then fulfill once
Handle payment outcomes
Checkout Security covers what to verify and how to retry an unknown result without creating a second session.
| Outcome | What the session shows | What to do |
|---|---|---|
| Declined | open, with paymentStatus: failed | Nothing. The customer can try another card or wallet on the same page. |
| Not yet known | open and unpaid while Tapaya confirms the result | Retrieve the session again later. |
| New session for the same order | The previous unpaid session reports expired | Use the new session. A paid order, or one with a payment in progress, returns HTTP 409. See One payment per order. |
| Expired | Stops accepting new payments 30 minutes after creation | Create a new session if the order is still unpaid. A payment submitted before expiry still completes. |
Check the integration
Test cards
Run every payment outcome against sandbox.
QA Checklist
Cover retries, interrupted checkouts, and expiry before you go live.
Collect details or save a payment method
Add these fields to the session when you need them:
- Customer details:
customersupplies email and phone;customerCollectionconfigures additional name and billing fields. See Customer details and shipping. - Delivery options:
shippingOptions. If delivery changes the total, verify the final amount on your server. - Save the card or wallet:
customerReference,savePaymentMethod, andpaymentMethodUsage. See Save cards and charge later. - Tax and shipping rows: send
0for no VAT or free shipping; omit the field to hide the row.