API Reference

Callbacks

In order to receive callbacks from our system, you need to specify 'Webhook Url' within website settings under Merchant Portal,
or provide 'webhookUrl' parameter in createPayment request. In case if "webhookUrl" is passed within the payment request,
it will override the static one configured in the system.

Signature verification

To ensure callbacks really come from our system, you can generate a Signing Key in your website settings.
If the Signing Key is specified, callbacks will include a Signature header.


How signature is generated (pseudocode)

input: rawBody, signingKey
algorithm: HMAC-SHA256
encoding: hex lowercase

function generateSignature(rawBody, signingKey):
bytes = HMAC_SHA256(key=signingKey, message=rawBody as UTF-8)
signatureHex = toHexLowercase(bytes)
return signatureHex

Key points:

  • Use the exact raw JSON body from the HTTP request (no pretty-print, no reordered fields).
  • Encode both key and body as UTF-8 before hashing.
  • Compare the generated hex string with the value in the Signature header.

Example

Raw body:

{"id":"6e58947ea2de4fc3bbca5e5169b2eb15","created":"2025-09-01T09:02:22.552859857","paymentType":"DEPOSIT","state":"COMPLETED","internalState":"COMPLETED","description":"Funding the account number 12345","paymentMethod":"BASIC_CARD","paymentMethodDetails":{"customerAccountNumber":"424242***4242","cardholderName":"test test","cardExpiryMonth":"09","cardExpiryYear":"2028","cardBrand":"VISA","cardIssuingCountry":"GB","cardBank":"STRIPE PAYMENTS UK LIMITED"},"amount":15,"currency":"EUR","customerAmount":15,"customerCurrency":"EUR","externalResultCode":null,"customer":{"referenceId":"01K2MFPXZV5J0XR9FXRTNYNA5G","citizenshipCountryCode":"GB","firstName":"Harry","lastName":"Potter","email":"[email protected]","phone":"52 2299377223","locale":"en"},"billingAddress":{"countryCode":"US","addressLine1":"211, Victory street","addressLine2":"Office 7B","city":"Hogwarts","state":"CA","postalCode":"01001"},"terminalName":"test"}

Signing key:

LtAs7UiLl5UQ

Generated signature (hex lowercase):

71724767a6ec1959a71dd128914b1c9fff3373bd0bfac44415d90fcd47a13b1d

Code samples

Python

import hmac, hashlib

raw_body = '{"id":"..."}'  # exact raw body
key = "LtAs7UiLl5UQ"

signature = hmac.new(
key.encode("utf-8"),
raw_body.encode("utf-8"),
hashlib.sha256
).hexdigest()  # lowercase hex

Node.js

const crypto = require("crypto");

const rawBody = '{"id":"..."}';  // exact raw body
const key = "LtAs7UiLl5UQ";

const signature = crypto
.createHmac("sha256", Buffer.from(key, "utf8"))
.update(Buffer.from(rawBody, "utf8"))
.digest("hex"); // lowercase

PHP

<?php
$rawBody = '{"id":"..."}'; // exact raw body
$key = "LtAs7UiLl5UQ";

$signature = hash_hmac("sha256", $rawBody, $key); // lowercase hex
?>

Java

import org.apache.commons.codec.digest.HmacAlgorithms;
import org.apache.commons.codec.digest.HmacUtils;

String rawBody = "{\"id\":\"...\"}"; // exact raw body
String key = "LtAs7UiLl5UQ";

String signature = new HmacUtils(
HmacAlgorithms.HMAC_SHA_256, key
).hmacHex(rawBody); // lowercase

If the calculated signature matches the Signature header, you can trust that the callback is genuine.

id
string <= 32 characters

Payment Id

referenceId
string <= 256 characters

referenceId from payment request

paymentType
string

Payment Type

state
string ( PaymentState )
Enum : "CHECKOUT" "PENDING" "CANCELLED" "DECLINED" "COMPLETED"

Payment State

description
string <= 512 characters

