K KalphaPay API v1
OpenAPI 3.1 spec

KalphaPay API

KalphaPay is a payment orchestration gateway. A CRM or trading platform integrates once. KalphaPay then presents a hosted cashier, routes each Pay In to one of the broker’s payment service providers (Stripe, Airwallex, …), and reports the outcome to the CRM with a signed webhook.

This document describes everything a CRM needs to build a native KalphaPay connector, in the same way trading-platform CRMs integrate cashier providers such as Paytiko or BridgerPay:

  • the server-to-server API to create a cashier session
  • the hosted cashier you show to the client
  • the webhook you receive when a payment completes
Card data never touches KalphaPay. Payers type their card into the PSP’s own secure fields inside the cashier, so card numbers go straight to Stripe or Airwallex. How it works

New here? Start with Choose an integration: it compares every way to take Pay Ins and send Pay Outs, for CRM providers and for brokers.

Base URL https://api.kalphapay.com · All requests and responses are JSON over HTTPS · Amounts are decimal numbers in major units (e.g. 100.50).

Choose an integration

Every KalphaPay integration ends the same way: one of the broker’s PSPs takes the payment, KalphaPay routes it and confirms it, and a signed webhook reports the result. What differs is who starts the payment and who credits the trading account.

What never differs is who renders the card field. It is always the PSP’s own secure fields inside the KalphaPay cashier, so on every path card data stays out of your systems and out of KalphaPay’s (see Card data never touches KalphaPay).

For CRM and trading-platform providers

Build once into your CRM; every broker on your platform can then switch KalphaPay on with their own keys. The Match-Trader connector guide maps each field.

For brokers (merchants)

No development, or almost none. Configured in the KalphaPay back office.

Compare the paths

PathWho starts the paymentWho renders the card fieldYou buildWho credits the trading accountBest when
Hosted cashierYour CRM: POST /v1/sessionsThe PSP, inside the KalphaPay cashierOne API call, a redirect, a webhook handlerYour CRM, on transaction.approvedYou want the fastest integration that works everywhere
Embedded cashierYour CRMThe PSP, inside the KalphaPay cashierThe same, plus one script tagYour CRMThe client should stay inside Client Office
KalphaPay credits for youYour site or CRM, with platform.loginThe PSPOne API call and a redirect; no credit logicKalphaPay, via Match-Trade CRM-APIThe broker’s CRM has no KalphaPay gateway yet
Pay In portalThe client, at /portal/<broker>The PSPNothing: the broker switches it onKalphaPay, via Match-Trade CRM-APIA launch with no development at all
Payment linksBroker staff, in the back officeThe PSPNothingKalphaPay (with a Match-Trader connection) or finance, who is remindedSupport cases and top-ups over email or chat
Pay Outs APIYour CRM: POST /v1/payouts, or broker staffNo card field: refunds go back to the original cardOne API call and a webhook handlerYour CRM deducts first and returns funds only if the Pay Out failsWithdrawals

You are not locked in

  • Paths combine: a CRM connector for everyday Pay Ins, payment links for support cases and the Pay Outs API for withdrawals all share one merchant, one set of PSP connections and one webhook URL.
  • Every path uses the same router and the same PSPs, so the payment methods a client sees depend on the broker’s connections, not on the path.
  • Webhooks tell paths apart with data.transaction.source: api, portal or payment_link. Pay Outs carry source api or back_office.

Card data never touches KalphaPay

Card numbers, expiry dates and CVCs are typed into secure fields that the PSP itself serves inside the cashier: Stripe’s Payment Element or Airwallex’s Drop-in. They travel straight from the payer’s browser to the PSP over TLS. KalphaPay’s servers never receive, process or store card data, and neither do yours.

Card data goes straight from the payer’s browser to the PSP Payer’s browser KalphaPay cashier page · amount, method, result PSP secure fields (served by Stripe / Airwallex) Card number 4242 4242 4242 4242 MM / YY CVC 3-D Secure also runs inside these fields PSP: Stripe / AirwallexReceives, stores and charges the card KalphaPay serversStatus, card brand, last 4 · never the card Your CRMSigned webhook · never the card card data, direct payment status webhook no card data
Who sees what. Only the PSP ever receives the card number, expiry and CVC.
WhoReceivesNever receives
PSP (Stripe, Airwallex)Card number, expiry, CVC, 3-D Securen/a: the PSP is the card processor
KalphaPayPSP payment reference, status, card brand, last 4 digits, amount, payer email and nameCard number, expiry, CVC
Your CRMSigned webhooks and API responses with the same non-sensitive fieldsCard number, expiry, CVC
  • Because the card form is never on your page (redirect, iframe or pop-up), the cashier keeps your PCI scope to the minimum. Confirm the exact questionnaire with your acquirer.
  • Bank account details for Pay Outs are not card data. They are checked with the PSP, encrypted at rest (AES-256-GCM) and only ever shown masked (•••• 1234).
  • Test mode only: the built-in Simulator’s form accepts published test card numbers. It is never offered to live merchants.

Pay In flow

