API docs by Redocly

Zatlas Payment Orchestration API (6.1)

Download OpenAPI specification:

Enables call-center partners to process credit card payments on behalf of hotel guests during phone interactions. Partners submit card data securely, and Zatlas handles payment processing, 3DS authentication, MSI (Meses Sin Intereses) installments, and refunds.

Base URLs

Operation Base URL
Tokenize card (POST /methods) https://cde-api.zatlas.com
All other operations https://api.zatlas.com

Payment Flows

Flow A — Simple Payment (2 calls): POST /methods → POST /payments → poll GET /payments/{id}

Flow B — MSI Payment (3 calls): POST /methods → POST /payments (with installments.required: true) → POST /payments/{id}/confirmation → poll GET /payments/{id}

Flow C — MSI with Amount Update (4 calls): POST /methods → POST /payments → PATCH /payments/{id} → POST /payments/{id}/confirmation → poll GET /payments/{id}

Flow D — Recurring / Scheduled Payment (reuse stored method): POST /payments (same methodId from a previous tokenization) → poll GET /payments/{id}

Methods are reusable — a single tokenized method can be charged multiple times. This enables scheduled or recurring payments without re-collecting card details.

3DS Authentication

When a card issuer requires Strong Customer Authentication, the payment enters requires_action status. Send the nextAction.url to the cardholder via SMS, WhatsApp, or email. The cardholder must complete authentication on their device — do not open the URL yourself.

MSI (Meses Sin Intereses)

MSI allows Mexican cardholders to pay in fixed monthly installments at 0% interest. Requires MXN currency and a Mexican credit card. Typical plans: 3, 6, 9, 12, or 18 months.

Idempotency

All POST requests require an Idempotency-Key header (UUID v4). Keys are valid for 24 hours. Same key + same payload returns the cached response. Same key + different payload returns 409 Conflict.

Polling

Use exponential backoff: 1s → 2s → 4s → 8s → 16s → 30s (max). Stop when status is terminal: succeeded, failed, or expired.

Methods

Card tokenization — creates a payment method from raw card data

Tokenize card

Tokenize card details to create a reusable payment method. This endpoint only creates the method — no payment is initiated.

Methods can be used for multiple payments (e.g., recurring charges on the same card). If a TTL is configured, the method expires after that period; otherwise it does not expire.

Authorizations:
oauth2
header Parameters
Idempotency-Key
required
string <uuid>
Example: 550e8400-e29b-41d4-a716-446655440000

UUID v4 to prevent duplicate operations. Keys are valid for 24 hours.

X-Request-Id
string
Example: req-abc-123

Correlation ID for request tracing

Request Body schema: application/json
required
type
required
string
Value: "card"

Payment method type

guestEmail
string <email>

Guest email — used for payment provider customer records and receipts

required
object (CardInput)

Responses

Request samples

Content type
application/json
{
  • "type": "card",
  • "guestEmail": "guest@example.com",
  • "card": {
    }
}

Response samples

Content type
application/json
{
  • "id": "mth_550e8400e29b41d4a716446655440000",
  • "type": "card",
  • "card": {
    },
  • "createdAt": "2025-01-15T10:30:00Z",
  • "expiresAt": "2025-01-15T10:45:00Z"
}

Payments

Payment lifecycle — create, update, confirm, poll, and refund payments

Create payment

Create a payment using a previously tokenized method.

Without installments: The payment is processed immediately. Response status will be processing or requires_action (3DS).

With installments.required: true: The payment is created in pending_confirmation status with available installment plans. You must call POST /payments/{id}/confirmation to process the payment.

MSI payments expire after 15 minutes if not confirmed.

Authorizations:
oauth2
header Parameters
Idempotency-Key
required
string <uuid>
Example: 550e8400-e29b-41d4-a716-446655440000

UUID v4 to prevent duplicate operations. Keys are valid for 24 hours.

X-Request-Id
string
Example: req-abc-123

Correlation ID for request tracing

Request Body schema: application/json
required
methodId
required
string

Method token from tokenization (mth_xxx)

amount
required
number <double> >= 0.01

Amount to process

currency
required
string (Currency)
Enum: "usd" "mxn"

ISO 4217 currency code (lowercase)

reservationId
required
string

Your reservation reference

object (InstallmentsRequest)
returnUrl
string <uri> ^https://.*

HTTPS callback URL where the cardholder is redirected after completing 3DS authentication. Required when you expect 3DS challenges and want the cardholder redirected to a specific page.

object

Arbitrary key-value pairs attached to the payment. Useful for storing partner-specific references (e.g., internal order ID, agent ID). Returned in all payment responses.

Responses

Request samples

Content type
application/json
Example
{
  • "methodId": "mth_550e8400e29b41d4a716446655440000",
  • "amount": 125,
  • "currency": "usd",
  • "reservationId": "RES-12345-ABC"
}

Response samples

Content type
application/json
Example
{
  • "id": "pay_6ba7b8109dad11d180b400c04fd430c8",
  • "status": "processing",
  • "amount": 125,
  • "currency": "usd",
  • "methodId": "mth_550e8400e29b41d4a716446655440000",
  • "reservationId": "RES-12345-ABC",
  • "createdAt": "2025-01-15T10:32:00Z",
  • "updatedAt": "2025-01-15T10:32:00Z"
}

