API reference

Quickstart

This guide takes you from a sandbox API key to your first card payment in about five minutes. Every request below is sent to your installation's /v1 base path. The examples use https://pay.example.com/v1; replace the host with the one you were given.

1. Get a sandbox key

Sign in to the merchant panel, open Developers → API keys and create a secret key. In a sandbox installation the key starts with sk_sandbox_; in a live installation it starts with sk_live_. There are no sk_test_ keys: sandbox and live are separate installations, and a key only works in the installation that issued it.

The secret is shown once. Store it in your server's secret store, never in a browser or mobile app.

Send it as a bearer token on every request:

curl https://pay.example.com/v1/balance \
  -H "Authorization: Bearer sk_sandbox_YOUR_KEY"

A 200 answer with your balance means the key works. Every response carries a Request-Id: req_… header; quote it when you contact support, and find the request later under Developers → Logs.

2. Create and confirm a payment

Money is always an integer in minor units: 12500 with currency try is 125.00 TRY. Create the payment and confirm it in one call by sending the card and confirm: true.

Billing details are required to confirm a payment (see the customers guide), and return_url must be registered in Settings → Websites & callbacks when 3-D Secure may be needed (see the 3-D Secure guide).

{
  "amount": 12500,
  "currency": "try",
  "capture_method": "automatic",
  "confirm": true,
  "payment_method_data": {
    "type": "card",
    "card": {
      "number": "4109090000000011",
      "exp_month": 12,
      "exp_year": 2030,
      "cvc": "123",
      "holder_name": "Test Customer"
    },
    "billing_details": {
      "name": "Test Customer",
      "email": "test@example.com",
      "address": {
        "line1": "Bagdat Caddesi 1",
        "city": "Kadikoy",
        "state": "Istanbul",
        "postal_code": "34710",
        "country": "TR"
      }
    }
  },
  "return_url": "https://shop.example.com/pay/return",
  "description": "Order 1001",
  "metadata": {"order_id": "1001"}
}

Send it with a unique Idempotency-Key so that a retry after a network error can never charge twice:

curl -X POST https://pay.example.com/v1/payment_intents \
  -H "Authorization: Bearer sk_sandbox_YOUR_KEY" \
  -H "Idempotency-Key: order-1001-attempt-1" \
  -H "Content-Type: application/json" \
  -d @payment.json

The sandbox card 4109090000000011 (expiry 12/2030, CVC 123) is a domestic credit card that approves. Other test cards are listed in the sandbox guide. Card numbers are accepted only inside payment_method_data[card]; the platform replaces them with a vault token before anything is stored or logged, and they are never returned.

3. Read the result

When the card needs no 3-D Secure step the payment is already succeeded:

{
  "id": "pi_01J9ZQ4V8K2M3N5P7R9T1W3Y5A",
  "object": "payment_intent",
  "amount": 12500,
  "amount_charged": 12500,
  "surcharge": 0,
  "amount_received": 12500,
  "captured_minor": 12500,
  "refunded_minor": 0,
  "amount_refundable": 12500,
  "currency": "try",
  "status": "succeeded",
  "capture_method": "automatic",
  "installments": 1,
  "payment_method_type": "card",
  "card": {
    "brand": "visa",
    "bin": "410909",
    "last4": "0011",
    "masked": "410909******0011",
    "exp_month": 12,
    "exp_year": 2030,
    "card_type": "credit",
    "domestic": true
  },
  "next_action": null,
  "last_payment_error": null,
  "description": "Order 1001",
  "metadata": {"order_id": "1001"},
  "created": 1790000000,
  "livemode": false
}

When the issuer asks the customer to authenticate, the payment is requires_action and next_action tells you where to send the customer. Handle both outcomes, as the 3-D Secure guide explains:

{
  "id": "pi_01J9ZQ4V8K2M3N5P7R9T1W3Y5B",
  "object": "payment_intent",
  "amount": 12500,
  "currency": "try",
  "status": "requires_action",
  "capture_method": "automatic",
  "next_action": {
    "type": "redirect_to_url",
    "redirect_to_url": {
      "url": "https://pay.example.com/3ds/start/att_01J9ZQ4V8K2M3N5P7R9T1W3Y5C",
      "return_url": "https://shop.example.com/pay/return"
    }
  },
  "created": 1790000000,
  "livemode": false
}

Do not mark the order as paid from the redirect alone. Treat payment_intent.succeeded (a webhook, see the webhooks guide) or a GET /v1/payment_intents/{id} that returns succeeded as the source of truth.

curl https://pay.example.com/v1/payment_intents/pi_01J9ZQ4V8K2M3N5P7R9T1W3Y5A \
  -H "Authorization: Bearer sk_sandbox_YOUR_KEY"

4. Next steps