Skip to content

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 URLInteractive referenceOpenAPI
https://sandbox-api.keshless.comSandbox SwaggerSandbox 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 ​

OperationCredential
Partner payments, refunds, webhooks, balance, history, and sandbox toolsX-API-Key: YOUR_INTEGRATION_KEY
Create, list, rotate or revoke integration keysAuthorization: Bearer VENDOR_ACCESS_TOKEN
Merchant login and token refreshCredentials 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

Keshless payment integration documentation