Description of the transaction

parentPaymentId
string <= 32 characters

Initial transaction Id from payment request, usually is used to proceed with refund OR in case if card PAN needs to be used for payouts.

paymentMethod
string ( PaymentMethod )
Enum : "ACTIVE" "ADVCASH" "ALFABANK_P2P" "ALIPAY" "ALTEL" "ALYCEPAY" "APPLEPAY" "APPLEPAYTOKEN" "ASTROPAY" "ASUPAY" "B2BINPAY" "BANCONTACT" "BANKTRANSFER" "BANK_TRANSFER_ARG" "BANK_TRANSFER_IND" "BANK_TRANSFER_JPY" "BANK_TRANSFER_KRW" "BANK_TRANSFER_PHP" "BANK_TRANSFER_PIX" "BANK_TRANSFER_PKR" "BANK_TRANSFER_SEPA" "BANK_TRANSFER_SWIFT" "BANK_TRANSFER_TRY" "BANK_TRANSFER_UK" "BASIC_CARD" "BCA" "BEELINE" "BILLLINE" "BILLPLZ" "BINANCEPAY" "BITEXPRO" "BITEXPRO_GOOGLEPAY" "BITEXPRO_ADVCARD" "BITEXPRO_ADVWALLET" "BITEXPRO_APPLEPAY" "BITEXPRO_BANCONTACT" "BITEXPRO_BANKTRANSFER" "BITEXPRO_BKASH" "BITEXPRO_BLIK" "BITEXPRO_BPWALLET" "BITEXPRO_CASH," "BITEXPRO_CREDITCARD" "BITEXPRO_CRYPTO" "BITEXPRO_EUROAPM" "BITEXPRO_EWALLET" "BITEXPRO_EXPAY" "BITEXPRO_GIROPAY" "BITEXPRO_GPAY" "BITEXPRO_HSP" "BITEXPRO_IDEAL" "BITEXPRO_MBWAY" "BITEXPRO_MEEZAQR," "BITEXPRO_MEEZAR2P," "BITEXPRO_MOBILEMONEY" "BITEXPRO_MULTIBANCO" "BITEXPRO_NAGAD" "BITEXPRO_NEOSURF" "BITEXPRO_NETBANKING" "BITEXPRO_NETELLER" "BITEXPRO_OPENBANK" "BITEXPRO_OPENBANKING" "BITEXPRO_P24" "BITEXPRO_P2P" "BITEXPRO_PAPARA" "BITEXPRO_PAYEER" "BITEXPRO_PAYSAFECARD" "BITEXPRO_PAYSAFECASH" "BITEXPRO_PAYTM" "BITEXPRO_PIX" "BITEXPRO_PAYCO" "BITEXPRO_PAYFIX" "BITEXPRO_QRPAYMENT" "BITEXPRO_RAPID" "BITEXPRO_RN," "BITEXPRO_ROCKET" "BITEXPRO_SBERPAY" "BITEXPRO_SBP" "BITEXPRO_SKRILL" "BITEXPRO_SOFORT" "BITEXPRO_SPEI" "BITEXPRO_STICPAY" "BITEXPRO_TRUSTLY" "BITEXPRO_UPI" "BITEXPRO_VODAFONE," "BITEXPRO_WALLET" "BKASH" "BLACK_RABBIT" "BLIK" "BNC" "BNI" "BOLETO" "BRI" "BSI" "CARDSHPP" "CARD_TO_CARD" "CASH" "CHEK" "CIMB" "CLICK" "CLICKQR" "COMMUNITYBANKING" "CRYPTO" "CRYPTO2CRYPTO" "CRYPTO2FIAT" "DANA" "DANAMON" "DEBITWAY" "DINO" "EFECTY" "EFT" "EMPAYRE" "EPAY" "EPS" "EUPAGO" "EUTELLER" "EWALLET" "EZPAY" "FAWRY" "FIAT2CRYPTO" "FINRAX" "FLEXEPIN" "FPS" "FYST" "GATE8TRANSACT" "GATEEXPRESS" "GCASH" "GIROPAY" "GOOGLEPAY" "GOOGLEPAYTOKEN" "GOPAY" "HAVALE" "HAYHAY" "HITES" "HUMO" "IBAN" "IDEAL" "IMPS" "INSTANTQR" "INTERAC" "INTERKASSA" "KAKAOPAY" "KCELL" "KESSPAY" "KHIPU" "KHIPUBANKTRANSFER" "KLARNA" "LATAM_BANKING" "LATAM_CASH" "LINKAJA" "LINK_AJA" "LOCALP2P" "LOCALPAYMENT" "LOCAL_BRAZIL" "LOCAL_CHILE" "LOCAL_MEXICO" "LOCAL_PERU" "LOTÉRICA" "M10" "M10_TO_M10" "MACH" "MACROPAY" "MANDIRI" "MAYBANK" "MB" "MBWAY" "MISTERCASH" "MOBILE" "MOBILEMONEY" "MOBILEMONEY_AIRTEL" "MOBILEMONEY_BANKTRANSFER" "MOBILEMONEY_MPESA" "MOBILEMONEY_MTN" "MOBILEMONEY_OPAY" "MOBILEMONEY_ORANGE" "MOBILEMONEY_OZOW" "MOBILEMONEY_PALMPAY" "MOBILEMONEY_PAYATTITUDE" "MOBILEMONEY_SNAPSCAN" "MOBILEMONEY_VODAFONE" "MOBILEMONEY_WAVE" "MOBILEMONEY_ZAMTEL" "MONETIX" "MONNET" "MOOV" "MPESA" "MTN" "MULTIBANCO" "NEFT" "NEOSURF" "NETBANKING" "NETELLER" "NGENIUS" "NUMICARD" "NUMIPAY_HPP" "NUMIPAY_VOUCHER" "ONLINEBANKING" "ONLINEBANKINGBTV" "OPENBANKING" "ORANGEMONEY" "OVO" "OXXO" "P24" "P2C" "P2P" "PAGOEFECTIVОCASH" "PAGOEFECTIVОONLINE" "PAGO_EFECTIVO" "PAG_SMILE" "PAPARA" "PAPARAPOOL" "PAPAZULA" "PAYBOL" "PAYCELL" "PAYCO" "PAYCOS" "PAYFIX" "PAYHERE" "PAYID" "PAYLER" "PAYMATRIX" "PAYMAXIS" "PAYMAYA" "PAYME" "PAYMEMOBILE" "PAYMOMENTUM" "PAYPAL" "PAYPORT" "PAYRETAILERS" "PAYRIVER" "PAYSAFECARD" "PAYSAFECASH" "PAYSCROW" "PAYTM" "PAYU" "PAY_BY_BANK" "PAY_SHOP" "PAY_U" "PEP" "PERFECTMONEY" "PERMATA" "PHONEPE" "PICPAY" "PID" "PIX" "POLI" "POPYPARA" "PRISMA_LINK" "PRZELEWY24" "PSEBANKTRANSFER" "PSPARK" "QBIT" "QRCODE" "QRIS" "RAIFFEISEN_P2P" "RAPIDTRANSFER" "RAPID_TRANSFER" "RAPYD" "RAZORPAY" "RETAILCARD" "REVOLUTPAY" "RTGS" "SAFETYPAY" "SAMSUNGPAY" "SBER" "SBERBANK_P2P" "SBERPAY" "SBP" "SBP_P2P" "SBP_TRANSFER" "SEPA" "SEPAP2P" "SHOPEEPAY" "SIRU_MOBILE" "SKRILL" "SLYSE" "SMILE_PAY" "SOFORT" "SPEI" "SPELL" "SPOYNT" "STRIPE" "SWIFT" "SWIPELUX" "TELE2" "TINK" "TODITO" "TPAGA" "TRANSFER_BCA" "TRUEMONEY" "TRUSTLY" "TRUSTPAYMENTS" "TUNZER" "UNIONPAYCARDS" "UPI" "UZCARD" "VIETQR" "VIETTELPAY" "VIRTUALACCOUNT" "VOLT" "VOUCHERS" "VOUCHSTAR" "WEBPAY" "WECHATWALLET" "YOUGANDA" "ZALO" "ZIRAAT" "MULTICA" "PAGO46" "SERVIFACIL" "VEPUY" "DIGITALWALLET" "MYBANK" "TPAY" "TWINT" "PAYPAY" "WIRE" "CARD" "QR" "BITEXPRO_INTERAC" "BITEXPRO_PAYID" "TRANSFIA" "TOUCHNGO" "DUITNOWQR" "MOMO" "MOMOB" "RARGCARD" "RARGBANKTRANSFER" "RARGWALLET" "REGPBANKTRANSFER" "REGPWALLET" "SMARTYPAY" "PSE" "PGWAY" "JETON" "GRABPAY" "ACHDIRECTDEBIT" "BACSDIRECTDEBIT" "CASHAPPPAY" "MOBILEPAY" "WECHATPAY" "WISE" "N26" "REVOLUT" "BIZUM" "UPIINTENT" "UPINEO" "NAGAD"