Pay In through a CRM connector Client browser Your CRM server KalphaPay KalphaPay PSP Stripe / Airwallex Clicks “Deposit” in Client Office 1 POST /v1/sessions 2 cashier_url + token 3 Redirect, or embed with launcher.js 4 Opens the cashier, picks a method 5 Card details, typed into the PSP’s own fields 6 Result (webhook + API check) 7 Signed webhook: transaction.approved 8 Credit the trading account, once 9 Result page → success_url 10
Pay In flow. The green arrow is the only path card data takes: straight from the payer’s browser to the PSP.
  1. CRM The client clicks Deposit and picks the KalphaPay gateway.
  2. CRM → KalphaPay Your server calls POST /v1/sessions with the order, amount, client and trading account. You receive a cashier_url and a session token.
  3. Client You redirect the client to cashier_url, or embed it with the launcher script. The client chooses a payment method and pays. 3-D Secure and alternative payment methods are handled inside the cashier.
  4. KalphaPay → PSP KalphaPay processes the payment with the PSP and confirms the result with the PSP directly.
  5. KalphaPay → CRM KalphaPay POSTs a signed transaction.approved (or transaction.declined, …) webhook to your notification_url.
  6. CRM You verify the signature and credit the trading account once per approved Pay In. The client returns to your success_url.

KalphaPay never credits the trading account itself in this model: your CRM stays the single source of truth for balances. Send the trading account only as information, with trading_account.login.

Quick start

  1. Get a test secret key (sk_test_…) and webhook signing secret (whsec_…) from the broker’s KalphaPay admin: Merchants → API & webhooks.
  2. Create a session:
curl -X POST https://api.kalphapay.com/v1/sessions \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 6f1c2a8e-crm-deposit-10001" \
  -d '{
    "order_id": "6f1c2a8e-crm-deposit-10001",
    "amount": 100,
    "currency": "USD",
    "country": "GB",
    "customer": { "email": "jane@example.com", "first_name": "Jane", "last_name": "Doe" },
    "trading_account": { "login": "700101" },
    "notification_url": "https://crm.broker.com/deposit/kalphano/callback",
    "success_url": "https://client.broker.com/deposit/success",
    "failure_url": "https://client.broker.com/deposit/failed"
  }'
  1. Open the returned cashier_url and pay with test card 4242 4242 4242 4242.
  2. Receive transaction.approved at your notification_url, verify the signature, and credit the account.

Environments & credentials

There is one host for both modes. The merchant’s environment decides what happens:

EnvironmentSecret key prefixPayment methods offeredlivemode
Testsk_test_Simulator test cards and PSP sandbox connections only. No real money moves.false
Livesk_live_Live PSP connections onlytrue

What a connector needs to store per broker

SettingExampleUsed for
API base URLhttps://api.kalphapay.comAll API calls (/v1)
Checkout hosthttps://checkout.kalphapay.comlauncher.js, cashier, payment links and the Pay In portal. You don’t build these URLs yourself: cashier_url, launcher.script_url and details_url come back in API responses.
Secret API keysk_live_…Authorization: Bearer header. Server-side only, never in a browser.
Webhook signing secretwhsec_…Verifying KalphaPay-Signature

Brokers can restrict API access to your CRM’s outbound IPs (IP allowlist in the admin). Requests from other IPs get 403.

Authentication

Send the merchant’s secret API key as a bearer token on every request:

Authorization: Bearer sk_live_9fQ…

Keys are shown once when created or replaced, and KalphaPay stores only a hash. A missing, invalid or revoked key returns 401. A disabled merchant or a non-allowlisted IP returns 403.

A merchant can have several API keys, for example one per payment gateway in your CRM. Each key can open its own cashier page; see Several gateways, one merchant.

Create a session POST /v1/sessions

Creates a cashier session for one Pay In. A session can hold several payment attempts: if the client is declined, they can retry with another method in the same session. Sessions expire after the merchant’s session lifetime (default 60 minutes).

Headers

AuthorizationrequiredBearer <secret key>
Idempotency-KeyrecommendedAny unique string, e.g. your payment-request UUID. Replays return the original response. See Idempotency.

Body

FieldTypeDescription
order_id requiredstringYour unique reference for this Pay In (e.g. the CRM payment-request UUID). 1–255 chars. Must not contain spaces or " ' / ` < > { } + @. It is echoed in every webhook.
currency requiredstringISO 4217 code, e.g. USD. Use the trading account’s currency.
amountnumberAmount in major units (100.50). If omitted, the client enters the amount in the cashier.
amount_lockedbooleanPrevents the client from changing the amount. Defaults to true when amount is sent.
countrystringISO 3166-1 alpha-2 of the client (e.g. MY). Picks the broker’s cashier page for that country and the eligible payment methods. Defaults to customer.country.
customerobjectemail, first_name, last_name, phone (E.164), country. Prefills the cashier and is sent to the PSP for risk checks.
trading_accountobject{ "login": "700101" }. Informational only: shown in the broker’s back office and echoed in webhooks. KalphaPay does not credit it.
notification_urlstringHTTPS URL that receives this session’s webhooks. It overrides the merchant’s default webhook URL.
success_urlstringWhere the client goes after an approved payment. KalphaPay appends order_id, kp_reference and kp_status as query parameters.
failure_urlstringWhere the client goes after giving up on a declined payment (same query parameters).
cancel_urlstringShown as “Cancel and return” before paying.
languagestringISO 639-1 language for the cashier, e.g. en.
themestringlight or dark. Overrides the theme chosen in the cashier designer. Default: the designer setting, else the client’s system setting.
metadataobjectFree-form key/values. Returned unchanged in transaction.metadata.
payloadstringUp to 1000 chars. Returned as transaction.metadata.payload. Useful for an extra integrity token.

