Quickstart

This guide creates a hosted checkout and shows the minimum integration loop: create, redirect, receive a webhook, and verify status from your backend.

Before you begin

You need:

• a Tsara business account
• the correct test or live public key for checkout creation
• the matching secret key for server-side status reads
• a unique order ID from your system
• separate success and cancellation URLs

Keep secret keys on your server. Only the public key used by the documented checkout-create flow may be exposed to a client integration.

1. Create a checkout

Bash

curl --request POST \
  --url https://YOUR_BASE_URL/v1/checkout \
  --header 'Content-Type: application/json' \
  --data '{
    "public_key": "pk_test_xxxxx",
    "trx_id": "order_001",
    "email": "[email protected]",
    "name": "John Doe",
    "amount": 5000,
    "amount_type": "fiat",
    "currency": "NGN",
    "success_url": "https://example.com/payments/success",
    "cancel_url": "https://example.com/payments/cancelled"
  }'

2. Store the response

JSON

{
  "success": true,
  "status": "success",
  "status_code": 200,
  "message": "Checkout Created",
  "data": {
    "id": "order_001",
    "status": "pending",
    "checkout_url": "https://checkout.tsara.ng/?trx_id=order_001"
  }
}

Store data.id and the returned checkout URL against your order. If the response says the checkout was reused, continue with the returned original trx_id rather than the newly requested one.

3. Redirect the customer

Open data.checkout_url in the browser. The customer completes payment using the methods enabled for your business.

The browser redirect improves customer experience, but it is not proof of payment. Confirm payment from a signed webhook or a server-side status request.

4. Verify from your backend

Bash

curl --request GET \
  --url 'https://YOUR_BASE_URL/v1/checkout/status?trx_id=order_001' \
  --header 'Authorization: Bearer sk_test_xxxxx' \
  --header 'Accept: application/json'

Only fulfill the order after the transaction reaches its documented successful status.

5. Add webhook handling

Configure an HTTPS webhook endpoint in the dashboard, verify every signature against the raw request body, return 200 after durable processing, and make your handler idempotent so a repeated delivery does not repeat fulfillment.

Production checklist

• replace test credentials with live credentials on the server
• confirm Checkout is enabled for the live business
• configure distinct success and cancellation URLs
• verify webhook signatures before processing events
• store your order ID and Tsara reference together
• reconcile non-final transactions with the status endpoint
• test duplicate requests and network timeouts before launch