Payment Method

paymentMethodDetails
object ( PaymentMethodDetails )
customerAccountNumber
string <= 256 characters

Customer account Id in external system or masked card PAN

cardholderName
string <= 128 characters

Cardholder name (applicable for BASIC_CARD payment method only)

cardExpiryMonth
string = 2 characters

Card expiration month (applicable for BASIC_CARD payment method only)

cardExpiryYear
string = 4 characters

Card expiration year (applicable for BASIC_CARD payment method only)

cardBrand
string <= 16 characters

Card brand (applicable for BASIC_CARD payment method only)

cardIssuingCountry
string = 2 characters

Card Issuing Country (applicable for BASIC_CARD payment method only)

cardBank
string <= 128 characters

Card bank name (applicable for BASIC_CARD payment method only)

amount
number multiple of 1e-18 [ 1e-18 .. 999999.99 ]

Processing amount

currency
string < ISO 4217 code for FIAT currencies or cryptocurrency symbol >

Processing currency

customerAmount
number

Amount from payment request. Used only in case if the request currency differs from the currency sent to the payment provider.

customerCurrency
string < ISO 4217 code for FIAT currencies or cryptocurrency symbol >

Currency from payment request. Used only in case if it differs from the currency sent to the payment provider.

redirectUrl
string <= 256 characters

