CentaPay Developer Documentation

Everything you need to integrate cross-border payment acceptance and disbursements for Central Asia.

What is CentaPay?#

CentaPay is an AIFC-incorporated, AFSA-regulated Money Services Provider built to connect international businesses and payment service providers with consumers in Central Asia. We provide the acquiring, processing, and settlement infrastructure — you integrate once and gain access to the full regional network as coverage expands.

All payment flows are cross-border by design. CentaPay does not serve domestic merchants or retail consumers. Our clients are international enterprises and licensed PSPs classified as Professional Clients under AFSA's conduct of business rules.

Coverage#

One integration today gives access to the full regional network as additional markets go live. No re-integration required.

Integration Model#

CentaPay uses a Server-to-Server (S2S) API only. Your server submits payment requests directly to our platform. Results are delivered both synchronously (JSON response) and asynchronously (callback to your webhook). Hosted Payment Pages (HPP) are available on request — contact info@centapay.com if HPP better suits your architecture.

How to Get Started#

Credentials & Environments#

Before you get an account, you must provide the following data to CentaPay:

You will receive the following credentials:

Protocol Mapping#

CentaPay maps specific protocol types to each merchant account. You cannot process payments until the relevant protocol has been mapped by CentaPay's operations team during onboarding. Confirm with your account manager before testing.

IP Whitelisting & Callbacks#

Requests from un-whitelisted IP addresses are rejected without a response. If you are testing from a development machine with a dynamic IP, use a tunnelling tool like ngrok for callbacks and let your account manager know your IPs need frequent updating during sandbox testing.

Authentication#

CentaPay uses MD5-based request signing. Every API request includes a hash parameter — a signature computed from specific request fields and your account password. There are no Bearer tokens or API key headers.

How It Works#

The hash is computed by reversing specific field values, concatenating them with your PASSWORD, converting to uppercase, then taking the MD5 digest. The exact formula varies by action — see the table below.

Formula Reference#

In all formulas below, strrev() means reverse the string, strtoupper() means convert to uppercase, and md5() means compute the MD5 hex digest.

Formula 1 — SALE, RETRY, RECURRING_SALE

md5(strtoupper(
  strrev(email)
  . PASSWORD
  . strrev(substr(card_number, 0, 6) . substr(card_number, -4))
))

function hashFormula1(string $email, string $password, string $cardNumber): string
{
    $cardPart = substr($cardNumber, 0, 6) . substr($cardNumber, -4);
    $raw = strrev($email) . $password . strrev($cardPart);
    return md5(strtoupper($raw));
}

import hashlib

def hash_formula_1(email: str, password: str, card_number: str) -> str:
    card_part = card_number[:6] + card_number[-4:]
    raw = email[::-1] + password + card_part[::-1]
    return hashlib.md5(raw.upper().encode()).hexdigest()

const crypto = require('crypto');

function hashFormula1(email, password, cardNumber) {
  const cardPart = cardNumber.slice(0, 6) + cardNumber.slice(-4);
  const raw = strrev(email) + password + strrev(cardPart);
  return crypto.createHash('md5').update(raw.toUpperCase()).digest('hex');
}

function strrev(s) { return s.split('').reverse().join(''); }

When card_token is provided instead of card data:

md5(strtoupper(
  strrev(email) . PASSWORD . strrev(card_token)
))

When digital_wallet is used (Apple Pay / Google Pay) — Formula 8:

md5(strtoupper(
  strrev(email) . PASSWORD
))

Formula 2 — CAPTURE, CREDITVOID, VOID, GET_TRANS_STATUS, Callback verification

md5(strtoupper(
  strrev(email)
  . PASSWORD
  . trans_id
  . strrev(substr(card_number, 0, 6) . substr(card_number, -4))
))

function hashFormula2(string $email, string $password, string $transId, string $cardNumber): string
{
    $cardPart = substr($cardNumber, 0, 6) . substr($cardNumber, -4);
    $raw = strrev($email) . $password . $transId . strrev($cardPart);
    return md5(strtoupper($raw));
}

// For callback verification, use the card mask from the callback
// (first 6 + last 4 digits visible in the masked PAN)

def hash_formula_2(email: str, password: str, trans_id: str, card_number: str) -> str:
    card_part = card_number[:6] + card_number[-4:]
    raw = email[::-1] + password + trans_id + card_part[::-1]
    return hashlib.md5(raw.upper().encode()).hexdigest()

