Skip to content
Paytalya Paytalya Gateway

Quickstart

This guide walks you from creating your first payment to confirming the result. First make sure you have an API key and a terminalId provisioned for you.

1. Create a payment request

Section titled “1. Create a payment request”

Call POST /v1/payments from your server. This request only sends the amount, the terminal, and the returnUrl; its body contains no card. Send the amount as an integer in minor units (kuruş) (1,250.50 TRY → 125050).

Terminal window
curl -X POST https://gateway.paytalya.com/v1/payments \
  -H "Authorization: Bearer ptk_live_xxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 125050,
    "partnerTxCode": "ORD-2026-8841",
    "terminalId": "trm_3Kd9x",
    "installment": 1,
    "description": "Order #8841",
    "returnUrl": "https://yourstore.example/payment/result"
  }'

Response (201 Created) contains no card or bank 3D form data; it returns a paymentRef and a handoffUrl:

{
  "paymentCode": "pay_7Hq2bL",
  "status": "initiated",
  "paymentRef": "pr_3Kd9xQ1w2E",
  "handoffUrl": "https://pay.paytalya.example/checkout"
}

2. Redirect the buyer to the handoff page

Section titled “2. Redirect the buyer to the handoff page”

You form-POST the card you collected on your own checkout, plus the paymentRef, from the buyer’s browser to the handoffUrl (with a WebView on mobile). The handoff page runs the bank’s 3D relay itself; you do not build the bank’s 3D form. Web and mobile examples: Card Handoff.

After 3D completes, the handoff page redirects the buyer to your returnUrl via 303. However, the result carried over returnUrl is not authoritative; you learn the definitive result in the step below.

3. Learn the result

Section titled “3. Learn the result”

There are two paths; both lead to the same result, but the webhook is real-time:

Webhook (recommended): When the status changes, Paytalya sends a notification to your endpoint. See Webhooks.

{
  "id": "whd_a1b2c3",
  "type": "payment.captured",
  "paymentCode": "pay_7Hq2bL",
  "occurredAt": "2026-06-14T12:05:11Z"
}

Query (confirmation): When a webhook arrives or on the returnUrl return, query the definitive status:

Terminal window
curl https://gateway.paytalya.com/v1/payments/pay_7Hq2bL \
  -H "Authorization: Bearer ptk_live_xxxxxxxxxxxxxxxxxxxx"

Next steps

Section titled “Next steps”