URL to redirect the customer

errorCode
string

Check 'Response Codes and Messages' section for details

externalResultCode
string

Result code recieved from external provider

externalRefs
object ( ExternalRefs )

This field serves as an identifier linking the system's records to corresponding records in the external provider's system.

orderId
string
customer
object ( CustomerS2S )
referenceId
string <= 128 characters

Id of the customer assigned by Merchant

citizenshipCountryCode
string = 2 characters

Customer country of citizenship

firstName
required
string <= 128 characters
lastName
required
string <= 128 characters
dateOfBirth
string <ISO 8601 (YYYY-MM-DD)> = 10 characters
email
required
string <email> <= 256 characters

Email address of the customer

phone
required
string <= 18 characters

International phone number of the customer, without the '+'. Use a space as a separator between the dialing country code and local phone number.

locale
string = 2 characters

Customer preferred display language (locale)

ip
string [ 8 .. 15 ] characters

IP address of the customer

routingGroup
string <= 64 characters

Identify the customer as belonging to a specific group that is used for routing. Learn more about Custom Payment Routing Fields.

kycStatus
boolean

Indicates whether the customer has passed KYC verification or not. Learn more about Custom Payment Routing Fields.

paymentInstrumentKycStatus
boolean

Indicates whether the payment instrument (usually the card number) has passed KYC verification Learn more about Custom Payment Routing Fields.