function hashFormula2(email, password, transId, cardNumber) {
  const cardPart = cardNumber.slice(0, 6) + cardNumber.slice(-4);
  const raw = strrev(email) + password + transId + strrev(cardPart);
  return crypto.createHash('md5').update(raw.toUpperCase()).digest('hex');
}

Formula 3 — CREATE_SCHEDULE

md5(strtoupper(strrev(PASSWORD)))

Formula 4 — PAUSE / RUN / DELETE / SCHEDULE_INFO / DESCHEDULE

md5(strtoupper(strrev(schedule_id + PASSWORD)))

Formula 5 — CREDIT2CARD

md5(strtoupper(
  PASSWORD . strrev(substr(card_number, 0, 6) . substr(card_number, -4))
))

// With card_token instead:
md5(strtoupper(PASSWORD . strrev(card_token)))

Formula 6 — CREDIT2CARD callbacks & GET_TRANS_STATUS (for CREDIT2CARD)

md5(strtoupper(
  PASSWORD . trans_id . strrev(substr(card_number, 0, 6) . substr(card_number, -4))
))

Formula 7 — GET_TRANS_STATUS_BY_ORDER

md5(strtoupper(
  strrev(email) . PASSWORD . order_id
  . strrev(substr(card_number, 0, 6) . substr(card_number, -4))
))

Formula Quick Reference#

Quickstart#

Process your first card payment through CentaPay in under 30 minutes. This guide assumes you have received sandbox credentials from your account manager.

What You Need#

You also need to provide CentaPay with your server IP address(es) and a callback (webhook) URL. Ensure the S2S CARD protocol has been mapped to your account.

Your First SALE Request#

All requests are HTTPS POST to {PAYMENT_URL}/post. The body must be URL-encoded form data — not JSON.

curl -X POST https://{PAYMENT_URL}/post \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "action=SALE" \
  -d "client_key={CLIENT_KEY}" \
  -d "order_id=ORD-001" \
  -d "order_amount=5000" \
  -d "order_currency=KZT" \
  -d "order_description=Product+purchase" \
  -d "card_number=4111111111111111" \
  -d "card_exp_month=01" \
  -d "card_exp_year=2038" \
  -d "card_cvv2=000" \
  -d "payer_first_name=John" \
  -d "payer_last_name=Smith" \
  -d "payer_email=john@example.com" \
  -d "payer_phone=77001234567" \
  -d "payer_country=KZ" \
  -d "payer_city=Astana" \
  -d "payer_address=10+Kunayeva+St" \
  -d "payer_zip=010000" \
  -d "payer_ip=192.168.1.1" \
  -d "term_url_3ds=https://yoursite.com/3ds-return" \
  -d "hash={CALCULATED_HASH}"

<?php
function calcHash(string $email, string $password, string $cardNumber): string
{
    $cardPart = substr($cardNumber, 0, 6) . substr($cardNumber, -4);
    $raw = strrev($email) . $password . strrev($cardPart);
    return md5(strtoupper($raw));
}

$cardNumber = '4111111111111111';
$params = [
    'action'           => 'SALE',
    'client_key'       => CLIENT_KEY,
    'order_id'         => 'ORD-001',
    'order_amount'     => '5000',
    'order_currency'   => 'KZT',
    'order_description'=> 'Product purchase',
    'card_number'      => $cardNumber,
    'card_exp_month'   => '01',
    'card_exp_year'    => '2038',
    'card_cvv2'        => '000',
    'payer_first_name' => 'John',
    'payer_last_name'  => 'Smith',
    'payer_email'      => 'john@example.com',
    'payer_phone'      => '77001234567',
    'payer_country'    => 'KZ',
    'payer_city'       => 'Astana',
    'payer_address'    => '10 Kunayeva St',
    'payer_zip'        => '010000',
    'payer_ip'         => $_SERVER['REMOTE_ADDR'],
    'term_url_3ds'     => 'https://yoursite.com/3ds-return',
];
$params['hash'] = calcHash($params['payer_email'], PASSWORD, $cardNumber);

$ch = curl_init(PAYMENT_URL . '/post');
curl_setopt_array($ch, [
    CURLOPT_POST           => true,
    CURLOPT_POSTFIELDS     => http_build_query($params),
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_SSL_VERIFYPEER => true,
]);
$result = json_decode(curl_exec($ch), true);
curl_close($ch);