Response 201 Created

{
  "livemode": false,
  "session": {
    "id": "0b7e1c52-6a3e-4c55-9c38-2f1f1c1c9e10",
    "order_id": "6f1c2a8e-crm-deposit-10001",
    "amount": 100,
    "currency": "USD",
    "amount_locked": true,
    "status": "open",
    "expires_at": "2026-11-22T11:00:00.000Z"
  },
  "token": "cs_Qm9vb…",
  "cashier_url": "https://checkout.kalphapay.com/cashier/?s=cs_Qm9vb…",
  "launcher": {
    "script_url": "https://checkout.kalphapay.com/launcher.js",
    "html": "<script src=\"https://checkout.kalphapay.com/launcher.js\" data-token=\"cs_Qm9vb…\" data-mode=\"iframe\"></script>"
  }
}

The token gives access to the cashier for this session only. Treat it like a one-time payment link, and never log it in client-side analytics.

Show the cashier

Choose one option:

1 · Redirect

Send the client’s browser to cashier_url. This is the simplest option and works everywhere.

2 · Embed with the launcher (iframe or pop-up)

<div id="kalphapay-cashier"></div>
<script src="https://checkout.kalphapay.com/launcher.js"
        data-token="cs_Qm9vb…"
        data-mode="iframe"                 <!-- iframe | popup | redirect -->
        data-container="#kalphapay-cashier"
        data-auto-redirect="true"></script>
AttributeDescription
data-tokenSession token (required).
data-modeiframe (default), popup or redirect.
data-containerCSS selector for the iframe container. Defaults to the script’s parent element.
data-buttonPop-up mode only: a selector for your own button that opens the cashier.
data-auto-redirectWhen true (default), the page navigates to the success or failure URL when the client clicks “Return”.

Prefer a plain iframe? Point it at cashier_url and keep allow="payment *" so Apple Pay and Google Pay work inside the frame:

<iframe src="CASHIER_URL" title="Deposit" allow="payment *"
        style="width:100%;min-height:680px;border:0"></iframe>

Browser events are dispatched on window. They are for UI only. Credit the account only from the server-side webhook.

window.addEventListener('kalphapay:status', (e) => {
  // e.detail = { status: 'approved' | 'declined' | 'pending' | ..., transaction: { id, reference, amount, currency } }
});
window.addEventListener('kalphapay:redirect', (e) => {
  // e.detail = { url }. Call e.preventDefault() to handle navigation yourself.
});

KalphaPay was called Kalphano Pay before. The launcher also fires every event under its old name (kalphano:status, kalphano:payout_status, kalphano:redirect), so pages written for the old name keep working.

Cashier page per country

Each broker designs its own cashier page in the back office (Cashier designer), with drag and drop and a live phone preview. No code is needed and nothing changes in the API call. For every country the broker chooses:

  • which payment methods (PSP connections) are shown, and which are hidden;
  • their order (the first one is pre-selected);
  • the name, subtitle, card logos and flag the client sees, e.g. FPX Online Banking · Maybank, CIMB and more.

The page title, intro text, button text, list or grid layout, theme, logo and brand colour apply to every country.

POST /v1/sessions "country": "MY" POST /v1/sessions "country": "GB" Malaysia page FPX Online Banking Cards Default page Cards Bank transfer Only what this page lists, in this order and naming. Every other country. New PSPs are added at the end automatically.

Rules

Which pageThe session’s country (or customer.country) picks that country’s page. Without a country, or for a country with no page of its own, the Default page is used.
Country pagesShow only the methods they list. A PSP connected later is not added to them automatically.
Default pageAlso shows connections it does not mention yet, at the end, so a new PSP is never hidden by accident. The broker can switch this off per page (“Add new payment providers to this page automatically”).
Eligibility still appliesA listed method appears only if it accepts the currency and amount, is enabled, and matches the merchant’s test or live mode.
Hidden means hiddenA method hidden on a page can’t be paid with through the API either.
Your own buttonsGET /v1/payment-methods returns the same list, order, names, subtitles and logos for a country.

The same page works as a full-page redirect and inside an iframe. Changes apply as soon as the broker saves, including sessions that are already open. The designer’s preview uses real preview sessions, which can never take a payment.

Several gateways, one merchant

Some CRMs treat one API key as one payment gateway. To offer, say, a Cards gateway and a Crypto gateway, create one API key per gateway in the back office (Merchants → API & webhooks → API keys) and paste each key into its gateway in the CRM.

  • Each key opens either the merchant’s main cashier page or its own page. An own page has its own methods, order, names and texts for every country, set up in the Cashier designer; it starts as a copy of the main page.
  • New PSP connections are not added to a key’s own page automatically, so a crypto-only gateway stays crypto-only.
  • The key used to create a session decides the page the client sees. GET /v1/payment-methods answers for the page of the key that calls it.
  • Everything else is shared by all keys of a merchant: Pay Ins and Pay Outs, webhooks and their signing secret, test or live mode, the IP allowlist and the logo and brand colour.
  • Payment links and the Pay In portal use the main page.

