Getting Started

Paytami processes payments for merchants in Guatemala and Central America. Your integration talks only to the Paytami API: one stable contract for all your charges.

How to integrate

There are three ways to collect payments, from simplest to most flexible:

Method	When to use it	Guide
Payment links	You want to collect payments without writing code: generate a link from the dashboard and share it.	Payment links
Hosted checkout	Your backend already creates the payment; you redirect the customer to a Paytami-hosted payment page.	Hosted checkout
Embedded checkout	You want the payment form inside your own site, without taking the customer away.	Embedded checkout

All three options share the same public API and the same data model: a payment (pay_...) is the central resource, and everything else (checkout, links, webhooks) revolves around it.

Base URL

https://app.paytami.com/api/v1

Every endpoint in this documentation is relative to that base.

Environments: test and live

Every merchant has two fully separate environments, each with its own keys and its own data — they never mix:

• Test (sk_test_...): for development and integration, no real money moves.
• Live (sk_live_...): real charges.

Which environment a request runs against is decided by the key you use, not a parameter or separate setting — send /v1 your test key and everything you do (creating payments, looking them up) stays in the test environment automatically.

Authentication

Every authenticated request carries your secret key in the Authorization header:

Authorization: Bearer sk_test_...

See Authentication for how to get your key and best practices for handling it.

Your first charge

curl https://app.paytami.com/api/v1/payments \
  -X POST \
  -H "Authorization: Bearer sk_test_..." \
  -H "Idempotency-Key: 6e4b6f0a-a5f0-4b9a-9b8b-1a2b3c4d5e6f" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": "15000",
    "currency": "GTQ",
    "method_type": "card",
    "success_url": "https://your-site.com/thanks",
    "cancel_url": "https://your-site.com/cart"
  }'

The response already includes a checkout_url on Paytami's own domain — that's where you send the customer to pay:

{
  "id": "pay_8f2c1a9d4e6b7c0a1d2e3f40",
  "status": "created",
  "currency": "GTQ",
  "amount": "15000",
  "checkout_url": "https://app.paytami.com/api/v1/checkout/pay_8f2c1a9d4e6b7c0a1d2e3f40",
  "created_at": "2026-08-28T15:04:00.000Z"
}

Continue with Hosted checkout for the full flow, or the POST /v1/payments reference for every available field.

Amounts are integers

amount always travels as a string, in the currency's minor unit (cents): "15000" is Q150.00 or $150.00, never 150.00 or a JS number. This avoids floating-point rounding errors with real money.