import requests, hashlib

def calc_hash(email: str, password: str, card_number: str) -> str:
    card_part = card_number[:6] + card_number[-4:]
    raw = email[::-1] + password + card_part[::-1]
    return hashlib.md5(raw.upper().encode()).hexdigest()

card_number = '4111111111111111'
params = {
    'action':            'SALE',
    'client_key':        CLIENT_KEY,
    'order_id':          'ORD-001',
    'order_amount':      '5000',
    'order_currency':    'KZT',
    'order_description': 'Product purchase',
    'card_number':       card_number,
    'card_exp_month':    '01',
    'card_exp_year':     '2038',
    'card_cvv2':         '000',
    'payer_first_name':  'John',
    'payer_last_name':   'Smith',
    'payer_email':       'john@example.com',
    'payer_phone':       '77001234567',
    'payer_country':     'KZ',
    'payer_city':        'Astana',
    'payer_address':     '10 Kunayeva St',
    'payer_zip':         '010000',
    'payer_ip':          '192.168.1.1',
    'term_url_3ds':      'https://yoursite.com/3ds-return',
}
params['hash'] = calc_hash(params['payer_email'], PASSWORD, card_number)

resp = requests.post(f'{PAYMENT_URL}/post', data=params)
result = resp.json()

const axios = require('axios');
const qs = require('qs');
const crypto = require('crypto');

const strrev = s => s.split('').reverse().join('');

function calcHash(email, password, cardNumber) {
  const cardPart = cardNumber.slice(0, 6) + cardNumber.slice(-4);
  const raw = strrev(email) + password + strrev(cardPart);
  return crypto.createHash('md5').update(raw.toUpperCase()).digest('hex');
}

const cardNumber = '4111111111111111';
const params = {
  action: 'SALE',
  client_key: CLIENT_KEY,
  order_id: 'ORD-001',
  order_amount: '5000',
  order_currency: 'KZT',
  order_description: 'Product purchase',
  card_number: cardNumber,
  card_exp_month: '01',
  card_exp_year: '2038',
  card_cvv2: '000',
  payer_first_name: 'John',
  payer_last_name: 'Smith',
  payer_email: 'john@example.com',
  payer_phone: '77001234567',
  payer_country: 'KZ',
  payer_city: 'Astana',
  payer_address: '10 Kunayeva St',
  payer_zip: '010000',
  payer_ip: req.ip,
  term_url_3ds: 'https://yoursite.com/3ds-return',
};
params.hash = calcHash(params.payer_email, PASSWORD, cardNumber);

const { data } = await axios.post(
  `${PAYMENT_URL}/post`,
  qs.stringify(params),
  { headers: { 'Content-Type': 'application/x-www-form-urlencoded' } }
);

Handling the Response#

Next Steps#

Cards#

CentaPay supports Visa, Mastercard, UZCARD, and HUMO for card-present-not-present (CNP) transactions across Kazakhstan and Uzbekistan.

SALE — Single Message (SMS)#

Authorise and capture in one step. This is the standard flow for immediate payments.

curl -X POST https://{PAYMENT_URL}/post \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "action=SALE" \
  -d "client_key={CLIENT_KEY}" \
  -d "order_id=ORD-001" \
  -d "order_amount=5000" \
  -d "order_currency=KZT" \
  -d "order_description=Product+purchase" \
  -d "card_number=4111111111111111" \
  -d "card_exp_month=01" \
  -d "card_exp_year=2038" \
  -d "card_cvv2=000" \
  -d "payer_first_name=John" \
  -d "payer_last_name=Smith" \
  -d "payer_email=john@example.com" \
  -d "payer_phone=77001234567" \
  -d "payer_country=KZ" \
  -d "payer_city=Astana" \
  -d "payer_address=10+Kunayeva+St" \
  -d "payer_zip=010000" \
  -d "payer_ip=192.168.1.1" \
  -d "term_url_3ds=https://yoursite.com/3ds-return" \
  -d "hash={HASH}"

