1. Getting Started

Whitelark is a payment gateway solution that provides a full range of processing services compliant with PCI DSS. The platform enables merchants and managers to process online payments securely and efficiently.

1.1 System Participants

White Labels (Platform Operators) – Companies that offer online payment processing services to merchants under their own brand, powered by the Whitelark platform.

Merchants – Businesses that sell goods or services online. A merchant contracts with a White Label to accept payments from customers.

Acquirer – A financial institution that processes transactions and settles funds into the White Label's accounts. Exposes a Payment Gateway Interface (PGI) that Whitelark connects to for transaction processing.

1.2 Key System Objects

Gateway – A software system component responsible for interaction with the PGI of Acquirer. Whitelark accepts a Merchant’s incoming transaction and forwards it to the PGI of an Acquirer for the actual charge-off.

MID – A virtual merchant account at Acquirer.

Routing rule – Set at the Merchant level, defines rules by which transactions are distributed to Gateways.

Endpoint – An entry point for incoming Merchant’s transactions and the only Whitelark object exposed via API.

1.3 Environments

Whitelark provides two environments:

Environment	Domain	Comments

Environment	Domain	Comments
Production	https://gate.whitelark.io	Live processing
Sandbox	https://sandbox.whitelark.io	Customer integration & testing
Staging	https://wlpg.io	Testing environment

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

2. Transaction Types Overview

A transaction represents a financial operation between accounts processed through the Whitelark payment gateway.

The platform supports the full lifecycle of card payment transactions – from initial authorization through settlement, as well as refunds, chargebacks, and payouts. For example, when a customer enters their card details and clicks Pay in a merchant's online store, the merchant initiates a Payment transaction. Whitelark processes the request and routes it to the appropriate Acquirer for authorization and settlement. If the customer later requests a refund, the merchant can initiate a Refund, and the funds are transferred back to the cardholder's account.

Transaction	Description

Transaction	Description
Payment	A single-step transaction that combines authorization and capture. See Payment Transactions.
Refund	Returns the specified amount – full or partial – to the cardholder's account. See Refund Transactions.
Chargeback	Initiated by the cardholder's issuing bank when the cardholder disputes a charge. Results in funds being returned to the cardholder pending resolution.
Payout	Transfers funds from the merchant's account to a customer's bank account or digital wallet. See Payout Transactions.

3. Card Payment API

The Whitelark Card Payment API provides a comprehensive set of transaction types for online payment processing. All API calls are initiated through HTTPS POST requests.

3.1 Card-Not-Present

This section covers transactions initiated without the physical card being present, typical for online/e-commerce payments.

1.1 Payment Transactions

Note: The API endpoint uses sale in the URL path. In Back Office and throughout this documentation, these transactions are referred to as Payments.

1.1.1 Direct Integration

Payment Request URLs

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

POST https://gate.whitelark.io/paynet/api/v2/sale/endpointid

Payment Request Authentication

The control parameter authenticates the request origin. It is a SHA-1 hash of the following values concatenated in order:

endpointid
client_orderid
amount in minor currency units (e.g., 0.94 USD → 94, 10.15 USD → 1015)
email
merchant_control

Example

Input string:

59I6email@client.com3E8E45B5-2-42D8-6ECC-FBF6B11B1

Resulting control value:

d02e67236575a8e02dea5e094f3c8f12f0db43d7

Payment Request Flow

Merchant uses a single entry point and a single API call for all Payment transactions. Whether 3DS authentication is required is determined server-side by Whitelark – the Merchant does not know in advance. The integration logic follows one unified flow with a single branching point:

Checkout – Customer proceeds to payment on the Merchant’s website.
Send Payment Request – Merchant sends an HTTPS POST to the Payment endpoint with the parameters described in Payment Request Parameters. Include redirect_url – this is the URL the Customer will be redirected to after a 3DS transaction is processed. redirect_url is not used if the transaction goes through the non-3DS process.
Receive Order ID – Whitelark immediately returns a response with paynet-order-id and status=processing.
Poll for Status – Merchant shows a processing message to the customer and starts polling the Order Status API using the paynet-order-id.
Branch: Check html Parameter – Whitelark determines whether 3DS is required and returns the status response. The Merchant inspects the html parameter in the response:
1. If html is empty (Non-3DS): Continue polling. Whitelark processes the transaction with the Acquirer asynchronously and returns the final status (approved or declined) through the Order Status API.
2. If html is not empty (3DS):
  1. URL-decode the html parameter and render the Issuer Bank’s authentication form in the customer’s browser.
  2. Customer completes 3DS verification (typically by entering an SMS code sent by their issuing bank).
  3. Upon successful authentication, Whitelark forwards the Payment request to the Acquirer for processing.
  4. Whitelark redirects the customer’s browser back to the redirect_url provided in step 2, with orderid and status (approved/declined) as POST parameters.
