Skip to content
Paytalya Paytalya Gateway

Overview

Paytalya Gateway is a payment orchestration system that manages your card payments. The integration is two-step: you create a payment request from your server, then redirect the buyer’s browser/WebView, with the card, to Paytalya’s separate handoff page (the pay.* origin). The bank’s 3D Secure relay, the callback, and capture run on that page and on Paytalya’s side.

Paytalya does not collect the card for you: you collect it on your own checkout. You then redirect the buyer to Paytalya’s separate handoff page, which takes the card you collected plus a one-time payment reference (paymentRef) and runs the bank’s 3D relay.

Core concepts

Section titled “Core concepts”
  • Merchant: The party accepting payment, that is, you.
  • Terminal: The bank POS definition a payment is routed to. Every payment is bound to a terminal (terminalId is required). Terminals are provisioned for you during onboarding. Today Paytalya provisions terminals for you and you use the terminalId you were given; self-service terminal/virtual-POS creation from your own panel is planned for a future release.
  • Payment: The end-to-end lifecycle of a card transaction. Each payment has a paymentCode identifier and a status (initiated → captured → ...). See Payment Lifecycle.
  • paymentRef: A one-time payment reference returned by POST /v1/payments. Used to carry the card to the handoff page; distinct from paymentCode.
  • handoffUrl: The Paytalya handoff page address (pay.*) you redirect the buyer’s browser/WebView to.

Capabilities

Section titled “Capabilities”

The Paytalya API offers four core capabilities:

  1. Create a payment: POST /v1/payments (amount + terminalId + returnUrl) starts a payment and returns paymentRef + handoffUrl. See Create Payment.
  2. Query a payment: GET /v1/payments/{paymentCode} or by partnerTxCode returns the current status, amount, commission, and refund breakdown. See Get Payment.
  3. Refund / void: POST /v1/payments/{paymentCode}/refunds starts a full or partial refund. See Refunds & Void.
  4. Webhook: Paytalya notifies your endpoint as the payment status changes. See Webhooks.

End-to-end flow

Section titled “End-to-end flow”
1. POST /v1/payments                  →  you get { paymentRef, handoffUrl, status: initiated }
2. Redirect the buyer to handoff page →  form-POST card + paymentRef to handoffUrl (pay.*)
3. Handoff page runs 3D               →  bank 3D, callback and capture are handled on Paytalya's side
4. Return                             →  the buyer returns to returnUrl via 303 (carried result not authoritative)
5. Confirm the result                 →  learn the definitive status via webhook + GET /v1/payments

The redirect to the handoff page and the 3D redirect are performed by the buyer’s browser/WebView; on your server you only start the payment and confirm the result. The only difference between web and mobile is the browser context (native browser vs WebView); the flow is the same, and on mobile there are no deep links. Step-by-step detail: Payment Flow and Card Handoff.

Next steps

Section titled “Next steps”