$card = '4111111111111111';
$params = [
  'action'           => 'SALE',
  'client_key'       => CLIENT_KEY,
  'order_id'         => 'ORD-001',
  'order_amount'     => '5000',
  'order_currency'   => 'KZT',
  'order_description'=> 'Product purchase',
  'card_number'      => $card,
  'card_exp_month'   => '01',
  'card_exp_year'    => '2038',
  'card_cvv2'        => '000',
  'payer_first_name' => 'John',
  'payer_last_name'  => 'Smith',
  'payer_email'      => 'john@example.com',
  'payer_phone'      => '77001234567',
  'payer_country'    => 'KZ',
  'payer_city'       => 'Astana',
  'payer_address'    => '10 Kunayeva St',
  'payer_zip'        => '010000',
  'payer_ip'         => $_SERVER['REMOTE_ADDR'],
  'term_url_3ds'     => 'https://yoursite.com/3ds-return',
];
// Formula 1 hash
$cp = substr($card,0,6).substr($card,-4);
$params['hash'] = md5(strtoupper(
  strrev($params['payer_email']).PASSWORD.strrev($cp)
));
$ch = curl_init(PAYMENT_URL.'/post');
curl_setopt_array($ch,[
  CURLOPT_POST=>true,
  CURLOPT_POSTFIELDS=>http_build_query($params),
  CURLOPT_RETURNTRANSFER=>true,
]);
$result = json_decode(curl_exec($ch),true);

import requests, hashlib

card = '4111111111111111'
email = 'john@example.com'
cp = card[:6] + card[-4:]
h = hashlib.md5((email[::-1] + PASSWORD + cp[::-1]).upper().encode()).hexdigest()

resp = requests.post(f'{PAYMENT_URL}/post', data={
    'action': 'SALE',
    'client_key': CLIENT_KEY,
    'order_id': 'ORD-001',
    'order_amount': '5000',
    'order_currency': 'KZT',
    'order_description': 'Product purchase',
    'card_number': card,
    'card_exp_month': '01',
    'card_exp_year': '2038',
    'card_cvv2': '000',
    'payer_first_name': 'John',
    'payer_last_name': 'Smith',
    'payer_email': email,
    'payer_phone': '77001234567',
    'payer_country': 'KZ',
    'payer_city': 'Astana',
    'payer_address': '10 Kunayeva St',
    'payer_zip': '010000',
    'payer_ip': '192.168.1.1',
    'term_url_3ds': 'https://yoursite.com/3ds-return',
    'hash': h,
})

const crypto = require('crypto');
const axios = require('axios');
const qs = require('qs');
const rev = s => s.split('').reverse().join('');

const card = '4111111111111111';
const email = 'john@example.com';
const cp = card.slice(0,6) + card.slice(-4);
const hash = crypto.createHash('md5')
  .update((rev(email) + PASSWORD + rev(cp)).toUpperCase())
  .digest('hex');

const {data} = await axios.post(`${PAYMENT_URL}/post`,
  qs.stringify({
    action:'SALE', client_key:CLIENT_KEY,
    order_id:'ORD-001', order_amount:'5000',
    order_currency:'KZT', order_description:'Product purchase',
    card_number:card, card_exp_month:'01',
    card_exp_year:'2038', card_cvv2:'000',
    payer_first_name:'John', payer_last_name:'Smith',
    payer_email:email, payer_phone:'77001234567',
    payer_country:'KZ', payer_city:'Astana',
    payer_address:'10 Kunayeva St', payer_zip:'010000',
    payer_ip:req.ip,
    term_url_3ds:'https://yoursite.com/3ds-return',
    hash
  }));

Currencies#

AUTH & CAPTURE — Dual Message (DMS)#

Authorise only (hold funds), then capture separately. Add auth=Y to the SALE request. For AUTH, you can set order_amount to 0 for card validation / tokenisation only.

To capture, send a CAPTURE request with the trans_id from the AUTH response. Partial capture is supported (once only). See CAPTURE reference.

Tokenisation#

Request a card token on the first transaction by adding req_token=Y to the SALE request. The response and callback return a card_token you can store and reuse for future charges without transmitting card data again.

To charge using a stored token, send card_token instead of card_number, card_exp_month, card_exp_year, card_cvv2. The hash formula changes — use the card_token variant of Formula 1.