Nothing changes in the API calls themselves. A key can be renamed, given a new secret (the old one stops working at once) or revoked at any time.

Webhooks

When a Pay In reaches a final status, KalphaPay sends POST with a JSON body to the session’s notification_url (or the merchant’s default webhook URL).

Event types

TypeMeaningWhat to do
transaction.approvedThe money was taken.Credit the trading account with amount and currency, once per transaction.id.
transaction.declinedThe PSP declined this attempt.Record it. The client may retry in the same session, so do not mark the order failed yet (see Statuses).
transaction.failedTechnical failure at the PSP.Same as declined.
transaction.cancelledThe payment was cancelled.Same as declined.
transaction.expiredNo final status within 24 h.Mark the attempt expired.
transaction.creditedOnly when KalphaPay credits accounts itself (CRM-API mode).A native connector can ignore it.
payout.*Withdrawals — see Pay Out webhooks.
test.pingSent from the admin’s “Send test event” button.Reply 2xx.

Request

POST /deposit/kalphano/callback HTTP/1.1
Content-Type: application/json
User-Agent: KalphaPay-Webhooks/1.0
KalphaPay-Event-Id: evt_6c1d8a9b2f3e4d5c8b7a6f5e4d3c2b1a
KalphaPay-Event-Type: transaction.approved
KalphaPay-Signature: t=1795305600,v1=5b2c0e…f41a
{
  "id": "evt_6c1d8a9b2f3e4d5c8b7a6f5e4d3c2b1a",
  "type": "transaction.approved",
  "created_at": "2026-11-22T10:04:12.311Z",
  "data": {
    "transaction": {
      "id": "d2bfa434-b57f-48cf-ab55-49cd0c3a0dd8",
      "reference": "KP-J52EZELAFT",
      "type": "deposit",
      "status": "approved",
      "order_id": "6f1c2a8e-crm-deposit-10001",
      "amount": 100,
      "amount_minor": 10000,
      "currency": "USD",
      "customer": { "email": "jane@example.com", "first_name": "Jane", "last_name": "Doe", "country": "GB" },
      "payment": { "provider": "stripe", "psp_reference": "pi_3Q…", "method": "card", "card_brand": "visa", "card_last4": "4242", "decline_reason": null },
      "trading_account": { "login": "700101" },
      "credit": null,
      "attempt": 1,
      "metadata": {},
      "created_at": "2026-11-22T10:03:40.112Z",
      "completed_at": "2026-11-22T10:04:12.298Z"
    }
  }
}

Delivery rules

  • Reply with any 2xx within 15 seconds. Acknowledge first and process asynchronously.
  • On a timeout, a non-2xx reply or a redirect, KalphaPay retries up to 8 attempts, waiting 10 s, 30 s, 2 min, 10 min, 30 min, 1 h and 3 h between them (about 4.5 hours in total). Brokers can re-send any event from the admin.
  • Delivery is at least once, so the same event can arrive twice. De-duplicate by id (the event) and credit once per data.transaction.id.
  • Order is not guaranteed. Always trust data.transaction.status, or fetch the Pay In (GET /v1/transactions/{id}) when in doubt.
  • Your parser must ignore unknown fields. New fields can be added without notice.
  • data.transaction.source tells where the payment started: api (your session), portal, or payment_link (a link created by broker staff, with payment_link_id). Payments you did not start have an order_id you do not know; ignore them or reconcile them by reference.

Verify signatures

KalphaPay-Signature: t=<unix seconds>,v1=<hex>, where v1 = HMAC-SHA256(webhook_secret, t + "." + raw_body).

The same values are also sent as Kalphano-Signature, Kalphano-Event-Id and Kalphano-Event-Type (the names from before the rename), so receivers built for them keep working. New integrations should read the KalphaPay- headers.

To check it:

  1. Compute the HMAC over the raw request bytes, not re-serialized JSON.
  2. Compare it to v1 in constant time.
  3. Reject the request if t is more than 5 minutes from your clock.
import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;
import java.nio.charset.StandardCharsets;
import java.security.MessageDigest;
import java.time.Instant;
import java.util.HexFormat;

public static boolean verifyKalphaPay(String header, byte[] rawBody, String secret) throws Exception {
    String t = null, v1 = null;
    for (String part : header.split(",")) {
        String[] kv = part.trim().split("=", 2);
        if (kv.length == 2 && kv[0].equals("t")) t = kv[1];
        if (kv.length == 2 && kv[0].equals("v1")) v1 = kv[1];
    }
    if (t == null || v1 == null) return false;
    if (Math.abs(Instant.now().getEpochSecond() - Long.parseLong(t)) > 300) return false;

    Mac mac = Mac.getInstance("HmacSHA256");
    mac.init(new SecretKeySpec(secret.getBytes(StandardCharsets.UTF_8), "HmacSHA256"));
    mac.update((t + ".").getBytes(StandardCharsets.UTF_8));
    String expected = HexFormat.of().formatHex(mac.doFinal(rawBody));
    return MessageDigest.isEqual(expected.getBytes(StandardCharsets.UTF_8), v1.getBytes(StandardCharsets.UTF_8));
}

