API reference

Create a hosted Payment

POST/v1/payments

Creates a PENDING, automatically-verifiable hosted Payment and returns its `checkout_url`. Only a UX-level check runs at creation (an enabled, Bridge-ready receiving method and enough Service Credit for the next fee) — the real fee reservation happens when the customer reaches checkout.

Parameters

Request body CreatePaymentRequest

Responses

• 201Payment created — Payment
• 400Invalid request — Error — see error codes
• 401Missing, invalid, or revoked API key — Error — see error codes
• 403The key does not have the required scope — Error — see error codes
• 409State/idempotency/external_id conflict — Error — see error codes
• 429Too many requests — Error — see error codes

curl $PAYTAKA_API_URL/v1/payments \
  -X POST \
  -H "Authorization: Bearer $PAYTAKA_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-123-payment" \
  -d '{
    "amount": "500.00",
    "external_id": "order-123",
    "return_url": "https://example.com/payment-return"
  }'

List Payments

GET/v1/payments

Cursor-paginated. `payments:read` scope required.

Parameters

Responses

• 200A page of Payments — PaymentList
• 401Missing, invalid, or revoked API key — Error — see error codes
• 403The key does not have the required scope — Error — see error codes
• 429Too many requests — Error — see error codes

Retrieve a Payment

GET/v1/payments/{id}

Parameters

Responses

• 200The Payment — Payment
• 401Missing, invalid, or revoked API key — Error — see error codes
• 403The key does not have the required scope — Error — see error codes
• 404Not found (including a Payment belonging to a different business) — Error — see error codes
• 429Too many requests — Error — see error codes

Cancel a pending Payment

POST/v1/payments/{id}/cancel

Only valid while the Payment is PENDING. Cancels any active checkout attempt and releases its Service Credit fee reservation atomically. `payments:write` scope required.

Parameters

Responses

• 200The cancelled Payment — Payment
• 401Missing, invalid, or revoked API key — Error — see error codes
• 403The key does not have the required scope — Error — see error codes
• 404Not found (including a Payment belonging to a different business) — Error — see error codes
• 409State/idempotency/external_id conflict — Error — see error codes
• 429Too many requests — Error — see error codes

Simulate a successful payment (TEST SECRET KEYS ONLY)

POST/v1/test_helpers/payments/{id}/succeed

**TEST SECRET KEYS ONLY.** Moves a PENDING `livemode: false` Payment to PAID with no real money, SMS, Bridge, or Service Credit involved, and emits `payment.paid` to Test webhook endpoints. A `pt_live_sk_...` key receives 404, exactly as if this route did not exist. `payments:write` scope required.

Parameters

Responses

• 200The PAID Payment — Payment
• 401Missing, invalid, or revoked API key — Error — see error codes
• 403The key does not have the required scope — Error — see error codes
• 404Not found (including a Payment belonging to a different business) — Error — see error codes
• 409State/idempotency/external_id conflict — Error — see error codes
• 429Too many requests — Error — see error codes

Simulate a cancelled payment (TEST SECRET KEYS ONLY)

POST/v1/test_helpers/payments/{id}/cancel

**TEST SECRET KEYS ONLY.** Moves a PENDING `livemode: false` Payment to CANCELLED and emits `payment.cancelled` to Test webhook endpoints. A `pt_live_sk_...` key receives 404. `payments:write` scope required.

Parameters

Responses

• 200The CANCELLED Payment — Payment
• 401Missing, invalid, or revoked API key — Error — see error codes
• 403The key does not have the required scope — Error — see error codes
• 404Not found (including a Payment belonging to a different business) — Error — see error codes
• 409State/idempotency/external_id conflict — Error — see error codes
• 429Too many requests — Error — see error codes