Skip to content

Payments and integration keys ​

Sandbox requests go to https://sandbox-api.keshless.com. Every path includes /api. Keep API keys, merchant login tokens, and webhook signing secrets on your server. Existing integrations retain their current URLs and credentials. Sandbox keys and balances never become live keys or money.

Merchant authentication ​

bash
curl -X POST https://sandbox-api.keshless.com/api/auth/vendor/login \
  -H 'Content-Type: application/json' \
  -d '{"email":"YOUR_MERCHANT_EMAIL","password":"YOUR_PASSWORD"}'

Login accepts an email or phone number and password. Use the returned vendor-owner access token for key management. An employee account cannot create owner keys. Refresh with POST /api/auth/vendor/refresh-token and JSON refreshToken; use the returned expiry.

Create and manage a key ​

bash
curl -X POST https://sandbox-api.keshless.com/api/integrations \
  -H 'Authorization: Bearer VENDOR_ACCESS_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{"vendorId":"VENDOR_ID","appName":"custom"}'

vendorId and appName are required. Use custom for a payment integration. Optional fields: future expiresAt and ipWhitelist containing exact IPv4/IPv6 addresses. IP restrictions compare the address observed by the API; ask Keshless to verify that address when requests pass through proxies. CIDR ranges are not accepted. Save the raw key when created or rotated; it is shown once. Sandbox keys start with kl_test_ and are valid only in the isolated sandbox. Existing kl_live_ credentials keep their existing endpoint; they do not authenticate here.

Sandbox provisioning supplies an initial active custom key. Use or rotate that key; creating another active key for the same app is rejected. See the sandbox guide for test-fund refills and captured SMS.

MethodEndpointInput
GET/api/integrationsQuery vendorId
POST/api/integrationsJSON creation fields
GET/api/integrations/{id}Key ID and query vendorId
DELETE/api/integrations/{id}Key ID and query vendorId
POST/api/integrations/{id}/rotateKey ID and query vendorId

Expired, revoked, and IP-restricted keys are rejected. Rotation revokes the old key atomically and preserves the webhook configuration. Payment replay references belong to the merchant, so they continue to work with its new key.

Balance and history ​

bash
curl https://sandbox-api.keshless.com/api/integration/balance \
  -H 'X-API-Key: YOUR_INTEGRATION_KEY'
curl 'https://sandbox-api.keshless.com/api/integration/transactions?limit=2&offset=2' \
  -H 'X-API-Key: YOUR_INTEGRATION_KEY'

History accepts limit (1–100, default 50), offset (integer zero or greater, default 0), startDate, endDate, and the documented transaction type. Dates may be supplied independently. Results use exact offset pagination with a stable descending creation-time and ID order. The response provides pagination.offset, limit, total, and hasNext. New transactions can shift offsets between requests.

Accept a payment ​

bash
curl -X POST https://sandbox-api.keshless.com/api/integration/payment \
  -H 'X-API-Key: YOUR_INTEGRATION_KEY' \
  -H 'Idempotency-Key: order-1001-attempt-1' \
  -H 'Content-Type: application/json' \
  -d '{"amount":25.5,"cardNumber":"RETURNED_CARD_NUMBER","pin":"1234","description":"Purchase","clientReference":"order-1001"}'
FieldRequirement
amountPositive SZL number, at most two decimal places, maximum 1,000,000; wallet limits still apply
cardNumberEight uppercase letters/digits; provide exactly this or userId
userIdAlternative customer identifier; provide exactly this or cardNumber
pinFour digits; required above E50. Every supplied PIN is verified, including for smaller payments
descriptionOptional, maximum 200 characters
clientReferenceOptional merchant order reference, maximum 128 characters

The API checks customer eligibility, wallet restrictions, balance, limits, and every supplied PIN. Money movements, limit tracking, the durable outcome, and its webhook event commit together. Each platform fee is charged once. Required verification failures return a 5xx response without committing a payment; optional analytics run after commit. PINs are not stored in retry records.

Safe retries ​

Idempotency-Key is required for payment and refund POSTs. Use 8–128 letters, digits, dots, underscores, colons, or hyphens. Save a different key for each new operation.