KalphaPay credits for you (CRM-API mode)

For brokers whose CRM has no KalphaPay gateway yet. The broker connects Match-Trade’s CRM-API in the KalphaPay back office (Merchants → Match-Trader) and maps a MANUAL payment gateway per currency. You then create sessions with platform instead of trading_account, and KalphaPay credits the account itself after the payment is approved.

KalphaPay credits the trading account (CRM-API mode) Client browser Your site or CRM KalphaPay KalphaPay PSP Stripe / Airwallex Match-Trader CRM-API POST /v1/sessions with platform.login 1 Redirect to cashier_url 2 Card details, in the PSP’s own fields 3 Payment approved 4 Manual deposit on the MANUAL gateway 5 Webhooks: transaction.approved, transaction.credited 6
KalphaPay credits the account through the broker’s Match-Trade CRM-API connection. Your system only starts the payment.
{
  "order_id": "site-10001",
  "amount": 100,
  "currency": "USD",
  "customer": { "email": "jane@example.com" },
  "platform": { "login": "700101" }
}

platform.system_uuid is optional; without it KalphaPay uses the connection’s default trading system.

  • Each approved Pay In becomes a manual deposit in Match-Trader, so it appears in the client’s history and the broker’s Back Office.
  • You receive transaction.approved and then transaction.credited. data.transaction.credit shows the credit status and the Match-Trader reference.
  • KalphaPay never credits twice. If Match-Trader does not answer clearly, the Pay In is marked needs review for the broker’s finance team instead of being retried blindly.

Pay In portal No code

A KalphaPay-hosted deposit page for each broker at /portal/<broker>. The broker switches it on under Merchants → Settings, connects Match-Trade’s CRM-API, and links to it from their website or Client Office.

Pay In portal Client browser KalphaPay KalphaPay PSP Stripe / Airwallex Match-Trader CRM-API Opens /portal/<broker>, enters email 1 6-digit code by email 2 Finds the client’s trading accounts 3 Picks an account and an amount 4 Card details, in the PSP’s own fields 5 Payment approved 6 Credits the account (manual deposit) 7 Success page 8
Pay In portal: no development. KalphaPay looks up and credits trading accounts with the broker’s Match-Trade CRM-API connection.
  • Clients sign in with their email and a one-time code. Only trading accounts that belong to that email are offered, and unknown emails get the same answer as known ones, so the page cannot be used to discover clients.
  • The currency follows the trading account. After approval KalphaPay credits the account through the CRM-API, as in CRM-API mode.
  • Codes are sent by email, so the server needs an SMTP account in production.

Pay Outs (withdrawals)

A Pay Out sends money back to a client. KalphaPay follows the card-scheme return-to-source rule: card Pay Ins are refunded first, newest first, up to what each card paid in. Whatever is left (for example trading profit) is sent by bank transfer to an account in the client’s name.

  1. Client requests a withdrawal; CRM deducts the amount from the trading account (as for any withdrawal).
  2. CRM calls POST /v1/payouts. The response shows the plan: which card refunds, and whether a bank transfer is needed.
  3. If a bank transfer is needed and the CRM did not send bank details, the response has a details_url. Show it to the client (redirect, pop-up or launcher, like the cashier). Client enters their bank account there.
  4. By default the broker’s finance team approves the Pay Out in the KalphaPay back office (pending_approval). Brokers can switch approval off or require it only above an amount.
  5. KalphaPay pays and sends a signed payout.completed, payout.failed, payout.rejected or payout.cancelled webhook.
Pay Out (withdrawal) Client browser Your CRM server KalphaPay KalphaPay PSP card refund / bank Requests a withdrawal 1 Deducts the balance 2 POST /v1/payouts 3 Plan, and details_url if a bank transfer is needed 4 Shows details_url (bank form) 5 Bank account (checked, encrypted) 6 Approval in the back office (on by default) 7 Refund card Pay Ins, then bank transfer 8 Paid 9 Signed webhook: payout.completed 10 failed / rejected / cancelled → return funds 11
Pay Out flow. Card Pay Ins are refunded first (return to source); the rest goes by bank transfer.
Balance rule. Return the funds to the trading account only on payout.failed, payout.rejected or payout.cancelled. These are sent only when no money left. On payout.completed, mark the withdrawal done. KalphaPay never reports “failed” once part of a Pay Out was paid; a broker resolves such cases in the back office.

Create a Pay Out POST /v1/payouts

Headers

AuthorizationrequiredBearer <secret key>
Idempotency-KeyrecommendedUse the CRM withdrawal UUID. A retry returns the original response, so a Pay Out is never created twice.

Body

