Common Utilities

Server Callbacks

Whitelark sends server-to-server HTTP GET callbacks to notify merchants of transaction results. Callbacks are triggered when a transaction reaches a final or intermediate state (approved, declined, error, or unknown).

Note

Callbacks are guaranteed to be delivered. If the merchant’s server does not respond with HTTP 200 OK, Whitelark retries the callback up to 30 times over 14 days using a progressive schedule. Merchants must implement idempotency checks (verify status, type, orderid, and client_orderid) to prevent processing duplicate callbacks.

Callback URL

A callback URL is a plain URL to the merchant’s endpoint without parameters. Whitelark appends the callback parameters automatically as query string values in the GET request.

Example endpoint: https://www.merchant.example.com/callback.php

Note

Allowed ports: HTTP – 80, 8080. HTTPS – 443, 8443.

In addition to server_callback_url, merchants can use the notify_url parameter to receive notifications for every status change during the transaction lifecycle (e.g., refund, chargeback).

Callback Authentication

The control parameter is a SHA-1 hash that verifies the callback originates from Whitelark. The merchant’s callback handler must validate this parameter on every callback.

The control parameter is a SHA-1 hash of the following values concatenated in order:

status
orderid
merchant_order
merchant_control_key

Example input:

approved123invoice-1AF4B5DE6-3468-424C-A922-C1DAD7CB4509

Resulting control value:

5bc8ee48f9ba37c0fd1e0b052a9bc105c6df87e1

Callback Parameters

Parameter	Description
status	Transaction status. See Status List.
merchant_order	Merchant order identifier (same as client_orderid).
client_orderid	Merchant order identifier.
orderid	Whitelark transaction ID (same as paynet-order-id in Status response).
type	Transaction type: payment, reversal, chargeback, etc.
amount	Actual transaction amount. May change during the transaction flow.
currency	Transaction currency.
descriptor	Payment descriptor of the processing gate.
original-gate-descriptor	Descriptor configured at the gate level.
error_code	Error code (if status is declined/error/filtered).
error_message	Error message (if status is declined/error/filtered).
name	Cardholder name.
email	Customer email.
first-name	Customer first name.
last-name	Customer last name.
phone	Customer phone number.
approval-code	Bank authorization approval code.
last-four-digits	Last four digits of the card number.
bin	Bank BIN of the card.
card-type	Card brand (VISA, MASTERCARD, etc.).
card-exp-month	Card expiration month.
card-exp-year	Card expiration year.
card-hash-id	Unique card hash identifier (stable across transactions).
card-country-alpha-three-code	Three-letter country code of the source card issuer.
bank-name	Issuing bank name.
gate-partial-reversal	Whether partial refund is supported (enabled/disabled).
processor-rrn	Bank Retrieval Reference Number.
processor-tx-id	Acquirer transaction identifier.
processor-credit-rrn	Retrieval Reference Number for credit (refund) transactions.
processor-credit-arn	Acquirer reference number for credit (refund) transactions.
processor-debit-arn	Acquirer reference number for debit card.
reason-code	Reason code for chargeback or fraud operations.
comment	Comment (for refund transactions).
serial-number	Serial number of the request.
verified-3d-status	3DS verification result (AUTHENTICATED if approved by 3DS).
eci	Electronic Commerce Indicator (Visa).
control	SHA-1 checksum for callback authentication.
merchantdata	Custom data passed by the merchant in the initial request.
initial-amount	Original transaction amount (without fees or commissions).
exchange-rate	Base exchange rate for currency conversion.
effective-exchange-rate	Actual exchange rate applied during conversion.
transaction-date	Date and time of the transaction’s final status.
ips-src-payment-product-code	Card product code (Visa/Mastercard).
ips-src-payment-product-name	Card product name (Visa/Mastercard).
ips-src-payment-type-code	Card type code (Visa/Mastercard).
ips-src-payment-type-name	Card type name (Visa/Mastercard).
destination-card-country-alpha-three-code	Three-letter country code of the destination card issuer.
country *	Customer’s country (two-letter code). See Country Codes.
state *	Customer’s state. See Country Codes. Required for USA, Canada, Australia.
city *	Customer’s city.
zip_code *	Customer’s ZIP code.
address1 *	Customer’s address line 1.
BIC*	Bank Identification Code.
IBAN*	International Bank Account Number.
additional-status*	Open banking status: authorised (verified) or not_authorised (not verified).

Note

Parameters marked with * are not included by default. Contact technical support to enable them in callbacks.

Callback to Status Parameters Mapping

The following table maps callback parameter names to their corresponding Order Status response field names.

Callback Parameter	Status Response Parameter
status	status
merchant_order	merchant-order-id
client_orderid	merchant-order-id
orderid	paynet-order-id
type	transaction-type
amount	amount
descriptor	descriptor
original-gate-descriptor	original-gate-descriptor
error_code	error-code
error_message	error-message
name	name
email	email
first-name	first-name
last-name	last-name
phone	phone
approval-code	approval-code
last-four-digits	last-four-digits
bin	bin
card-type	card-type
card-exp-month	card-exp-month
card-exp-year	card-exp-year
gate-partial-reversal	gate-partial-reversal
gate-partial-capture	gate-partial-capture
processor-rrn	processor-rrn
processor-tx-id	processor-tx-id
reason-code	reason-code
comment	comment
serial-number	serial-number
merchantdata	merchantdata
initial-amount	initial-amount
card-country-alpha-three-code	card-country-alpha-three-code
destination-card-country-alpha-three-code	destination-card-country-alpha-three-code
country	country
state	state
city	city
zip_code	zip_code
address1	address1
bank-name	bank-name
dest-bin	dest-bin
dest-card-type	dest-card-type
dest-last-four-digits	dest-last-four-digits
dest-bank-name	dest-bank-name
purpose	purpose
exchange-rate	exchange-rate
effective-exchange-rate	effective-exchange-rate

Get Balance

Retrieve the current available balance for a merchant account. Useful for monitoring account funding and automated balance checks.

Request URL

Note

For integration purposes always use the sandbox environment instead of production.

POST https://gate.whitelark.io/paynet/api/v2/get-balance/endpointid

Request Parameters

Note

Response has Content-Type: text/html;charset=utf-8. All parameters are x-www-form-urlencoded with 0x0A at the end of each value.

Parameter	Length/Type	Necessity	Description
login	String	Mandatory	Merchant login name.
control	40/String	Mandatory	SHA-1 hash of: login + merchant_control.
currency	3/String	Optional	Three-letter ISO currency code. If omitted, balances for all currencies are returned.

Response Parameters

Note

When currency is omitted, the response contains multiple amount/currency pairs. When a single currency is requested, exactly one pair is returned (or none if not available).

Parameter	Description
amount	Available balance amount. Repeated per currency when no currency filter is applied.
currency	Currency code. Repeated per currency when no currency filter is applied.

Response Example

amount=29.99 currency=USD

Card Payment API

Any other questions? Get in touch