Tranzak Docs
tranzak.co Dashboard
Docs  /  API reference

Create a payment

Create a payment with POST /api/gateway/v1/payments. Parameters, response, method-specific fields and errors.

POST/api/gateway/v1/payments

Creates a payment, whatever the payment method. Authenticate with the X-Api-Key header.

Request body

Field Type Required Description
amount number Yes In the currency's real unit (500 is 500 HTG). At least 1. Method minimums apply.
currency string Yes HTG or USD.
payment_method string Yes moncash, natcash, lakaypay_card or card. See Payment methods.
customer_name string Yes The customer's name, stored as sent.
customer_email string No The customer's email address.
customer_phone string No The customer's phone number, for example +50937654321.
reference string No Your order identifier. Strongly recommended: it is how you find the payment later.
description string No A short description.
metadata object No Your own data, returned as is in reads and webhooks.
recurring boolean No lakaypay_card only. See Hosted card page.
recurring_interval string No daily, weekly, monthly or yearly.
recurring_interval_count integer No Number of intervals between two charges.

Example

curl https://api.tranzak.co/api/gateway/v1/payments \
  -H "X-Api-Key: $TRANZAK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 500,
    "currency": "HTG",
    "payment_method": "moncash",
    "customer_name": "Jean Dupont",
    "customer_email": "[email protected]",
    "customer_phone": "+50937654321",
    "reference": "ORDER-4821",
    "description": "Order #4821",
    "metadata": { "order_id": "4821" }
  }'

const res = await fetch('https://api.tranzak.co/api/gateway/v1/payments', {
  method: 'POST',
  headers: { 'X-Api-Key': process.env.TRANZAK_API_KEY, 'Content-Type': 'application/json' },
  body: JSON.stringify({
    amount: 500,
    currency: 'HTG',
    payment_method: 'moncash',
    customer_name: 'Jean Dupont',
    customer_email: '[email protected]',
    customer_phone: '+50937654321',
    reference: 'ORDER-4821',
    description: 'Order #4821',
    metadata: { order_id: '4821' },
  }),
});
const payment = await res.json();

import os, requests

payment = requests.post(
    "https://api.tranzak.co/api/gateway/v1/payments",
    headers={"X-Api-Key": os.environ["TRANZAK_API_KEY"]},
    json={
        "amount": 500,
        "currency": "HTG",
        "payment_method": "moncash",
        "customer_name": "Jean Dupont",
        "customer_email": "[email protected]",
        "customer_phone": "+50937654321",
        "reference": "ORDER-4821",
        "description": "Order #4821",
        "metadata": {"order_id": "4821"},
    },
).json()

$ch = curl_init('https://api.tranzak.co/api/gateway/v1/payments');
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => ['X-Api-Key: ' . getenv('TRANZAK_API_KEY'), 'Content-Type: application/json'],
    CURLOPT_POSTFIELDS => json_encode([
        'amount' => 500,
        'currency' => 'HTG',
        'payment_method' => 'moncash',
        'customer_name' => 'Jean Dupont',
        'customer_email' => '[email protected]',
        'customer_phone' => '+50937654321',
        'reference' => 'ORDER-4821',
        'description' => 'Order #4821',
        'metadata' => ['order_id' => '4821'],
    ]),
]);
$payment = json_decode(curl_exec($ch), true);

Response

201 Created. The fields are at the root of the JSON, not wrapped in data.

{
  "success": true,
  "transaction_id": "17843268616389",
  "amount": "500.00",
  "currency": "HTG",
  "status": "processing",
  "created_at": "2026-10-04T14:00:00.000000Z",
  "payment_url": "https://…"
}
Field Description
transaction_id The Tranzak identifier, a numeric string. Store it against your order before redirecting.
amount, currency What the customer is charged. Read them from the response: a USD request for MonCash or NatCash is charged in HTG.
status processing at creation, except for card.
payment_url Redirect the customer's browser here. Absent for card.
conversion Present when an amount was converted to HTG. See Currencies and exchange rate.

Method-specific fields are added at the root:

  • NatCash also returns natcash_reference.
  • Card (card) returns client_secret, publishable_key and payment_intent_id instead of payment_url, with status: "requires_payment_method". See Embedded card widget.

Errors

HTTP error Meaning
422 validation_error A field is missing or invalid. See errors in the response.
400 payment_method_not_available The method is not enabled for this account.
400 amount_too_low / amount_too_high Outside the method's limits. The message states the limit.
403 payment_method_not_approved Live mode only, for card. Request access in the dashboard.
400 payment_processing_failed The provider refused the payment. Show message to the customer.
500 internal_error Retry later. Check the idempotency note before creating again.

Authentication errors and rate limits are listed in Errors and rate limits.