FieldTypeDescription
order_id requiredstringYour withdrawal ID. Unique per merchant: a second Pay Out with the same order_id returns 409.
amount requirednumberMajor units, e.g. 250.00.
currency requiredstringISO 4217. Card refunds use Pay Ins in this currency; bank transfers are sent in this currency.
customer requiredobjectemail (required, used to find the client’s card Pay Ins), first_name, last_name, country.
trading_accountobject{ "login": "700101" }. Informational; echoed in webhooks.
methodstringauto (default: cards first, then bank), card_refund (fails with 422 if the cards cannot cover the amount) or bank_transfer.
bank_accountobjectOptional. { "country": "GB", "fields": { … } } with the fields from the bank schema. Without it, the client enters the bank account on the hosted page (details_url).
notification_urlstringHTTPS URL for this Pay Out’s webhooks (default: the merchant’s webhook URL).
return_urlstringWhere the hosted bank-details page sends the client afterwards.
metadata, payloadobject, stringReturned unchanged in the Pay Out object.

Response 201 Created

{
  "livemode": false,
  "payout": {
    "id": "8d1e0a54-3f0b-4a8e-9a51-0c2b9e6c7d11",
    "reference": "PO-7F3K9Q2MXA",
    "order_id": "crm-withdrawal-20031",
    "source": "api",
    "status": "awaiting_details",
    "amount": 1000,
    "paid_amount": 0,
    "currency": "USD",
    "method": "auto",
    "customer": { "email": "jane@example.com", "first_name": "Jane", "last_name": "Doe", "country": "GB" },
    "trading_account": { "login": "700101" },
    "requires_approval": false,
    "bank_account": null,
    "plan": [
      { "method": "card_refund", "amount": 300, "refunded_transaction": "KP-J52EZELAFT", "card": { "brand": "visa", "last4": "4242" } },
      { "method": "bank_transfer", "amount": 700, "refunded_transaction": null, "card": null }
    ],
    "legs": [],
    "created_at": "2026-11-22T12:00:00.000Z",
    "completed_at": null
  },
  "details_url": "https://checkout.kalphapay.com/cashier/?p=po_…"
}

Common 422 errors: Pay Outs not enabled for the merchant; details.code = "not_refundable" (card-only Pay Out larger than the refundable amount, with details.refundable_amount_minor); "no_bank_method" (a bank transfer is needed but the broker has no bank-payout provider); bank details not accepted (details.fields lists each field’s problem).

Bank details GET /v1/payouts/bank-schema?country=GB&currency=GBP

Bank fields differ by country (sort code in the UK, IBAN in the EU, routing number in the US…). This endpoint returns what is needed for a local transfer, or SWIFT where no local rail exists:

{
  "country": "GB", "currency": "GBP", "transfer_method": "LOCAL",
  "fields": [
    { "key": "first_name", "label": "First name", "required": true, "pattern": "[\\s\\S]{1,100}", "options": null, "default": null },
    { "key": "last_name", "label": "Last name", "required": true, "pattern": "[\\s\\S]{1,100}", "options": null, "default": null },
    { "key": "routing_code", "label": "Sort code", "required": true, "pattern": "^[0-9]{6}$", "options": null, "default": null },
    { "key": "account_number", "label": "Bank account number", "required": true, "pattern": "^[0-9]{8}$", "options": null, "default": null },
    { "key": "account_name", "label": "Name of account holder", "required": true, "pattern": "…", "options": null, "default": null },
    { "key": "address_country", "label": "Country or region", "required": true, "pattern": "…", "options": [ … ], "default": "GB" },
    { "key": "postcode", "label": "Postcode", "required": true, "pattern": "…", "options": null, "default": null },
    { "key": "street_address", "label": "Address", "required": true, "pattern": "…", "options": null, "default": null },
    { "key": "city", "label": "City", "required": true, "pattern": "…", "options": null, "default": null }
  ]
}

Send the values as bank_account.fields, keyed by key. Patterns are anchored regular expressions. The details are validated with the bank network before the Pay Out is accepted, stored encrypted, and never returned in full: the Pay Out shows only bank_account.account_hint (e.g. •••• 5678). The account must be in the client’s own name.

Hosted bank-details page

Instead of collecting bank details in the CRM, show the client details_url, either by redirect or with the launcher: <script src="https://checkout.kalphapay.com/launcher.js" data-type="payout" data-token="po_…"></script>. The page shows what is refunded to which card, asks for the bank account, and dispatches kalphapay:payout_status when done. The link works once and expires (default 72 h); an expired link cancels the Pay Out (payout.cancelled).

Pay Out object & statuses

StatusMeaningFinal?
awaiting_detailsWaiting for the client’s bank details (hosted page).no
pending_approvalWaiting for the broker’s finance team in the KalphaPay back office.no
approvedApproved (or approval not needed); payment starts within seconds.no
processingRefunds / transfer sent to the providers. Bank transfers usually take 0–3 business days.no
needs_reviewPart was paid and part failed, or a provider reversed a payment. The broker resolves it; no webhook is sent for this state.no
completedEverything was paid. paid_amount = amount.yes
failedNothing was paid. Return the funds.yes
rejectedRejected by the broker before paying. Return the funds.yes
cancelledCancelled before paying (by you, the broker, or an expired bank-details link). Return the funds.yes

legs lists the individual movements once payment started: method (card_refund | bank_transfer), status (pending | paid | failed | cancelled), amount, provider, psp_reference, card, refunded_transaction_id and failure_reason.

Retrieve and cancel

GET /v1/payouts/{id} (id or PO- reference) · GET /v1/payouts?order_id={order_id} · POST /v1/payouts/{id}/cancel with an optional { "reason": "…" }. Cancelling works only before payment starts (awaiting_details, pending_approval, or approved but not yet processing); otherwise it returns 422.