Repeat the same key and purchase fields to retrieve a completed outcome without another debit. Changing amount, customer, description, or clientReference with that key returns 409. A stored failure remains failed; correcting a confirmed failed attempt requires a new key. PIN is not part of the saved purchase fingerprint.

After a timeout, look up GET /api/integration/payments/by-key/{key} or retry the original request with its original key. Do not create a new key while the first outcome is unknown. A busy service returns 429 with Retry-After: 1; retry the original key after waiting. A concurrent request still processing returns 409; poll or retry the same key.

Payment and refund status ​

bash
curl https://sandbox-api.keshless.com/api/integration/payments/PAYMENT_REFERENCE \
  -H 'X-API-Key: YOUR_INTEGRATION_KEY'

A merchant can look up its own payment or refund by reference. Status is PENDING, COMPLETED, FAILED, or REFUNDED for a refunded payment. A failed operation includes a failure with statusCode and message. A refunded payment includes refundReference.

Refund a payment ​

bash
curl -X POST https://sandbox-api.keshless.com/api/integration/payments/PAYMENT_REFERENCE/refund \
  -H 'X-API-Key: YOUR_INTEGRATION_KEY' \
  -H 'Idempotency-Key: order-1001-refund-1' \
  -H 'Content-Type: application/json' \
  -d '{"reason":"Customer returned the purchase"}'

Refunds return the full purchase principal once. reason is required (1–200 characters). Partial refunds are unavailable. Original user and merchant platform fees are retained (feesRefunded: false); the original payment commission is reversed. The merchant must have sufficient float for principal plus commission reversal. Restricted customer funds return to the restricted wallet. A repeated refund key replays its outcome; a second refund with another key returns 409. The status lookup shows the original payment as REFUNDED.

Configure webhooks ​

bash
curl -X PUT https://sandbox-api.keshless.com/api/integration/webhook \
  -H 'X-API-Key: YOUR_INTEGRATION_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"url":"https://YOUR_MERCHANT_HOST/payments/webhook"}'

The response returns signingSecret once. Save it securely. Each PUT generates a new secret. GET /api/integration/webhook reads settings without revealing the secret; DELETE stops new events. Already queued events retain their saved destination and secret. URLs must resolve only to public addresses, use HTTPS port 443, and contain no credentials or fragment. Redirects are not followed.

Events: payment.completed, payment.failed, refund.completed, refund.failed. Event payload:

json
{
  "id": "EVENT_ID",
  "type": "payment.completed",
  "createdAt": "2026-10-13T18:00:00.000Z",
  "environment": "sandbox",
  "data": {"reference":"PAYMENT_REFERENCE","status":"COMPLETED","amount":25.5,"currency":"SZL"}
}

The data contains the operation result; a failure contains its reference, amount, currency, and failure details. Deduplicate by event id: delivery is at least once. Retries can deliver events out of order; use the status lookup for the current payment state. Respond with 2xx only after you have durably accepted the event.

Verify signatures ​

Headers are X-Keshless-Event-Id, X-Keshless-Timestamp (Unix seconds), and X-Keshless-Signature. The signature is v1= plus the hex HMAC-SHA256 of timestamp + "." + rawBody. Verify before parsing or trusting the body. Reject timestamps outside five minutes.

js
import crypto from 'node:crypto'

export function verifyKeshlessWebhook(rawBody, timestamp, signature, secret) {
  if (!/^\d+$/.test(timestamp) || Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) return false
  const expected = Buffer.from('v1=' + crypto.createHmac('sha256', secret)
    .update(timestamp + '.').update(rawBody).digest('hex'))
  const supplied = Buffer.from(signature || '')
  return expected.length === supplied.length && crypto.timingSafeEqual(expected, supplied)
}

Capture the exact request bytes before any JSON middleware changes them. Check the event header matches the signed body ID. Keep the previous secret while events queued before a secret rotation may still arrive.

Delivery failures and retries ​

bash
curl 'https://sandbox-api.keshless.com/api/integration/webhook/events?limit=50&offset=0' \
  -H 'X-API-Key: YOUR_INTEGRATION_KEY'