Update pending payment amount

Update a pending payment's amount before confirmation. Use this when you need to adjust the amount (e.g., adding commission, applying discounts) after showing the guest the available installment plans.

Only works for payments in pending_confirmation status. The availableInstallments list is automatically refreshed based on the new amount. Amount increases may unlock additional installment plans; decreases may remove some.

Authorizations:
oauth2
path Parameters
id
required
string^pay_[a-f0-9]{32}$
Example: pay_6ba7b8109dad11d180b400c04fd430c8

Payment identifier (prefixed with pay_)

header Parameters
X-Request-Id
string
Example: req-abc-123

Correlation ID for request tracing

Request Body schema: application/json
required
amount
required
number <double> >= 0.01

New amount to charge

Responses

Request samples

Content type
application/json
{
  • "amount": 15000
}

Response samples

Content type
application/json
{
  • "id": "pay_6ba7b8109dad11d180b400c04fd430c8",
  • "status": "pending_confirmation",
  • "amount": 15000,
  • "originalAmount": 12000,
  • "currency": "mxn",
  • "methodId": "mth_550e8400e29b41d4a716446655440000",
  • "reservationId": "RES-12345-ABC",
  • "availableInstallments": [
    ],
  • "createdAt": "2025-01-15T10:32:00Z",
  • "updatedAt": "2025-01-15T10:35:00Z",
  • "expiresAt": "2025-01-15T10:47:00Z"
}

Get payment status

Retrieve the current status of a payment, including installment details, 3DS next actions, failure information, and refunds.

Authorizations:
oauth2
path Parameters
id
required
string^pay_[a-f0-9]{32}$
Example: pay_6ba7b8109dad11d180b400c04fd430c8

Payment identifier (prefixed with pay_)

header Parameters
X-Request-Id
string
Example: req-abc-123

Correlation ID for request tracing

Responses

Response samples

Content type
application/json
Example
{
  • "id": "pay_6ba7b8109dad11d180b400c04fd430c8",
  • "status": "processing",
  • "amount": 125,
  • "currency": "usd",
  • "methodId": "mth_550e8400e29b41d4a716446655440000",
  • "reservationId": "RES-12345-ABC",
  • "createdAt": "2025-01-15T10:30:00Z",
  • "updatedAt": "2025-01-15T10:30:05Z"
}

Confirm pending payment

Confirm a pending payment with optional installment selection. Only required when installments.required: true was used during payment creation.

Send an empty body {} for single payment, or specify installments.count to select an installment plan. The count must be one of the values returned in availableInstallments from the create/update response.

Authorizations:
oauth2
path Parameters
id
required
string^pay_[a-f0-9]{32}$
Example: pay_6ba7b8109dad11d180b400c04fd430c8

Payment identifier (prefixed with pay_)

header Parameters
X-Request-Id
string
Example: req-abc-123

Correlation ID for request tracing

Request Body schema: application/json
required
object

Responses

Request samples

Content type
application/json
Example
{
  • "installments": {
    }
}

Response samples

Content type
application/json
{
  • "id": "pay_6ba7b8109dad11d180b400c04fd430c8",
  • "status": "processing",
  • "amount": 12000,
  • "currency": "mxn",
  • "methodId": "mth_550e8400e29b41d4a716446655440000",
  • "reservationId": "RES-12345-ABC",
  • "installments": {
    },
  • "createdAt": "2025-01-15T10:32:00Z",
  • "updatedAt": "2025-01-15T10:33:00Z"
}

Create refund

Create a refund for a succeeded payment. Supports full and partial refunds. Omit amount for a full refund. Multiple partial refunds are allowed until the payment amount is exhausted.

Refunds may return pending status initially (async processing). Poll GET /payments/{id} for the updated refund status in the refunds array.

Authorizations:
oauth2
path Parameters
id
required
string^pay_[a-f0-9]{32}$
Example: pay_6ba7b8109dad11d180b400c04fd430c8

Payment identifier (prefixed with pay_)

header Parameters
Idempotency-Key
required
string <uuid>
Example: 550e8400-e29b-41d4-a716-446655440000

UUID v4 to prevent duplicate operations. Keys are valid for 24 hours.

X-Request-Id
string
Example: req-abc-123

Correlation ID for request tracing

Request Body schema: application/json
required
amount
number <double> >= 0.01

Amount to refund. If omitted, full refund.

reason
required
string (RefundReason)
Enum: "duplicate" "fraudulent" "requested_by_customer" "cancellation"
  • duplicate — Duplicate payment
  • fraudulent — Fraudulent transaction
  • requested_by_customer — Guest requested refund
  • cancellation — Reservation cancellation

Responses

Request samples

Content type
application/json
Example
{
  • "reason": "cancellation"
}

Response samples

Content type
application/json
{
  • "id": "ref_7c9e6679d1cd4f5a8b3e7f8d9c0a1b2e",
  • "paymentId": "pay_6ba7b8109dad11d180b400c04fd430c8",
  • "status": "succeeded",
  • "amount": 5000,
  • "currency": "mxn",
  • "reason": "requested_by_customer",
  • "createdAt": "2025-01-15T10:45:00Z"
}