Pay Out webhooks

TypeWhat to do
payout.processingOptional: show “in progress” to the client.
payout.completedMark the withdrawal done.
payout.failed · payout.rejected · payout.cancelledMark the withdrawal failed and return the funds to the trading account, once per data.payout.id.

The body is { "id", "type", "created_at", "data": { "payout": { … } } }, signed with KalphaPay-Signature exactly like Pay In webhooks. Pay Outs created by broker staff in the back office carry "source": "back_office"; their order_id starts with BO- and the CRM can ignore them.

Pay In object

A Pay In is one payment attempt inside a session. In the API and in webhooks it is the transaction object.

FieldTypeDescription
iduuidKalphaPay In ID. Use it to de-duplicate credits.
referencestringShort human reference, e.g. KP-J52EZELAFT. Shown to the client and in comments.
typestringdeposit
statusstringSee Statuses.
order_idstringYour session order_id.
amount / amount_minornumber / integerAmount in major and minor units (e.g. 100.5 / 10050).
currencystringISO 4217
customerobjectemail, first_name, last_name, country
paymentobjectprovider (stripe, airwallex, simulator), psp_reference, method, card_brand, card_last4, decline_reason
trading_accountobject|null{ login } as sent in the session.
creditobject|nullAlways null for native connectors. It is only set when KalphaPay credits the account itself through the CRM-API: { status, system_uuid, reference }.
attemptinteger1 for the first payment attempt in the session, 2 for a retry, and so on.
metadataobjectYour session metadata (+ payload).
created_at / completed_atISO 8601UTC timestamps

Statuses

created → pending → approved
pending → declined | failed | cancelled | expired
StatusFinal?Meaning
creatednoAttempt registered, not yet sent to the PSP.
pendingnoWaiting for the client (card form, 3-D Secure, bank app) or for the PSP.
approvedyesThe money was taken. This status never changes.
declinedyes*Declined by the issuer or PSP.
failedyes*Technical error at the PSP.
cancelledyes*Cancelled by the client or PSP.
expiredyes*No final answer from the PSP within 24 h.

* Late approvals. A PSP can still confirm a payment after reporting a decline, timeout or expiry, for example after an internal retry. When that happens, KalphaPay moves the Pay In to approved and sends transaction.approved.

For your connector, this means:

  • Always credit on approved, even after an earlier declined for the same Pay In.
  • Several attempts can share one order_id. Treat the order as paid when any of its Pay Ins is approved.

Retrieve Pay Ins

GET /v1/transactions/{id}

{id} is the Pay In UUID or its reference. The response is { "transaction": { … } }.

GET /v1/transactions?order_id={order_id}&limit=50

All attempts for one of your orders, newest first (limit ≤ 200). The response is { "data": [ … ] }. Use it to reconcile if you suspect a missed webhook.

POST /v1/transactions/{id}/sync

Asks the PSP for the latest status right now and applies it. The response is { "transaction": { … }, "changed": true|false }. A status change also triggers the normal webhook.

Payment methods GET /v1/payment-methods?currency=USD&country=GB&amount=100

Lists the methods the cashier would offer for these parameters, in the order, and with the names, of the broker’s cashier page for that country. Use it to hide the KalphaPay gateway when nothing is available (for example, an unsupported currency), or to draw your own method buttons.

{
  "livemode": true,
  "data": [
    { "id": "a1f2…", "title": "FPX Online Banking", "subtitle": "Maybank, CIMB and more", "icons": ["flag:MY", "bank"],
      "provider": "airwallex", "min_amount": null, "max_amount": null },
    { "id": "5d8c…", "title": "Cards", "subtitle": "Visa, Mastercard, Amex, Apple Pay, Google Pay", "icons": ["visa", "mastercard", "amex"],
      "provider": "stripe", "min_amount": 10, "max_amount": 10000 }
  ]
}

icons contains visa, mastercard, amex, jcb, unionpay, discover, applepay, googlepay, card, bank, qr, wallet, crypto, cash, or flag:XX (ISO country code).

Retrieve a session GET /v1/sessions/{id}

Returns { "session": { … }, "transactions": [ … ] }. Session status is open, completed (an approved payment exists) or expired.

Errors

Errors use HTTP status codes and a JSON body:

{ "error": "validation_error", "message": "currency: Invalid currency", "details": [ … ] }
HTTPerrorWhen
400validation_error, bad_requestInvalid or missing fields. message says which.
401unauthorizedMissing or invalid API key
403forbiddenMerchant disabled, or IP not on the allowlist
404not_foundUnknown session or Pay In
409idempotency_mismatch / idempotency_in_progressThe same Idempotency-Key was used with a different body, or is still processing
422unprocessableValid request that cannot be processed, e.g. no payment method for this currency
429—Rate limit exceeded. Retry after the retry-after seconds.
5xxinternal_errorRetry with the same Idempotency-Key.