Process Result – Merchant receives the final transaction status either through the redirect, Order Status polling, or server_callback_url and presents the result to the customer.

Tip: Your integration code should handle both branches with a simple check: if the html parameter in the status response is non-empty, initiate the 3DS flow; otherwise, keep polling for the final status. This is the only difference between the two paths.

Payment Request Parameters

Note: Request must have content-type=application/x-www-form-urlencoded. Leading and trailing whitespace in input parameters will be omitted. The following characters must be escaped in parameter values: & + ".

Parameter	Length/Type	Necessity	Description
client_orderid	128/String	Mandatory	Merchant order identifier.
amount	10/Numeric	Mandatory	Amount to be charged. Specified in the highest units with . delimiter. For instance, 10.5 for USD means 10 US Dollars and 50 Cents.
currency	3/String	Mandatory	Currency the transaction is charged in (three-letter ISO code). E.g., USD, EUR.
address1	50/String	Mandatory	Customer’s address line 1.
city	50/String	Mandatory	Customer’s city.
zip_code	10/String	Mandatory	Customer’s ZIP code.
country	2/String	Mandatory	Customer’s country (two-letter ISO code). See Country Codes.
phone	15/String	Mandatory	Customer’s full international phone number, including country code.
email	50/String	Mandatory	Customer’s email address.
ipaddress	45/String	Mandatory	Customer’s IP address, included for fraud screening purposes.
control	40/String	Mandatory	SHA-1 checksum. See Request authorization through control parameter.
cvv2	3-4/Numeric	Mandatory	Customer’s CVV2 code. Three- or four-digit number in the signature area of the card.
credit_card_number	20/Numeric	Mandatory	Customer’s credit card number. Send combination of credit_card_number + card_printed_name + expire_month + expire_year.
card_printed_name	128/String	Mandatory	Card printed name.
expire_month	2/Numeric	Mandatory	Credit card expiration month.
expire_year	4/Numeric	Mandatory	Credit card expiration year.
first_name	50/String	Conditional	Customer’s first name. Depends on Acquirer’s requirements.
last_name	50/String	Conditional	Customer’s last name. Depends on Acquirer’s requirements.
redirect_url	1024/String	Conditional	URL the cardholder will be redirected to upon completion. Cardholder is redirected regardless of approval or decline. Do not use this to retrieve results — use server_callback_url instead. Mandatory if both redirect_success_url and redirect_fail_url are missing.
redirect_success_url	1024/String	Conditional	URL for redirect only on approved transactions. Mandatory if redirect_url is missing.
redirect_fail_url	1024/String	Conditional	URL for redirect only on declined or filtered transactions. Mandatory if redirect_url is missing.
state	2-3/String	Optional	Customer’s state. See Country Codes. Mandatory for USA, Canada, Australia.
order_desc	64k/String	Optional	Brief order description.
ssn	32/Numeric	Optional	Last four digits of the customer’s social security number.
birthday	8/Numeric	Optional	Customer’s date of birth, format YYYYMMDD.
cell_phone	15/String	Optional	Customer’s full international cell phone number.
site_url	128/String	Optional	URL the original Payment is made from.
purpose	128/String	Optional	Destination to where the payment goes (e.g., account top-up). Used by fraud monitoring.
server_callback_url	1024/String	Optional	URL the transaction result will be sent to (server-to-server).
merchant_data	64k/String	Optional	Any additional information (e.g., VIP customer). Returned in Status response and Callback.

Additional Fields: 3DS Authentication Results (Acquirers)

Acquirers can fill 3DS results for each transaction if 3DS authentication is performed on their side.

