Skip to content

Payment quick start ​

Developer test requests use the isolated sandbox at https://sandbox-api.keshless.com. Request sandbox access in the developer dashboard. Wait for administrator approval, then choose Create test key in your workspace. Use the dashboard or merchant authentication to manage your keys. Keep credentials on your server.

bash
export KESHLESS_BASE_URL=https://sandbox-api.keshless.com
export KESHLESS_INTEGRATION_KEY=YOUR_SANDBOX_KEY

Get test customers ​

bash
curl -X POST "$KESHLESS_BASE_URL/api/integration/sandbox/fixtures" \
  -H "X-API-Key: $KESHLESS_INTEGRATION_KEY"

The response contains merchant-specific test customers, their actual userId, cardNumber, test PIN 1234, current balance, and a signed-webhook test receiver URL. Initial scenarios:

ScenarioStarting balanceExpected use
verifiedE150Successful payment
pin_requiredE150Test a payment above E50 with a valid PIN
insufficient_balanceE0Reject a payment without moving money
unverifiedE150Reject a payment pending verification

Repeated fixture requests return the same customers and current balances; they do not replenish spent funds. These customers work only with their owning merchant. No real customer account or phone number is needed. Use the sandbox guide to refill test balances and inspect simulated SMS messages.

Accept a payment ​

Choose the verified customer's returned card number. Create one unique key per purchase and save it with the exact request body before sending the request.

bash
export PAYMENT_KEY=$(uuidgen)
curl -X POST "$KESHLESS_BASE_URL/api/integration/payment" \
  -H "X-API-Key: $KESHLESS_INTEGRATION_KEY" \
  -H "Idempotency-Key: $PAYMENT_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"amount":25.5,"cardNumber":"RETURNED_CARD_NUMBER","pin":"1234","description":"Sandbox purchase","clientReference":"order-1001"}'

Amounts are in SZL with at most two decimal places. Supply exactly one of cardNumber or userId. A PIN is required above E50. Payments of E50 or less can omit a PIN. Every supplied PIN is verified, including below E50.

A successful result under data includes reference, status, customerCharged, merchantReceived, userFee, merchantFee, and replayed. Store the reference. See response and error examples.

Recover from a timeout ​

Look up the purchase by its saved key:

bash
curl "$KESHLESS_BASE_URL/api/integration/payments/by-key/$PAYMENT_KEY" \
  -H "X-API-Key: $KESHLESS_INTEGRATION_KEY"

Retry with the same key and purchase details after a timeout or an unknown outcome. A completed request replays its recorded result without another debit. HTTP 409 can mean a request is still processing or the key was reused with different details; read the message. A 404 lookup means no outcome was found yet; retry the original request with its original key. Use a new key only for a new purchase or after confirming the original operation is FAILED.

Test refunds and webhooks ​

Payments and keys covers full-principal refunds, webhook configuration, signature verification, event retries, and a sandbox migration rehearsal. The fixture response includes a receiver URL that verifies signatures for you. Add ?simulateFailure=1 to exercise delivery failure and retry handling.

Moving to production ​

Existing integrations keep their current connection settings. New integrations use separate live credentials after explicit activation. The rehearsal checks portability inside the sandbox only; it does not move money, promote test credentials, or activate production.

Sandbox Swagger · Sandbox OpenAPI · All endpoints

Keshless payment integration documentation