curl -X POST https://sandbox-api.keshless.com/api/integration/webhook/events/EVENT_ID/retry \
  -H 'X-API-Key: YOUR_INTEGRATION_KEY'

The event list shows status, attempts, lastError, nextAttemptAt, and deliveredAt. Delivery accepts only 2xx, times out after ten seconds, and retries up to ten attempts with exponential delays starting at 30 seconds and capped at one hour. The dispatcher runs every minute, so delivery may happen after the scheduled retry time. After the tenth failure, status is FAILED. Failures remain visible; they do not reverse an already completed payment.

Correct the receiver configuration, then retry a failed event. Manual retry uses the calling integration key's current webhook configuration and resets the attempt count. It is allowed for PENDING events with a delivery error or FAILED events, unless delivery is currently in progress.

Sandbox fixtures and migration rehearsal ​

POST /api/integration/sandbox/fixtures returns four isolated test scenarios and a signature-verifying receiver URL. See the quick start. Configure the returned URL as your webhook destination. Append ?simulateFailure=1 to test a 503 receiver failure, then restore the working URL and retry the event.

bash
curl -X POST https://sandbox-api.keshless.com/api/integration/sandbox/migration-rehearsal \
  -H 'X-API-Key: YOUR_INTEGRATION_KEY'

The rehearsal copies this merchant's identity, hashed keys, webhook signing credential, and operation history into independent temporary sandbox tables. It verifies authentication and saved retry outcomes, then drops the tables. The result reports each check, operationsChecked, merchantChangesRequired: false, sandboxWalletBalancesMigrated: false, and productionChanged: false. This proves sandbox portability for the tested records; the actual production cutover remains a separate Keshless-operated rollout. Sandbox payments will not become real sales or balances.

Responses and errors ​

The JSON envelope contains success, message, timestamp, and path; successful results are under data. This illustrative payment example assumes zero fees; use the returned values rather than assuming fees are zero:

json
{
  "success": true,
  "message": "Success",
  "timestamp": "2026-10-13T18:00:00.000Z",
  "path": "/api/integration/payment",
  "data": {
    "reference": "PAYMENT_REFERENCE",
    "status": "COMPLETED",
    "amount": 25.5,
    "currency": "SZL",
    "environment": "sandbox",
    "customerId": "SANDBOX_CUSTOMER_ID",
    "customerCharged": 25.5,
    "merchantReceived": 25.5,
    "userFee": 0,
    "merchantFee": 0,
    "clientReference": "order-1001",
    "walletTransactionId": "TRANSACTION_ID",
    "createdAt": "2026-10-13T18:00:00.000Z",
    "replayed": false
  }
}

Example rejected reuse of a key:

json
{
  "success": false,
  "message": "Idempotency-Key was already used with different request details",
  "timestamp": "2026-10-13T18:00:00.000Z",
  "path": "/api/integration/payment"
}

Example validation or balance failure (HTTP 400):

json
{
  "success": false,
  "message": "Validation Error",
  "error": "Insufficient balance",
  "timestamp": "2026-10-13T18:00:00.000Z",
  "path": "/api/integration/payment"
}
HTTP statusMeaning / handling
400Invalid body, missing retry key, eligibility, balance, or limit failure; show the returned error text
401Missing, expired, revoked, invalid, or IP-restricted credentials
403Incorrect PIN, permission failure, or sandbox operations disabled
404No operation or resource belonging to this merchant was found
409Key reused with changed details, operation processing, or already refunded; read the message
423PIN is locked after repeated incorrect attempts; follow the returned message
429Service capacity / rate limit reached; respect Retry-After where supplied
5xxProcessing or dependency failed; check stored status before retrying money operations

Error details vary by operation. Read the status; use error when it is a string, otherwise message, for the returned explanation; never replace an error with a successful payment screen. A Cloudflare 403 with code 1010 is an edge rejection before API authentication. Network and upstream errors can also return a non-JSON body. Treat every non-2xx response as a failure, and look up saved payment status before retrying a money operation.

Sandbox Swagger · Sandbox OpenAPI · Endpoint list

Keshless payment integration documentation