curl -X POST https://{PAYMENT_URL}/post \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "action=SALE" \
  -d "client_key={CLIENT_KEY}" \
  -d "order_id=ORD-AP-001" \
  -d "order_amount=99.99" \
  -d "order_currency=USD" \
  -d "order_description=Purchase" \
  -d "digital_wallet=applepay" \
  -d "payment_token={APPLE_PAY_TOKEN_JSON}" \
  -d "payer_first_name=Jane" \
  -d "payer_last_name=Doe" \
  -d "payer_email=jane@example.com" \
  -d "payer_phone=77001234567" \
  -d "payer_country=KZ" \
  -d "payer_city=Astana" \
  -d "payer_address=10+Kunayeva" \
  -d "payer_zip=010000" \
  -d "payer_ip=192.168.1.1" \
  -d "term_url_3ds=https://yoursite.com/return" \
  -d "hash={FORMULA_8_HASH}"

// Formula 8: md5(strtoupper(strrev(email) . PASSWORD))
$hash = md5(strtoupper(strrev($email) . PASSWORD));
$params = [
  'action' => 'SALE',
  'client_key' => CLIENT_KEY,
  'digital_wallet' => 'applepay',
  'payment_token' => $applePayTokenJson,
  // ... all payer fields ...
  'hash' => $hash,
];

// Build auto-submitting form from SALE response
$html = '<form id="3ds" method="'
  . $response['redirect_method']
  . '" action="' . $response['redirect_url'] . '">';

if (!empty($response['redirect_params'])
    && is_array($response['redirect_params'])) {
    foreach ($response['redirect_params'] as $k => $v) {
        $html .= '<input type="hidden" name="'
          . htmlspecialchars($k) . '" value="'
          . htmlspecialchars($v) . '">';
    }
}
$html .= '</form>';
$html .= '<script>document.getElementById("3ds").submit();</script>';
echo $html;

document.location = response.redirect_url;

"redirect_params": {
  "PaReq": "eJxVUt1...",
  "TermUrl": "https://..."
}

"redirect_params": [
  {"name": "PaReq", "value": "eJxVUt1..."},
  {"name": "TermUrl", "value": "https://..."}
]

Card Payouts (CREDIT2CARD)#

Push funds from your CentaPay settlement balance to a recipient's card. Used for merchant payouts, refunds to alternate cards, or disbursements to end-users.

Request Parameters#

Response#

Callback#

Callback hash uses Formula 6 (not Formula 2). This is the only action with a different callback hash formula.

Testing#

Use test card 4601541833776519 for successful CREDIT2CARD. Response: {action: CREDIT2CARD, result: SUCCESS, status: SETTLED}.

curl -X POST https://{PAYMENT_URL}/post \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "action=CREDIT2CARD" \
  -d "client_key={CLIENT_KEY}" \
  -d "order_id=PAY-001" \
  -d "order_amount=10000" \
  -d "order_currency=KZT" \
  -d "order_description=Merchant+payout" \
  -d "card_number=4601541833776519" \
  -d "hash={FORMULA_5_HASH}"

// Formula 5: md5(strtoupper(PASSWORD . strrev(first6+last4)))
$card = '4601541833776519';
$cp = substr($card,0,6).substr($card,-4);
$hash = md5(strtoupper(PASSWORD . strrev($cp)));
$params = [
  'action' => 'CREDIT2CARD',
  'client_key' => CLIENT_KEY,
  'order_id' => 'PAY-001',
  'order_amount' => '10000',
  'order_currency' => 'KZT',
  'order_description' => 'Merchant payout',
  'card_number' => $card,
  'hash' => $hash,
];

Virtual Account Payouts#

Direct Merchants#

International businesses integrating directly with CentaPay. Each direct merchant receives a dedicated MID, full transaction reporting, and settlement in their preferred currency.

Onboarding#

Settlement#

Settlement Cycle

CentaPay settles to clients on a T+1 (next business day) cycle. Transactions that reach SETTLED status before the daily cutoff are included in the next business day's settlement batch.

Transaction Status Lifecycle

How a transaction moves through the system toward settlement:

FX & Currency Conversion

When the transaction currency differs from your settlement currency, CentaPay applies a foreign exchange conversion. The applicable rate is included in callback parameters:

Settlement Reports

Settlement reports are available via the admin panel and include transaction-level detail for reconciliation against your callback records. Contact info@centapay.com for details on report format, delivery schedule, and available export options for your account.

Querying Settlement Status

Use GET_TRANS_STATUS or GET_TRANS_DETAILS to check whether a transaction has settled.