Parameter	Description
tds_authentication_result_type	Type of result. Possible value: SIMPLE.
tds_authentication_result_authentication_type	Authentication type (01=Static, 02=Dynamic, 03=OOB, 04=Decoupled).
tds_authentication_result_authentication_value	Payment System-specific authentication value. Base64-encoded 20-byte value (28-byte result).
tds_authentication_result_transaction_id	xid for 1.0.2 or dsTransID for 2.1.0/2.2.0.
tds_authentication_result_transaction_status	Y=Authenticated, N=Not Authenticated, U=Could Not Be Performed, A=Attempts Processing, C=Challenge Required, D=Decoupled, R=Rejected.
tds_authentication_result_message_version	Protocol version: 1.0.2, 2.1.0, or 2.2.0.

Payment Request Example (with Cardholder Data)

credit_card_number=4538977399606732
&card_printed_name=CARD HOLDER
&expire_month=12&expire_year=2099&cvv2=123
&client_orderid=902B4FF5
&order_desc=Test Order Description
&first_name=John&last_name=Smith
&ssn=1267&birthday=19820115
&address1=100 Main st&city=Seattle&state=WA
&zip_code=98102&country=US
&phone=%2B12063582043&email=john.smith@gmail.com
&currency=USD&amount=10.42
&ipaddress=65.153.12.232&site_url=www.google.com
&purpose=user_account1
&redirect_url=https://doc.whitelark.io/doc/dummy.htm
&server_callback_url=https://httpstat.us/200
&merchant_data=VIP customer
&control=768eb8162fc361a3e14150ec46e9a6dd8fbfa483

Payment Response

Note: Response has Content-Type: text/html;charset=utf-8 header. All fields are x-www-form-urlencoded, with 0x0A character at the end of each parameter’s value.

Parameter	Description
type	The type of response. May be async-response, validation-error, error. If validation-error or error, error-message and error-code contain details.
paynet-order-id	Order ID assigned to the order by Whitelark.
merchant-order-id	Merchant order ID.
serial-number	Unique number assigned by Whitelark server to this particular request.
error-message	If status is error, contains the reason for decline or error details.
error-code	The error code in case of error status.
end-point-id	Endpoint ID used for the transaction.

Payment Response Example

type=async-response
&serial-number=00000000-0000-0000-0000-0000000624e8
&merchant-order-id=59e1e3ca-5d44-11e1-b3d6-002522b853b4
&paynet-order-id=94935
&end-point-id=223

3DS Redirect

Upon completion of 3DS authorization, the customer is automatically redirected to redirect_url. The redirection is performed as an HTTPS POST request with the following parameters:

Parameter	Description
status	See Status List for details.
orderid	Order ID assigned by Whitelark.
merchant_order	Merchant order ID.
client_orderid	Merchant order ID.
error_message	If declined or error, contains the reason for decline.
control	SHA-1 checksum of: status + orderid + client_orderid + merchant-control.
descriptor	Gate descriptor.

Server Callback

Upon transaction completion, Whitelark sends a GET request to the server_callback_url with the parameters described in Server Callbacks.

Server Callback Authentication

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

status
orderid
client_orderid
merchant_control

Example

Input string:

approvedS279G323P4T1209294c258d6536ababe653E8E45B5-7682-42D8-6ECC-FB794F6B11B1

Resulting control value:

e04bd50531f45f9fc76917ac78a82f3efaf0049c

Server Callback Example

status=declined
&error-message=Decline, refer to card issuer
&error-code=107
&paynet-order-id=S279G323P4T1209294
&merchant-order-id=c258d6536ababe65

Order Status

After any type of transaction is sent to Whitelark and an order ID is returned, Merchant should poll for transaction status. When the transaction is processed, Whitelark returns the status back to Merchant.

Status URL

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

POST https://gate.whitelark.io/paynet/api/v2/status/endpointid

Status Request Authentication

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

login
client_orderid
orderid
merchant_control

Example:

Parameter	Value

Parameter	Value
login	`cool_merchant`
client_orderid	`5624444333322221111110`
orderid	`9625`
merchant_control

API documentation

1. Getting Started

1.1 System Participants

1.2 Key System Objects

1.3 Environments

2. Transaction Types Overview

3. Card Payment API

3.1 Card-Not-Present

1.1 Payment Transactions

1.1.1 Direct Integration