dateOfFirstDeposit
string <ISO 8601 (YYYY-MM-DD)>

Date of the first deposit from the customer. Learn more about Custom Payment Routing Fields.

depositsAmount
integer

How much the customer has deposited already, in the base currency. Learn more about Custom Payment Routing Fields.

withdrawalsAmount
integer

How much the customer has withdrawn already, in the base currency. Learn more about Custom Payment Routing Fields.

depositsCnt
integer

How many times the customer made a deposit. Learn more about Custom Payment Routing Fields.

withdrawalsCnt
integer

How many times the customer made a withdrawal. Learn more about Custom Payment Routing Fields.

trustLevel
string
Enum: "ftd" "redep"

Separates traffic into primary and secondary streams. Learn more about Custom Payment Routing Fields.

btag
Boolean
Enum: true false
affiliated
string <= 3 characters
Enum: "yes" "no"

The affiliated param allows custom routing configurations specifically tailored for affiliates. By setting this parameter, the system can adjust routes based on affiliate-specific rules, ensuring personalized user experiences, targeted payment providers or connectors. Learn more about Custom Payment Routing Fields.

billingAddress
object ( BillingAddress )

Customer's billing address

addressLine1
string <= 128 characters

Line 1 of the address (e.g., Number, street, etc)

addressLine2
string <= 128 characters

Line 2 of the address (e.g., Suite, apt)

city
string <= 50 characters

City name

countryCode
string = 2 characters [A-Z]{2}

2-character IS0-3166-1 country code

postalCode
string <= 20 characters

Postal code

state
string <= 40 characters

State code

startRecurring
boolean

Indicates whether this payment has started a recurring flow

recurringToken
string

Token that can be used to continue the recurring flow

terminalName
string

The name of the processing terminal OR payment solution that was used to process this transaction




{
  "id": "a0981ba1540d4062bc42d4019607sf94",
  "referenceId": "payment-123",
  "paymentType": "DEPOSIT",
  "state": "COMPLETED or PENDING",
  "description": "Funding the account",
  "parentPaymentId": "a0981ba1540d4062bc42d4019607sf94",
  "paymentMethod": "BASIC_CARD",
  "paymentMethodDetails": {
    "customerAccountNumber": "400000***0002",
    "cardholderName": "Harry Potter",
    "cardExpiryMonth": "07",
    "cardExpiryYear": "2028",
    "cardBrand": "VISA",
    "cardIssuingCountry": "PL",
    "cardBank": "INTL HDQTRS-CENTER OWNED"
  },
  "amount": 11.12,
  "currency": "EUR",
  "customerAmount": 15,
  "customerCurrency": "USD",
  "redirectUrl": "http://init/txid/a0981ba1540d4062bc42d4019607sf94",
  "errorCode": "1.01",
  "externalResultCode": "03",
  "externalRefs": {
    "orderId": 123456
  },
  "customer": {
    "referenceId": "VIP_customer_12345",
    "citizenshipCountryCode": "GB",
    "firstName": "Harry",
    "lastName": "Potter",
    "dateOfBirth": "1996-01-05",
    "email": "[email protected]",
    "phone": "357 123456789",
    "locale": "en",
    "ip": "172.16.0.1",
    "routingGroup": "VIP_Campaign",
    "kycStatus": true,
    "paymentInstrumentKycStatus": true,
    "dateOfFirstDeposit": "2021-02-23",
    "depositsAmount": 1000,
    "withdrawalsAmount": 250,
    "depositsCnt": 12,
    "withdrawalsCnt": 3,
    "trustLevel": "ftd",
    "btag": true,
    "affiliated": "yes"
  },
  "billingAddress": {
    "addressLine1": "211, Victory street",
    "addressLine2": "Office 7B",
    "city": "Hogwarts",
    "countryCode": "GB",
    "postalCode": "01001",
    "state": "CA"
  },
  "startRecurring": true,
  "recurringToken": "string",
  "terminalName": "string"
}