GET_TRANS_STATUS returns the current status field. A value of SETTLED confirms the transaction completed successfully and will be included in settlement.

GET_TRANS_DETAILS returns the full order history including an array of all sub-transactions (sale, 3ds, auth, capture, credit, chargeback, reversal, refund) with individual dates, statuses, and amounts.

PSPs & Platforms#

Licensed payment service providers adding Central Asian acquiring to their platform. CentaPay provides per-merchant MID visibility with aggregated settlement and sub-merchant reporting.

PayFac Model#

PSP clients operate under a Payment Facilitator (PayFac) or Merchant of Record (MOR) structure. CentaPay holds the acquiring relationship; you onboard and manage your sub-merchants under your account.

Sub-Merchants#

Use the channel_id parameter to route transactions to specific sub-merchants. This value is echoed in callbacks and available in reporting, enabling you to reconcile at sub-merchant level.

KYC Delegation#

PSP clients retain responsibility for KYC on their sub-merchants. CentaPay performs KYC on the PSP itself. Sub-merchant due diligence obligations are set out in your client agreement. See AML Obligations for details.

Settlement & Reporting#

PSP clients receive a single aggregated settlement per cycle covering all sub-merchant transactions.

Each transaction callback includes order_id (your reference), trans_id (CentaPay reference), and channel_id (if provided) for sub-merchant-level reconciliation.

Use GET_TRANS_DETAILS to retrieve the full history of any transaction, including payer details, masked card, and all status transitions.

For details on sub-merchant settlement breakdowns and report formats, contact info@centapay.com.

Refunds & Reversals (CREDITVOID)#

CREDITVOID handles both reversals (cancel an AUTH hold) and refunds (return settled funds). Full and partial refunds are supported. Multiple partial refunds are allowed.

Synchronous response returns result: ACCEPTED. Final result delivered via callback:

curl -X POST https://{PAYMENT_URL}/post \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "action=CREDITVOID" \
  -d "client_key={CLIENT_KEY}" \
  -d "trans_id={TRANS_ID}" \
  -d "amount=25.00" \
  -d "hash={FORMULA_2_HASH}"

// Formula 2: md5(strtoupper(strrev(email).PASSWORD.trans_id.strrev(first6+last4)))
$hash = md5(strtoupper(strrev($email).PASSWORD.$transId.strrev($cardPart)));
$params = [
  'action' => 'CREDITVOID',
  'client_key' => CLIENT_KEY,
  'trans_id' => $transId,
  'amount' => '25.00',
  'hash' => $hash,
];

Same-Day Void (VOID)#

Cancel a transaction performed the same financial day. Only allowed for SETTLED transactions from SALE, CAPTURE, or RECURRING_SALE operations. Unlike CREDITVOID, VOID does not process a refund — it cancels the transaction entirely.

Transaction Status (GET_TRANS_STATUS)#

Query the current status of a transaction. Use when a callback hasn't arrived or for reconciliation.

Response includes status (one of: 3DS, REDIRECT, PENDING, PREPARE, DECLINED, SETTLED, REVERSAL, REFUND, VOID, CHARGEBACK), plus decline_reason if declined, and recurring_token / schedule_id / digital_wallet if applicable, arn* if configured.

Transaction Details (GET_TRANS_DETAILS)#

Returns full order history including payer details, card mask, and an array of all transactions in the order.

Response includes: name, mail, ip, amount, currency, card (masked), decline_reason if declined, recurring_token, schedule_id, pan_type, digital_wallet, arn* if configured, and a transactions array with entries containing date, type (sale, 3ds, auth, capture, credit, chargeback, reversal, refund), status, and amount.

Status by Order ID (GET_TRANS_STATUS_BY_ORDER)#

Look up the most recent transaction status using your order_id instead of trans_id. Useful when trans_id is lost or for reconciliation.

Response: status (3DS/REDIRECT/PENDING/PREPARE/DECLINED/SETTLED/REVERSAL/REFUND/VOID/CHARGEBACK), decline_reason if declined, recurring_token, schedule_id, digital_wallet if applicable. With cascading enabled, returns most recent transaction only.

Chargebacks#

Chargebacks are initiated by the issuing bank, not by API request. CentaPay sends a callback notification when a chargeback occurs.

* Extended data fields - included only if configured in admin panel (Configuration → Protocol Mappings → "Add Extended Data to Callback").

