Tranzak Docs
tranzak.co Dashboard
Docs  /  API reference

Retrieve a payment

Read a payment by Tranzak identifier or by your own reference, and force a real-time verification with the provider.

Three endpoints read the state of a payment. They all return the same payment object.

The payment object

{
  "success": true,
  "data": {
    "transaction_id": "17843268616389",
    "amount": "500.00",
    "currency": "HTG",
    "status": "completed",
    "payment_method": "moncash",
    "reference": "ORDER-4821",
    "description": "Order #4821",
    "customer": { "name": "Jean Dupont", "email": "[email protected]", "phone": "+50937654321" },
    "created_at": "2026-10-04T14:00:00.000000Z",
    "completed_at": "2026-10-04T14:03:10.000000Z",
    "failed_at": null,
    "failure_reason": null,
    "metadata": { "order_id": "4821" }
  }
}
Field Description
status pending, processing, completed or failed. Branch your logic on this field.
amount A string such as "500.00". Compare it as a decimal.
reference The reference you sent when you created the payment.
completed_at, failed_at, failure_reason Set when the payment becomes final.
metadata Your own data, as you sent it.

Retrieve by transaction identifier

GET/api/gateway/v1/payments/{transaction_id}
curl https://api.tranzak.co/api/gateway/v1/payments/17843268616389 \
  -H "X-Api-Key: $TRANZAK_API_KEY"

const res = await fetch('https://api.tranzak.co/api/gateway/v1/payments/17843268616389', {
  headers: { 'X-Api-Key': process.env.TRANZAK_API_KEY },
});
const { data } = await res.json();

import os, requests

data = requests.get(
    "https://api.tranzak.co/api/gateway/v1/payments/17843268616389",
    headers={"X-Api-Key": os.environ["TRANZAK_API_KEY"]},
).json()["data"]

$ch = curl_init('https://api.tranzak.co/api/gateway/v1/payments/17843268616389');
curl_setopt_array($ch, [CURLOPT_RETURNTRANSFER => true, CURLOPT_HTTPHEADER => ['X-Api-Key: ' . getenv('TRANZAK_API_KEY')]]);
$data = json_decode(curl_exec($ch), true)['data'];

Retrieve by your reference

GET/api/gateway/v1/payments/reference/{reference}

Use the order identifier you sent as reference. This is how you check a payment before creating a second one for the same order.

curl https://api.tranzak.co/api/gateway/v1/payments/reference/ORDER-4821 \
  -H "X-Api-Key: $TRANZAK_API_KEY"

const res = await fetch('https://api.tranzak.co/api/gateway/v1/payments/reference/ORDER-4821', {
  headers: { 'X-Api-Key': process.env.TRANZAK_API_KEY },
});

import os, requests

res = requests.get(
    "https://api.tranzak.co/api/gateway/v1/payments/reference/ORDER-4821",
    headers={"X-Api-Key": os.environ["TRANZAK_API_KEY"]},
)

If no payment matches, the API answers 404:

{ "success": false, "error": "transaction_not_found", "message": "Transaction not found for this reference" }

Note reference is not enforced as unique. Send a unique reference for each order.

Verify with the provider

POST/api/gateway/v1/payments/{transaction_id}/verify

Asks the payment provider for the latest status, then returns it. Use it to reconcile pending orders and for polling.

curl -X POST https://api.tranzak.co/api/gateway/v1/payments/17843268616389/verify \
  -H "X-Api-Key: $TRANZAK_API_KEY"

const res = await fetch('https://api.tranzak.co/api/gateway/v1/payments/17843268616389/verify', {
  method: 'POST',
  headers: { 'X-Api-Key': process.env.TRANZAK_API_KEY },
});
const { data } = await res.json();

import os, requests

data = requests.post(
    "https://api.tranzak.co/api/gateway/v1/payments/17843268616389/verify",
    headers={"X-Api-Key": os.environ["TRANZAK_API_KEY"]},
).json()["data"]

{
  "success": true,
  "data": {
    "transaction_id": "17843268616389",
    "status": "completed",
    "verified_at": "2026-10-04T14:10:00.000000Z",
    "provider_response": { }
  }
}

Important Use data.status only. provider_response uses the provider's own vocabulary (for example MonCash returns successful), which is not the same as Tranzak's statuses. Ignore it for your logic.

This endpoint makes a real-time call to the provider. Use it when you need an immediate answer, not on every page view, as it can be rate-limited.