Quick start

Create your first test payment, pay it on the test checkout page and confirm the result, in about five minutes.

This guide takes you from zero to a confirmed test payment. You need a Teyra Pay account (sign up at app.teyra.co) and a terminal. Test mode is available as soon as you sign up, before your account is approved.

Take your first test payment

Get your test secret key

In the dashboard, open Developers → API keys and create a key in Test mode. Copy the secret: it starts with sk_test_ and is shown only once.

Store it in an environment variable on your server:

export TEYRA_SECRET_KEY="sk_test_..."

Secret keys belong on your server only. Never put them in a web page, a mobile app or a public repository.

Create a payment

Call POST /v1/payments with the amount in minor units. 12500 in KWD is 12.500 KWD.

curl https://api.teyra.co/v1/payments \
  -H "Authorization: Bearer $TEYRA_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-1042" \
  -d '{
    "amount": 12500,
    "currency": "KWD",
    "return_url": "https://shop.example.com/thanks",
    "description": "Order #1042",
    "reference": "1042"
  }'

The response is a Payment in status requires_payment:

{
  "id": "pay_01JBX4T9W2",
  "object": "payment",
  "livemode": false,
  "amount": 12500,
  "currency": "KWD",
  "status": "requires_payment",
  "checkout_url": "https://api.teyra.co/checkout/pay_01JBX4T9W2",
  "return_url": "https://shop.example.com/thanks",
  "expires_at": "2026-10-28T15:07:00.000Z"
}

Pay on the test checkout page

Open checkout_url in your browser. It shows the Teyra Pay checkout page with a TEST badge: your business name, the description and the amount, with secure card fields connected to the card processor's test environment. No real money moves.

Pay with a test card. When the payment succeeds, you are sent to your return_url:

https://shop.example.com/thanks?payment_id=pay_01JBX4T9W2&status=succeeded

Confirm the payment from your server

The query string is only a hint: anyone can type it. Before you fulfil the order, fetch the payment with your secret key and check its status.

curl https://api.teyra.co/v1/payments/pay_01JBX4T9W2 \
  -H "Authorization: Bearer $TEYRA_SECRET_KEY"

You should see "status": "succeeded" with paid_at set. The payment also appears in the dashboard under Payments.

What's next

Add a webhook endpoint so you hear about payments even when the customer never returns to your site.
Read Return URL handling for a production-ready return page.
When you're ready, switch to live mode.