Appearance
Payment API reference
This reference covers the endpoints available to payment integration partners: merchant authentication, key management, payments, status lookups, refunds, webhooks, balance, transaction history, and sandbox test tools.
Current environment: sandbox
Developer sandbox calls go to https://sandbox-api.keshless.com.
| Base URL | Interactive reference | OpenAPI |
|---|---|---|
https://sandbox-api.keshless.com | Sandbox Swagger | Sandbox JSON |
Every documented endpoint includes /api. The public OpenAPI contract and Swagger target this sandbox endpoint.
Existing integrations retain their current connection settings. Sandbox testing uses separate credentials and simulated money; going live is an explicit activation with separate live credentials.
Authentication
| Operation | Credential |
|---|---|
| Partner payments, refunds, webhooks, balance, history, and sandbox tools | X-API-Key: YOUR_INTEGRATION_KEY |
| Create, list, rotate or revoke integration keys | Authorization: Bearer VENDOR_ACCESS_TOKEN |
| Merchant login and token refresh | Credentials or refresh token in the JSON body |
A vendor integration key is linked to one merchant. It is distinct from a vendor login token. Keep both on your server and use the sandbox credentials supplied for your integration.
Safe payment retries
Payment and refund POSTs require Idempotency-Key. Save one unique key per operation and retry the same purchase with the same key after a timeout. Look up the payment by reference or key before deciding to start another attempt. See the full retry rules.
Responses and errors
JSON responses include success, message, timestamp and path, with results under data on success. Error details vary by operation. Read the HTTP status and display error when it is a string, otherwise message.
json
{
"success": false,
"message": "API key is required",
"timestamp": "2026-10-13T15:00:00+02:00",
"path": "/api/integration/balance"
}Do not treat a failed request as successful. See the quick start, payments and keys and endpoint list.
Response shapes
The following examples use illustrative IDs, balances, and times. Read data after checking the HTTP status and success. Fees and balances come from the actual response.
Balance
json
{
"success": true,
"message": "Success",
"data": 250,
"timestamp": "2026-10-13T18:00:00.000Z",
"path": "/api/integration/balance"
}History
json
{
"success": true,
"message": "Success",
"data": {
"data": [
{
"id": "TRANSACTION_ID",
"type": "VENDOR_PAYMENT_RECEIVED",
"amount": 25.5,
"createdAt": "2026-10-13T18:00:00.000Z"
}
],
"pagination": {
"page": 2,
"offset": 2,
"limit": 2,
"total": 3,
"totalPages": 2,
"hasNext": false,
"hasPrev": true
}
},
"timestamp": "2026-10-13T18:00:00.000Z",
"path": "/api/integration/transactions?limit=2&offset=2"
}History rows contain additional receipt and counterparty fields where available; the example shows only the common fields.
Refund
json
{
"success": true,
"message": "Success",
"data": {
"reference": "REFUND_REFERENCE",
"paymentReference": "PAYMENT_REFERENCE",
"status": "COMPLETED",
"amount": 25.5,
"currency": "SZL",
"environment": "sandbox",
"feesRefunded": false,
"walletTransactionId": "TRANSACTION_ID",
"createdAt": "2026-10-13T18:00:00.000Z",
"replayed": false
},
"timestamp": "2026-10-13T18:00:00.000Z",
"path": "/api/integration/payments/PAYMENT_REFERENCE/refund"
}Failed operation status
json
{
"success": true,
"message": "Success",
"data": {
"reference": "PAYMENT_REFERENCE",
"status": "FAILED",
"amount": 25.5,
"currency": "SZL",
"environment": "sandbox",
"createdAt": "2026-10-13T18:00:00.000Z",
"failure": {
"statusCode": 400,
"message": "Insufficient balance"
},
"replayed": false
},
"timestamp": "2026-10-13T18:00:00.000Z",
"path": "/api/integration/payments/PAYMENT_REFERENCE"
}Webhook configuration
json
{
"success": true,
"message": "Success",
"data": {
"url": "https://YOUR_MERCHANT_HOST/payments/webhook",
"signingSecret": "SHOWN_ONCE_STORE_SECURELY",
"signatureFormat": "v1=HMAC-SHA256(timestamp + \".\" + rawBody)",
"events": [
"payment.completed",
"payment.failed",
"refund.completed",
"refund.failed"
]
},
"timestamp": "2026-10-13T18:00:00.000Z",
"path": "/api/integration/webhook"
}Webhook delivery status
json
{
"success": true,
"message": "Success",
"data": {
"events": [
{
"id": "EVENT_ID",
"operationId": "PAYMENT_REFERENCE",
"eventType": "payment.completed",
"status": "PENDING",
"attempts": 1,
"nextAttemptAt": "2026-10-13T18:00:30.000Z",
"lastError": "Webhook delivery failed: Webhook receiver returned HTTP 503",
"deliveredAt": null,
"receiverVerifiedAt": null,
"createdAt": "2026-10-13T18:00:00.000Z"
}
],
"pagination": {
"limit": 50,
"offset": 0,
"total": 1,
"hasNext": false
}
},
"timestamp": "2026-10-13T18:00:00.000Z",
"path": "/api/integration/webhook/events?limit=50&offset=0"
}Sandbox fixtures
json
{
"success": true,
"message": "Success",
"data": {
"environment": "sandbox",
"merchantId": "MERCHANT_ID",
"customers": [
{
"scenario": "verified",
"userId": "CUSTOMER_1",
"cardNumber": "A1B2C3D4",
"pin": "1234",
"balance": 150,
"currency": "SZL"
},
{
"scenario": "pin_required",
"userId": "CUSTOMER_2",
"cardNumber": "B2C3D4E5",
"pin": "1234",
"balance": 150,
"currency": "SZL"
},
{
"scenario": "insufficient_balance",
"userId": "CUSTOMER_3",
"cardNumber": "C3D4E5F6",
"pin": "1234",
"balance": 0,
"currency": "SZL"
},
{
"scenario": "unverified",
"userId": "CUSTOMER_4",
"cardNumber": "D4E5F6A7",
"pin": "1234",
"balance": 150,
"currency": "SZL"
}
],
"webhookReceiverUrl": "https://sandbox-api.keshless.com/api/partner-jobs/sandbox/webhook-receiver/MERCHANT_ID"
},
"timestamp": "2026-10-13T18:00:00.000Z",
"path": "/api/integration/sandbox/fixtures"
}Fixture IDs and cards above are illustrative. Use the actual values returned for your merchant.
Migration rehearsal
json
{
"success": true,
"message": "Success",
"data": {
"passed": true,
"environment": "sandbox",
"merchantIdPreserved": true,
"apiKeyPreserved": true,
"webhookSecretPreserved": true,
"replayHistoryPreserved": true,
"operationsChecked": 8,
"sandboxWalletBalancesMigrated": false,
"productionChanged": false,
"integrationBaseUrlBefore": "https://sandbox-api.keshless.com",
"integrationBaseUrlAfter": "https://sandbox-api.keshless.com",
"merchantChangesRequired": false,
"scope": "Credential and replay-history migration rehearsal in isolated temporary target tables"
},
"timestamp": "2026-10-13T18:00:00.000Z",
"path": "/api/integration/sandbox/migration-rehearsal"
}Payment success, webhook payload, signature verification, and error examples · Quick start