Rate limits & idempotency

  • Rate limit: 300 requests per minute per API key on /v1. Responses include x-ratelimit-limit, x-ratelimit-remaining and x-ratelimit-reset.
  • Idempotency: send Idempotency-Key on POST /v1/sessions and POST /v1/payouts. The same key with the same body returns the original 201 response, so a network retry never creates two sessions. The same key with a different body returns 409. Keys are scoped to the merchant. Using your order_id as the key is a good default.

Match-Trader connector guide

This is the recommended mapping for a native KalphaPay gateway in the Match-Trade CRM. It mirrors how Paytiko and BridgerPay gateways work today.

Gateway configuration fields (per broker)

API base URLhttps://api.kalphapay.com
Secret API keysk_live_… / sk_test_… (one per gateway, see Several gateways)
Webhook signing secretwhsec_…
Display modeiframe (launcher) or redirect

Pay In request (CRM deposit) → POST /v1/sessions

KalphaPay fieldMatch-Trade CRM source
order_id + Idempotency-KeyDeposit / payment-request UUID
amount, currencyRequested amount; trading-account currency
trading_account.loginTrading account login
customer.email / first_name / last_name / phoneAccount personal details
countryAccount country (ISO alpha-2)
notification_urlCRM callback, e.g. https://<client-office-host>/deposit/kalphano/callback
success_url / failure_urlClient Office result pages
metadatae.g. { "accountUuid": "…", "systemUuid": "…", "branchUuid": "…" }

Callback handling

  1. Verify KalphaPay-Signature, then reply 200 immediately.
  2. Find the CRM deposit by data.transaction.order_id.
  3. On transaction.approved, credit data.transaction.amount in data.transaction.currency to the trading account, once per data.transaction.id. Store data.transaction.reference as the external payment ID.
  4. If the amount or currency differs from what was requested, which can only happen when amount_locked was false, credit the amount actually paid.
  5. On declined, failed or cancelled, keep the CRM deposit open until the session expires (the client may retry), then mark it failed.

Withdrawal request → POST /v1/payouts

KalphaPay fieldMatch-Trade CRM source
order_id + Idempotency-KeyWithdrawal UUID
amount, currencyRequested amount; trading-account currency (already deducted from the balance)
customer.email / first_name / last_name / countryAccount personal details (email must match the Pay Ins)
trading_account.loginTrading account login
bank_accountOptional: the withdrawal form’s bank fields, mapped with the bank schema
notification_urlCRM callback, e.g. https://<client-office-host>/withdrawal/kalphano/callback
return_urlClient Office withdrawals page

If the response has a details_url, open it for the client (like the cashier). On payout.completed mark the withdrawal done; on payout.failed / rejected / cancelled return the funds, once per data.payout.id.

Testing

Use a test merchant (sk_test_). Its cashier offers the Simulator, and the card number decides the outcome:

Card numberResult
4242 4242 4242 4242approved (Visa)
5555 5555 5555 4444approved (Mastercard)
4000 0000 0000 0002declined: card declined
4000 0000 0000 9995declined: insufficient funds
4000 0000 0000 0119failed: processor error
4000 0000 0000 0077stays pending

Any expiry in the future and any CVC work. Test merchants can also use PSP sandbox connections, such as Stripe test keys or Airwallex demo, with those providers’ own test cards: for example Stripe 4242 4242 4242 4242 or Airwallex 4035 5010 0000 0008. The broker’s back office has a page per provider (Payment providers → Setup guide & test cards) with the full lists, 3-D Secure cards and sandbox bank accounts.

Pay Out test values (Simulator)

Card refundsSucceed, except for Pay Ins made with 4000 0000 0000 5126, whose refunds fail (to test partial Pay Outs).
Bank account number ending 99Transfer fails.
Bank account number ending 77Transfer stays pending (use “Simulate paid / failed” in the back office).
Any other account numberTransfer is paid at once.

Scenarios to certify

  • Approved payment → exactly one credit
  • Decline, then retry with another card in the same session → one credit
  • Duplicate webhook delivery (re-send from the admin) → still one credit
  • Callback endpoint down for 1 minute → the retry is processed
  • Invalid signature → rejected, no credit
  • POST /v1/sessions retried with the same Idempotency-Key → same session
  • Missed webhook → reconciled with GET /v1/transactions?order_id=
  • Pay Out refunded to the card → payout.completed → withdrawal done
  • Pay Out with a bank transfer via details_url → payout.completed
  • Pay Out rejected / failed / cancelled → funds returned exactly once
  • POST /v1/payouts retried with the same Idempotency-Key → same Pay Out

Go-live checklist

  • Live merchant created, with live PSP connections tested in the admin
  • Secret key and webhook secret stored encrypted in the CRM gateway configuration
  • CRM outbound IPs added to the merchant’s IP allowlist (optional)
  • notification_url reachable over HTTPS from KalphaPay’s servers
  • Signature verification and crediting once per Pay In in place
  • A small real Pay In approved and credited end to end

Changelog

2026-11-23Cashier page per country: the session country picks the broker’s page. subtitle and icons added to payment methods.
2026-11-22Pay Outs: POST /v1/payouts, bank schema, hosted bank-details page, payout.* webhooks; source and payment_link_id on Pay In webhooks.
2026-11-22v1: sessions, hosted cashier and launcher, webhooks with HMAC signatures, Pay Ins, payment methods, the trading_account and notification_url session fields, and test/live environments.