Callback Delivery Rules#

CentaPay sends HTTP POST callbacks to your notification URL as transaction states change. Always use callbacks — not the synchronous response — as the authoritative result.

Content Type

Callbacks are sent as application/x-www-form-urlencoded.

Required Response

Your endpoint must return the plain string OK — nothing else. Any other content, HTML, or timeout is treated as a failure.

When Callbacks Are Sent

Callback Parameters by Action#

SALE Callback (Success)

SALE Callback (Declined)

CAPTURE Callback

CREDITVOID Callback

Success: action, result: SUCCESS, status (REFUND/REVERSAL/SETTLED), order_id, trans_id, creditvoid_date, amount, hash (Formula 2). Extended data fields* if configured.

Declined: action, result: DECLINED, order_id, trans_id, decline_reason, hash (Formula 2).

Undefined: result: UNDEFINED, status: SETTLED, order_id, trans_id, creditvoid_date, amount, hash (Formula 2).

VOID Callback

CREDIT2CARD Callback

Uses Formula 6 for hash (not Formula 2). This is the only action with a different callback hash formula.

* Extended data fields are included if configured in admin panel (Configuration → Protocol Mappings → "Add Extended Data to Callback").

Hash Verification#

Always verify the callback hash before processing. For most actions, use Formula 2. For CREDIT2CARD, use Formula 6. For VOID, see hash note under VOID Callback above (source references undefined "Void signature" - verify with Akurateco).

$data = $_POST;
// Use card from callback if present (SUCCESS), otherwise use stored mask (DECLINED)
$cardMask = isset($data['card']) ? $data['card'] : $storedCardMask;
$cardPart = substr($cardMask,0,6).substr($cardMask,-4);
$expected = md5(strtoupper(
  strrev($storedEmail) . PASSWORD . $data['trans_id'] . strrev($cardPart)
));
if (!hash_equals($expected, $data['hash'])) {
    http_response_code(400);
    exit('ERROR');
}
// Process based on result
if ($data['result'] === 'SUCCESS') {
    fulfillOrder($data['order_id'], $data['trans_id']);
}
echo 'OK';

import hashlib, hmac
data = request.form.to_dict()
# Use card from callback if present (SUCCESS), otherwise use stored mask (DECLINED)
card_mask = data.get('card', stored_card_mask)
card_part = card_mask[:6] + card_mask[-4:]
raw = stored_email[::-1] + PASSWORD + data['trans_id'] + card_part[::-1]
expected = hashlib.md5(raw.upper().encode()).hexdigest()
if not hmac.compare_digest(expected, data.get('hash','')):
    return 'ERROR', 400
if data['result'] == 'SUCCESS':
    fulfill_order(data['order_id'])
return 'OK'

const rev = s => s.split('').reverse().join('');
app.post('/webhook', express.urlencoded({extended:false}), (req,res) => {
  const d = req.body;
  // Use card from callback if present (SUCCESS), otherwise use stored mask (DECLINED)
  const cardMask = d.card || storedCardMask;
  const cp = cardMask.slice(0,6) + cardMask.slice(-4);
  const raw = rev(storedEmail) + PASSWORD + d.trans_id + rev(cp);
  const exp = crypto.createHash('md5').update(raw.toUpperCase()).digest('hex');
  if (!crypto.timingSafeEqual(Buffer.from(exp), Buffer.from(d.hash||'')))
    return res.status(400).send('ERROR');
  if (d.result === 'SUCCESS') fulfillOrder(d.order_id);
  res.send('OK');
});

Cascading Behaviour#

When cascading is enabled (auto-retry across MIDs on decline):

• General case: You receive only a callback for the last payment attempt with the final status.
• Particular case: If a redirect is required (e.g. 3DS), you also receive a callback for the first attempt with redirect data. The last-attempt callback includes only the final status.
• Intermediate attempts are not sent. The trans_id may differ between first and final callbacks. Do not assume you will receive a first-attempt callback.

Extended Callback Data#

Additional fields if configured in admin panel (Configuration → Protocol Mappings → "Add Extended Data to Callback"): connector_name, rrn, approval_code, gateway_id / extra_gateway_id, merchant_name / mid_name, issuer_country / issuer_bank, brand, arn, extended_data.

API Reference — CREDIT2CARD#

Test card: 4601541833776519.

