Developer guide

Quickstart (15-min walkthrough)

From zero to a verified sandbox transaction with webhook delivery in 15 minutes. Eight concrete steps.

Context and key considerations

Concrete walkthrough — 8 commands, ~15 minutes, end with a verified webhook delivery on your local machine. Every command below works copy-pasted against https://sandbox.key2pay.ai/api/v1 with a test secret key.

In this guide1 / 8

1. Get sandbox keys

Log into the merchant portal at merchant.key2pay.ai → Shops & API keys. You'll see one pair of test keys per shop: pk_test_… (publishable, safe for client) and sk_test_… (secret, server-only). Copy the secret — that's all you need for backend integration.

bash

export K2P=sk_test_…

2. Ping the API

Confirms your key works, shows which environment you're hitting, returns the merchant name resolved from the credential. Idempotent and free.

bash

curl https://sandbox.key2pay.ai/api/v1/ping -H "Authorization: Bearer $K2P"

json

{
  "ok": true,
  "environment": "sandbox",
  "keyKind": "secret",
  "keyId": "sk_test_…7u10",
  "apiVersion": "2026-05-01",
  "merchant": { "id": "MCH-ON-009", "name": "Golden Dragon" }
}

3. Identify the merchant + see capabilities

Returns the merchant's tier, trustScore, enabled methods, and what features are unlocked.

bash

curl https://sandbox.key2pay.ai/api/v1/me -H "Authorization: Bearer $K2P"

4. List the methods available for this shop

One row per retailer / bank / native rail. Each one has a 4-digit paymentMethodId — store it, pass it back on POST /payments.

bash

curl "https://sandbox.key2pay.ai/api/v1/payment-methods?country=MX" -H "Authorization: Bearer $K2P"

You'll get the rails for MX. In sandbox the list ALWAYS includes the built-in test methods (sbx_pix, sbx_spei, sbx_card, sbx_pse, sbx_cash) — these are the same ones the sandbox playground uses. Note one — e.g. { "paymentMethodId": "sbx_spei", "name": "SPEI (sandbox)" }.

5. Create your first payment

With Sandbox-Simulate: paid the tx auto-completes in 5 seconds and a payment.completed webhook fires — perfect for testing your handler without manual UI clicks.

bash

curl https://sandbox.key2pay.ai/api/v1/payments \
  -H "Authorization: Bearer $K2P" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Sandbox-Simulate: paid" \
  -d '{
    "amount": 50,
    "paymentMethodId": "sbx_spei",
    "country": "MEX",
    "userEmail": "test@test.com",
    "merchantOrderId": "ORD-001",
    "tag1": "campaign:black-friday",
    "tag2": "channel:mobile-app",
    "tag3": "note:vip-customer"
  }'

6. Receive the webhook on your local machine

Expose your localhost with ngrok or cloudflared first (e.g. ngrok http 3000 → https://abc-123.ngrok-free.app). Then register the URL:

bash

curl https://sandbox.key2pay.ai/api/v1/webhooks \
  -H "Authorization: Bearer $K2P" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://abc-123.ngrok-free.app/webhooks/key2pay",
    "events": ["payment.completed", "payment.failed", "payment.refunded"]
  }'

# Response includes `secret` ONCE — save it now:
# { "id": "wh_...", "url": "...", "secret": "whsec_...", … }

Re-run step 5. Within ~5 seconds your endpoint receives a POST with payment.completed. Verify the X-Key2Pay-Signature header using HMAC-SHA256 with your secret — see Webhooks & signing for the verification snippet.

7. Refund

bash

# TXN-... is the transactionId from step 5
curl https://sandbox.key2pay.ai/api/v1/payments/TXN-…/refund \
  -H "Authorization: Bearer $K2P" \
  -H "Content-Type: application/json" \
  -d '{ "amount": 25, "reason": "requested_by_customer" }'

# Response (camelCase + ISO 8601, amount in local-currency major units):
# { "refundId": "CLM-...", "transactionId": "TXN-...", "amount": 25, "amountUsd": 1.45, "currency": "MXN", "status": "pending", "createdAt": "..." }

Your webhook handler also receives payment.refunded.