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
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.
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.
Hosted cashier
Create a session from your server and redirect the client to the KalphaPay cashier.
Embedded cashier
Same session, shown inside Client Office in an iframe or pop-up with one script tag.
Pay Outs API
Send withdrawals: refunds to the deposit cards first, then a bank transfer.
For brokers (merchants)
No development, or almost none. Configured in the KalphaPay back office.
Pay In portal
A KalphaPay-hosted page where clients sign in with an email code and deposit to their account.
Payment links
Create a link in the back office and send it by email or chat.
KalphaPay credits for you
Start a session with the trading login; KalphaPay credits Match-Trader through the CRM-API.
Compare the paths
| Path | Who starts the payment | Who renders the card field | You build | Who credits the trading account | Best when |
|---|---|---|---|---|---|
| Hosted cashier | Your CRM: POST /v1/sessions | The PSP, inside the KalphaPay cashier | One API call, a redirect, a webhook handler | Your CRM, on transaction.approved | You want the fastest integration that works everywhere |
| Embedded cashier | Your CRM | The PSP, inside the KalphaPay cashier | The same, plus one script tag | Your CRM | The client should stay inside Client Office |
| KalphaPay credits for you | Your site or CRM, with platform.login | The PSP | One API call and a redirect; no credit logic | KalphaPay, via Match-Trade CRM-API | The broker’s CRM has no KalphaPay gateway yet |
| Pay In portal | The client, at /portal/<broker> | The PSP | Nothing: the broker switches it on | KalphaPay, via Match-Trade CRM-API | A launch with no development at all |
| Payment links | Broker staff, in the back office | The PSP | Nothing | KalphaPay (with a Match-Trader connection) or finance, who is reminded | Support cases and top-ups over email or chat |
| Pay Outs API | Your CRM: POST /v1/payouts, or broker staff | No card field: refunds go back to the original card | One API call and a webhook handler | Your CRM deducts first and returns funds only if the Pay Out fails | Withdrawals |
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,portalorpayment_link. Pay Outs carrysourceapiorback_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.
| Who | Receives | Never receives |
|---|---|---|
| PSP (Stripe, Airwallex) | Card number, expiry, CVC, 3-D Secure | n/a: the PSP is the card processor |
| KalphaPay | PSP payment reference, status, card brand, last 4 digits, amount, payer email and name | Card number, expiry, CVC |
| Your CRM | Signed webhooks and API responses with the same non-sensitive fields | Card 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
- CRM The client clicks Deposit and picks the KalphaPay gateway.
- CRM → KalphaPay Your server calls
POST /v1/sessionswith the order, amount, client and trading account. You receive acashier_urland a sessiontoken. - 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. - KalphaPay → PSP KalphaPay processes the payment with the PSP and confirms the result with the PSP directly.
- KalphaPay → CRM KalphaPay POSTs a signed
transaction.approved(ortransaction.declined, …) webhook to yournotification_url. - 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
- Get a test secret key (
sk_test_…) and webhook signing secret (whsec_…) from the broker’s KalphaPay admin: Merchants → API & webhooks. - 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"
}'
- Open the returned
cashier_urland pay with test card4242 4242 4242 4242. - Receive
transaction.approvedat yournotification_url, verify the signature, and credit the account.
Environments & credentials
There is one host for both modes. The merchant’s environment decides what happens:
| Environment | Secret key prefix | Payment methods offered | livemode |
|---|---|---|---|
| Test | sk_test_ | Simulator test cards and PSP sandbox connections only. No real money moves. | false |
| Live | sk_live_ | Live PSP connections only | true |
What a connector needs to store per broker
| Setting | Example | Used for |
|---|---|---|
| API base URL | https://api.kalphapay.com | All API calls (/v1) |
| Checkout host | https://checkout.kalphapay.com | launcher.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 key | sk_live_… | Authorization: Bearer header. Server-side only, never in a browser. |
| Webhook signing secret | whsec_… | 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
Authorization | required | Bearer <secret key> |
Idempotency-Key | recommended | Any unique string, e.g. your payment-request UUID. Replays return the original response. See Idempotency. |
Body
| Field | Type | Description |
|---|---|---|
order_id required | string | Your 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 required | string | ISO 4217 code, e.g. USD. Use the trading account’s currency. |
amount | number | Amount in major units (100.50). If omitted, the client enters the amount in the cashier. |
amount_locked | boolean | Prevents the client from changing the amount. Defaults to true when amount is sent. |
country | string | ISO 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. |
customer | object | email, first_name, last_name, phone (E.164), country. Prefills the cashier and is sent to the PSP for risk checks. |
trading_account | object | { "login": "700101" }. Informational only: shown in the broker’s back office and echoed in webhooks. KalphaPay does not credit it. |
notification_url | string | HTTPS URL that receives this session’s webhooks. It overrides the merchant’s default webhook URL. |
success_url | string | Where the client goes after an approved payment. KalphaPay appends order_id, kp_reference and kp_status as query parameters. |
failure_url | string | Where the client goes after giving up on a declined payment (same query parameters). |
cancel_url | string | Shown as “Cancel and return” before paying. |
language | string | ISO 639-1 language for the cashier, e.g. en. |
theme | string | light or dark. Overrides the theme chosen in the cashier designer. Default: the designer setting, else the client’s system setting. |
metadata | object | Free-form key/values. Returned unchanged in transaction.metadata. |
payload | string | Up 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>
| Attribute | Description |
|---|---|
data-token | Session token (required). |
data-mode | iframe (default), popup or redirect. |
data-container | CSS selector for the iframe container. Defaults to the script’s parent element. |
data-button | Pop-up mode only: a selector for your own button that opens the cashier. |
data-auto-redirect | When 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.
Rules
| Which page | The 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 pages | Show only the methods they list. A PSP connected later is not added to them automatically. |
| Default page | Also 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 applies | A listed method appears only if it accepts the currency and amount, is enabled, and matches the merchant’s test or live mode. |
| Hidden means hidden | A method hidden on a page can’t be paid with through the API either. |
| Your own buttons | GET /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-methodsanswers 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
| Type | Meaning | What to do |
|---|---|---|
transaction.approved | The money was taken. | Credit the trading account with amount and currency, once per transaction.id. |
transaction.declined | The 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.failed | Technical failure at the PSP. | Same as declined. |
transaction.cancelled | The payment was cancelled. | Same as declined. |
transaction.expired | No final status within 24 h. | Mark the attempt expired. |
transaction.credited | Only when KalphaPay credits accounts itself (CRM-API mode). | A native connector can ignore it. |
payout.* | Withdrawals — see Pay Out webhooks. | |
test.ping | Sent 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
2xxwithin 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 perdata.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.sourcetells where the payment started:api(your session),portal, orpayment_link(a link created by broker staff, withpayment_link_id). Payments you did not start have anorder_idyou do not know; ignore them or reconcile them byreference.
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:
- Compute the HMAC over the raw request bytes, not re-serialized JSON.
- Compare it to
v1in constant time. - Reject the request if
tis 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));
}
import crypto from 'node:crypto';
export function verifyKalphaPay(header, rawBody /* Buffer */, secret) {
const parts = Object.fromEntries(header.split(',').map((p) => p.trim().split('=', 2)));
if (!parts.t || !parts.v1) return false;
if (Math.abs(Date.now() / 1000 - Number(parts.t)) > 300) return false;
const expected = crypto.createHmac('sha256', secret).update(`${parts.t}.`).update(rawBody).digest('hex');
return expected.length === parts.v1.length &&
crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(parts.v1));
}
function verifyKalphaPay(string $header, string $rawBody, string $secret): bool {
$parts = [];
foreach (explode(',', $header) as $p) {
[$k, $v] = array_pad(explode('=', trim($p), 2), 2, null);
$parts[$k] = $v;
}
if (empty($parts['t']) || empty($parts['v1'])) return false;
if (abs(time() - (int)$parts['t']) > 300) return false;
$expected = hash_hmac('sha256', $parts['t'] . '.' . $rawBody, $secret);
return hash_equals($expected, $parts['v1']);
}
// $raw = file_get_contents('php://input');
import hashlib, hmac, time
def verify_kalphapay(header: str, raw_body: bytes, secret: str) -> bool:
parts = dict(p.strip().split("=", 1) for p in header.split(",") if "=" in p)
t, v1 = parts.get("t"), parts.get("v1")
if not t or not v1 or abs(time.time() - int(t)) > 300:
return False
expected = hmac.new(secret.encode(), f"{t}.".encode() + raw_body, hashlib.sha256).hexdigest()
return hmac.compare_digest(expected, v1)
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.
{
"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.approvedand thentransaction.credited.data.transaction.creditshows 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.
- 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.
Payment links No code
Broker staff create a link in Payment links → New payment link. Each link has a fixed amount or lets the payer choose; is single-use (closes after the first approved payment) or reusable; and expires after 1–90 days. Opening https://checkout.kalphapay.com/pay/<code> starts a normal cashier session.
- With a trading login and a Match-Trader CRM-API connection, KalphaPay credits the account automatically. Otherwise the Pay In is flagged credit manually for the broker’s finance team.
- Your CRM still receives
transaction.*webhooks for these payments, withsource: "payment_link"andpayment_link_id. Theirorder_idstarts withPL-: ignore orders you did not create, or reconcile them byreference.
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.
- Client requests a withdrawal; CRM deducts the amount from the trading account (as for any withdrawal).
- CRM calls POST
/v1/payouts. The response shows the plan: which card refunds, and whether a bank transfer is needed. - 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. - 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. - KalphaPay pays and sends a signed
payout.completed,payout.failed,payout.rejectedorpayout.cancelledwebhook.
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
Authorization | required | Bearer <secret key> |
Idempotency-Key | recommended | Use the CRM withdrawal UUID. A retry returns the original response, so a Pay Out is never created twice. |
Body
| Field | Type | Description |
|---|---|---|
order_id required | string | Your withdrawal ID. Unique per merchant: a second Pay Out with the same order_id returns 409. |
amount required | number | Major units, e.g. 250.00. |
currency required | string | ISO 4217. Card refunds use Pay Ins in this currency; bank transfers are sent in this currency. |
customer required | object | email (required, used to find the client’s card Pay Ins), first_name, last_name, country. |
trading_account | object | { "login": "700101" }. Informational; echoed in webhooks. |
method | string | auto (default: cards first, then bank), card_refund (fails with 422 if the cards cannot cover the amount) or bank_transfer. |
bank_account | object | Optional. { "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_url | string | HTTPS URL for this Pay Out’s webhooks (default: the merchant’s webhook URL). |
return_url | string | Where the hosted bank-details page sends the client afterwards. |
metadata, payload | object, string | Returned 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¤cy=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
| Status | Meaning | Final? |
|---|---|---|
awaiting_details | Waiting for the client’s bank details (hosted page). | no |
pending_approval | Waiting for the broker’s finance team in the KalphaPay back office. | no |
approved | Approved (or approval not needed); payment starts within seconds. | no |
processing | Refunds / transfer sent to the providers. Bank transfers usually take 0–3 business days. | no |
needs_review | Part was paid and part failed, or a provider reversed a payment. The broker resolves it; no webhook is sent for this state. | no |
completed | Everything was paid. paid_amount = amount. | yes |
failed | Nothing was paid. Return the funds. | yes |
rejected | Rejected by the broker before paying. Return the funds. | yes |
cancelled | Cancelled 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
| Type | What to do |
|---|---|
payout.processing | Optional: show “in progress” to the client. |
payout.completed | Mark the withdrawal done. |
payout.failed · payout.rejected · payout.cancelled | Mark 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.
| Field | Type | Description |
|---|---|---|
id | uuid | KalphaPay In ID. Use it to de-duplicate credits. |
reference | string | Short human reference, e.g. KP-J52EZELAFT. Shown to the client and in comments. |
type | string | deposit |
status | string | See Statuses. |
order_id | string | Your session order_id. |
amount / amount_minor | number / integer | Amount in major and minor units (e.g. 100.5 / 10050). |
currency | string | ISO 4217 |
customer | object | email, first_name, last_name, country |
payment | object | provider (stripe, airwallex, simulator), psp_reference, method, card_brand, card_last4, decline_reason |
trading_account | object|null | { login } as sent in the session. |
credit | object|null | Always null for native connectors. It is only set when KalphaPay credits the account itself through the CRM-API: { status, system_uuid, reference }. |
attempt | integer | 1 for the first payment attempt in the session, 2 for a retry, and so on. |
metadata | object | Your session metadata (+ payload). |
created_at / completed_at | ISO 8601 | UTC timestamps |
Statuses
pending → declined | failed | cancelled | expired
| Status | Final? | Meaning |
|---|---|---|
created | no | Attempt registered, not yet sent to the PSP. |
pending | no | Waiting for the client (card form, 3-D Secure, bank app) or for the PSP. |
approved | yes | The money was taken. This status never changes. |
declined | yes* | Declined by the issuer or PSP. |
failed | yes* | Technical error at the PSP. |
cancelled | yes* | Cancelled by the client or PSP. |
expired | yes* | 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 earlierdeclinedfor 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": [ … ] }
| HTTP | error | When |
|---|---|---|
| 400 | validation_error, bad_request | Invalid or missing fields. message says which. |
| 401 | unauthorized | Missing or invalid API key |
| 403 | forbidden | Merchant disabled, or IP not on the allowlist |
| 404 | not_found | Unknown session or Pay In |
| 409 | idempotency_mismatch / idempotency_in_progress | The same Idempotency-Key was used with a different body, or is still processing |
| 422 | unprocessable | Valid request that cannot be processed, e.g. no payment method for this currency |
| 429 | — | Rate limit exceeded. Retry after the retry-after seconds. |
| 5xx | internal_error | Retry with the same Idempotency-Key. |
Rate limits & idempotency
- Rate limit: 300 requests per minute per API key on
/v1. Responses includex-ratelimit-limit,x-ratelimit-remainingandx-ratelimit-reset. - Idempotency: send
Idempotency-KeyonPOST /v1/sessionsandPOST /v1/payouts. The same key with the same body returns the original201response, so a network retry never creates two sessions. The same key with a different body returns409. Keys are scoped to the merchant. Using yourorder_idas 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 URL | https://api.kalphapay.com |
| Secret API key | sk_live_… / sk_test_… (one per gateway, see Several gateways) |
| Webhook signing secret | whsec_… |
| Display mode | iframe (launcher) or redirect |
Pay In request (CRM deposit) → POST /v1/sessions
| KalphaPay field | Match-Trade CRM source |
|---|---|
order_id + Idempotency-Key | Deposit / payment-request UUID |
amount, currency | Requested amount; trading-account currency |
trading_account.login | Trading account login |
customer.email / first_name / last_name / phone | Account personal details |
country | Account country (ISO alpha-2) |
notification_url | CRM callback, e.g. https://<client-office-host>/deposit/kalphano/callback |
success_url / failure_url | Client Office result pages |
metadata | e.g. { "accountUuid": "…", "systemUuid": "…", "branchUuid": "…" } |
Callback handling
- Verify
KalphaPay-Signature, then reply200immediately. - Find the CRM deposit by
data.transaction.order_id. - On
transaction.approved, creditdata.transaction.amountindata.transaction.currencyto the trading account, once perdata.transaction.id. Storedata.transaction.referenceas the external payment ID. - If the amount or currency differs from what was requested, which can only happen when
amount_lockedwasfalse, credit the amount actually paid. - 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 field | Match-Trade CRM source |
|---|---|
order_id + Idempotency-Key | Withdrawal UUID |
amount, currency | Requested amount; trading-account currency (already deducted from the balance) |
customer.email / first_name / last_name / country | Account personal details (email must match the Pay Ins) |
trading_account.login | Trading account login |
bank_account | Optional: the withdrawal form’s bank fields, mapped with the bank schema |
notification_url | CRM callback, e.g. https://<client-office-host>/withdrawal/kalphano/callback |
return_url | Client 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 number | Result |
|---|---|
4242 4242 4242 4242 | approved (Visa) |
5555 5555 5555 4444 | approved (Mastercard) |
4000 0000 0000 0002 | declined: card declined |
4000 0000 0000 9995 | declined: insufficient funds |
4000 0000 0000 0119 | failed: processor error |
4000 0000 0000 0077 | stays 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 refunds | Succeed, except for Pay Ins made with 4000 0000 0000 5126, whose refunds fail (to test partial Pay Outs). |
Bank account number ending 99 | Transfer fails. |
Bank account number ending 77 | Transfer stays pending (use “Simulate paid / failed” in the back office). |
| Any other account number | Transfer 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/sessionsretried with the sameIdempotency-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/payoutsretried with the sameIdempotency-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_urlreachable 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-23 | Cashier page per country: the session country picks the broker’s page. subtitle and icons added to payment methods. |
| 2026-11-22 | Pay Outs: POST /v1/payouts, bank schema, hosted bank-details page, payout.* webhooks; source and payment_link_id on Pay In webhooks. |
| 2026-11-22 | v1: 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. |