API Reference — GET_TRANS_STATUS#

Response: status (3DS/REDIRECT/PENDING/PREPARE/DECLINED/SETTLED/REVERSAL/REFUND/VOID/CHARGEBACK), decline_reason, recurring_token, schedule_id, digital_wallet, arn* if configured.

API Reference — GET_TRANS_DETAILS#

Response includes: name, mail, ip, amount, currency, card (masked), decline_reason if declined, recurring_token, schedule_id, pan_type, digital_wallet, arn* if configured, transactions[] array (each with date, type, status, amount).

API Reference — GET_TRANS_STATUS_BY_ORDER#

Response: status (3DS/REDIRECT/PENDING/PREPARE/DECLINED/SETTLED/REVERSAL/REFUND/VOID/CHARGEBACK), decline_reason if declined, recurring_token, schedule_id, digital_wallet if applicable. With cascading enabled, returns most recent transaction only.

API Reference — CHARGEBACK#

Callback-only — not merchant-initiated. See Chargebacks for the full callback schema.

API Reference — RECURRING_SALE#

Response identical to SALE but action=RECURRING_SALE. Bypasses 3DS.

API Reference — RETRY#

Sync: result: ACCEPTED, order_id, trans_id. Only for soft declines.

Callback Parameters

Success: action: RETRY, result: SUCCESS, status: SETTLED, order_id, trans_id, amount, currency, hash (Formula 2).

Declined: action: RETRY, result: DECLINED, status: DECLINED, order_id, trans_id, amount, currency, decline_reason, hash (Formula 2).

API Reference — Schedule Operations#

All schedule actions use POST https://{PAYMENT_URL}/post.

CREATE_SCHEDULE

Response: schedule_id.

PAUSE_SCHEDULE

RUN_SCHEDULE

Same parameters as PAUSE_SCHEDULE with action=RUN_SCHEDULE. Resumes paused schedule.

DELETE_SCHEDULE

Same parameters with action=DELETE_SCHEDULE. Permanently removes schedule.

SCHEDULE_INFO

Same parameters with action=SCHEDULE_INFO. Returns: name, interval_length, interval_unit, day_of_month, payments_count, delays, paused (Y/N).

DESCHEDULE

Test Cards#

Use these test values in the sandbox environment. All transactions are processed by the test engine — no real funds are moved. Use any 3-digit CVV.

S2S CARD — Scenario Simulation

All scenarios use card number 4111111111111111. The expiry date determines the outcome:

CREDIT2CARD Test Card

Error & Decline Codes#

When a request fails validation, the synchronous response contains:

{
  "result": "ERROR",
  "error_message": "Description of the error",
  "error_code": 204002
}

Error Code Reference

Hash Calculator#

Generate test hashes during development. The PASSWORD is processed client-side only — do not use in production.

Formula 1 — SALE (card)

Formula 2 — CAPTURE / CREDITVOID / VOID / Callback

Formula 5 — CREDIT2CARD

Formula 8 — Digital Wallets (Apple Pay / Google Pay)

Request Builder#

Build a complete SALE request with auto-generated hash and cURL command. Enter your sandbox credentials and card details below.

Go-Live Checklist#

Complete these items before requesting production credentials.

Technical

If Using Recurring

If Using Payouts

If Using Digital Wallets

Compliance

Commercial

Contact info@centapay.com when all items are complete to begin the go-live process.

Eligibility#

CentaPay is an AFSA-regulated Money Services Provider operating within a strict compliance framework.

• All clients are international businesses or licensed payment service providers
• CentaPay does not provide services to retail consumers
• All payment flows are cross-border
• Domestic merchant acquiring within Kazakhstan or Uzbekistan is outside scope

Prohibited Categories#

Prohibited categories include: unlicensed financial services, gambling without appropriate licensing, adult content, weapons and controlled substances, and services subject to international sanctions.

Permitted Verticals

PCI DSS#

AML Obligations#

As a CentaPay client, you retain responsibility for:

• KYC on your end-users — Know Your Customer checks on the cardholders and recipients in your system
• Sanctions screening — Screen counterparties against applicable sanctions lists before submitting payment requests
• Suspicious transaction reporting — Report unusual patterns to CentaPay and your own regulatory authority where applicable
• Data accuracy — Submitting false payer data (names, addresses, IPs) constitutes a breach of your client agreement