API reference

Payments

A payment is one attempt to collect money from a customer. You create it, send the customer to its checkout_url, and then follow it until it succeeds, fails, is cancelled or expires.

• Create a payment
• Retrieve a payment
• List payments
• Cancel a payment

The payment object#

{
  "id": "pay_r3QA7YeEEBY3ABp3e2zS8iq9",
  "object": "payment",
  "status": "succeeded",
  "amount": "340.00",
  "amount_refunded": "0.00",
  "currency": "AED",
  "fee": "7.65",
  "net": "332.35",
  "reference": "order-1001",
  "description": "Blue mug",
  "customer_email": "buyer@example.com",
  "metadata": { "cart_id": "42" },
  "checkout_url": null,
  "card": { "brand": "VISA", "last4": "4242", "country": "AE" },
  "failure_message": null,
  "livemode": false,
  "created_at": "2026-10-20T10:00:00.000Z",
  "paid_at": "2026-10-20T10:02:31.000Z"
}

Statuses#

A payment normally ends in one of succeeded, failed, cancelled or expired.

Create a payment#

Creates a payment and returns it with a checkout_url. Send the customer there to pay.

Request body#

success_url and cancel_url are both required. A request that leaves either one out is rejected with a 400 validation error. Unknown fields are rejected with a 400 error too, so a typo in a field name is caught straight away.

Example#

curl https://api.tigerpay.app/v1/payments \
  -H "Authorization: Bearer sk_test_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-1001" \
  -d '{
    "amount": "340.00",
    "currency": "AED",
    "reference": "order-1001",
    "description": "Blue mug",
    "customer_email": "buyer@example.com",
    "success_url": "https://shop.example.com/thanks",
    "cancel_url": "https://shop.example.com/cart",
    "metadata": { "cart_id": "42" }
  }'

const response = await fetch("https://api.tigerpay.app/v1/payments", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.TIGERPAY_SECRET_KEY}`,
    "Content-Type": "application/json",
    "Idempotency-Key": "order-1001",
  },
  body: JSON.stringify({
    amount: "340.00",
    currency: "AED",
    reference: "order-1001",
    success_url: "https://shop.example.com/thanks",
    cancel_url: "https://shop.example.com/cart",
  }),
});
const payment = await response.json();

<?php
$ch = curl_init('https://api.tigerpay.app/v1/payments');
curl_setopt_array($ch, [
    CURLOPT_POST           => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER     => [
        'Authorization: Bearer ' . getenv('TIGERPAY_SECRET_KEY'),
        'Content-Type: application/json',
        'Idempotency-Key: order-1001',
    ],
    CURLOPT_POSTFIELDS     => json_encode([
        'amount'      => '340.00',
        'currency'    => 'AED',
        'reference'   => 'order-1001',
        'success_url' => 'https://shop.example.com/thanks',
        'cancel_url'  => 'https://shop.example.com/cart',
    ]),
]);
$payment = json_decode(curl_exec($ch), true);
curl_close($ch);

Response: 200 with the payment object, status pending.

Possible errors#

Retrieve a payment#

Returns the payment object for a pay_ id.

curl https://api.tigerpay.app/v1/payments/pay_r3QA7YeEEBY3ABp3e2zS8iq9 \
  -H "Authorization: Bearer sk_test_YOUR_KEY"

• If the payment is still pending and is more than 2 minutes old, TigerPay checks its latest state before it answers. So this call can show a result even if a webhook has not reached you yet.
• If the id does not exist, or belongs to another account or the other mode, you get 404 with code resource_missing.

Webhooks are the best way to learn about a result. Use this call to double-check, or to catch up after your server was down.

List payments#

Returns your payments, newest first. A test key lists test payments and a live key lists live payments.

curl "https://api.tigerpay.app/v1/payments?limit=2&status=succeeded" \
  -H "Authorization: Bearer sk_test_YOUR_KEY"

{
  "object": "list",
  "data": [
    { "id": "pay_r3QA7YeEEBY3ABp3e2zS8iq9", "object": "payment", "status": "succeeded", "…": "…" },
    { "id": "pay_kY9pF34Qy6nB3Wwd25rq4f5z", "object": "payment", "status": "succeeded", "…": "…" }
  ],
  "has_more": true
}

If has_more is true, ask for the next page with starting_after set to the id of the last payment you received:

curl "https://api.tigerpay.app/v1/payments?limit=2&status=succeeded&starting_after=pay_kY9pF34Qy6nB3Wwd25rq4f5z" \
  -H "Authorization: Bearer sk_test_YOUR_KEY"

An unknown query parameter, or a starting_after that is not one of your payments, gives 400 parameter_invalid.

Cancel a payment#

Cancels a payment that is still pending, so the customer can no longer pay it. No body is needed. TigerPay sends a payment.cancelled webhook.

curl -X POST https://api.tigerpay.app/v1/payments/pay_kY9pF34Qy6nB3Wwd25rq4f5z/cancel \
  -H "Authorization: Bearer sk_test_YOUR_KEY"

It returns the payment with status cancelled and checkout_url set to null.

• Only pending payments can be cancelled. Any other status gives 400 payment_not_cancellable. If the customer pays at the same moment, the request can fail with this error. Fetch the payment to see its real status.
• To give money back for a payment that succeeded, use a refund.

Money maths#

• Amounts are strings so that no rounding error can creep in. Do not turn them into floating-point numbers. Work in fils ("340.00" is 34000 fils) or use a decimal library.
• The fee is worked out in whole fils and rounded half up. Example: AED 10.10 on a UAE card at 2.25% is 22.725 fils, so the fee is 23 fils, "0.23".

TigerPay API documentation, version 1. Base URL: https://api.tigerpay.app/v1