API reference#

Credentials, hash formulas, every action and its parameters, callback parameters, error codes and PCI scope.

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).

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))
))

Void signature (VOID callbacks)

hash = md5(strtoupper(strrev(trans_id)) . PASSWORD)

Validates VOID callback hashes only - the VOID request itself signs with Formula 2. Unlike Formulas 1-8, the Void signature is a plain MD5 with no SHA1 wrapper.

Formula Quick Reference#

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").

API Reference — SALE#

* Optional if card_token or payment_token provided. ** Optional if payment_token provided.

Parameter precedence: If card_token and card data are both sent, card_token is ignored. If req_token and card_token are both sent, req_token is ignored. If payment_token and card data are both sent, payment_token is ignored. If card_token is specified, payment_token is ignored.

Response — Success

Response — 3DS Redirect

Response — Declined

Response — Undefined

API Reference — CAPTURE#

Response

SUCCESS → status: SETTLED. DECLINED → status: PENDING + decline_reason. UNDEFINED → status: PENDING.

All responses include: action, result, status, order_id, trans_id, trans_date, descriptor, amount, currency.

API Reference — CREDITVOID#

Response

Synchronous: result: ACCEPTED. Callback: SUCCESS with status: REFUND/REVERSAL (full) or SETTLED (partial). DECLINED includes decline_reason.

API Reference — VOID#

Response

Same-day only. Applies to SALE, CAPTURE, RECURRING_SALE in SETTLED status.

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

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.

PCI DSS#

Compliance#