API Documentation

Table of Content

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.

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.
order_desc	64k/String	Mandatory	Brief order description.
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	Conditional	Customer’s credit card number. Send combination of credit_card_number + card_printed_name + expire_month + expire_year.
card_printed_name	128/String	Conditional	Card printed name.
expire_month	2/Numeric	Conditional	Credit card expiration month.
expire_year	4/Numeric	Conditional	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.
state	2-3/String	Conditional	Customer’s state. See Country Codes. Mandatory for USA, Canada, Australia.
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.
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.
dapi_imei	32/String	Optional	Unique device identifier.

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

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

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

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

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

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

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
login	`cool_merchant`
client_orderid	`5624444333322221111110`
orderid	`9625`
merchant_control	`r45a019070772d1c4c2b503bbdc0fa22`

Input string:

cool_merchant56244443333222211111109625r45a019070772d1c4c2b503bbdc0fa22

Resulting control value:

c52cfb609f20a3677eb280cc4709278ea8f7024c

Order Status Call Parameters

Note

Request must have content-type=application/x-www-form-urlencoded.

Parameter	Length/Type	Necessity	Description
login	String	Mandatory	Merchant login name.
client_orderid	String	Mandatory	Merchant order identifier of the transaction for which status is requested.
orderid	String	Conditional	Order ID assigned by Whitelark.
by-request-sn	String	Optional	Serial number assigned to a specific request by Whitelark. Include to get status for a particular transaction stage.
control	40/String	Mandatory	SHA-1 checksum of: login + client_orderid + orderid + merchant_control.

Note

In most cases, include both client_orderid and orderid. client_orderid alone can be used if it is unique and orderid was not received.

Order Status Response

Note

Response has Content-Type: text/html;charset=utf-8 header. All parameters are x-www-form-urlencoded. Parameters marked with * are not defined by default – contact tech support to enable.

Parameter	Description
type	The type of response. May be status-response.
status	See Status List for details.
amount	Actual transaction amount (may change during transaction flow).
paynet-order-id	Order ID assigned by Whitelark.
merchant-order-id	Merchant order ID.
phone	Customer phone.
html	HTML code of 3DS authorization form, encoded in application/x-www-form-urlencoded MIME format. Merchant must decode this parameter before showing the form to the Customer.
redirect-to	For 3DS authorization the merchant can redirect the customer to URL provided in this parameter instead of rendering the page provided in `html` parameter. The `redirect-to` parameter is returned only if the `html` parameter is returned. Merchant should use GET HTTP method to redirect. Required for 3DS 2.0.
serial-number	Unique number assigned by Whitelark to this request.
last-four-digits	Last four digits of customer’s card number.
bin	Bank BIN of customer’s card number.
masked_pan	Masked PAN in 6+4 format.
card-type	Card type (VISA, MASTERCARD, etc.).
gate-partial-reversal	Whether gate supports partial refunds (enabled/disabled).
transaction-type	Transaction type (payment, payout, refund).
processor-rrn	Bank Receiver Registration Number.
processor-tx-id	Acquirer transaction identifier.
receipt-id	Link to electronic receipt.
name	Name.
cardholder-name	Cardholder name.
card-exp-month	Card expiration month.
card-exp-year	Card expiration year.
card-hash-id	Unique card identifier for loyalty programs or fraud checks.
card-country-alpha-three-code	Three-letter country code of card issuer.
email	Customer email.
first-name	Customer’s first name.
last-name	Customer’s last name.
country *	Customer’s country (two-letter country code).
state *	Customer’s country (two-letter country code). Mandatory for USA, Canada and Australia.
city *	Customer’s city.
zip_code *	Customer’s ZIP code.
address1 *	Customer’s address line 1.
purpose	Destination to where the payment goes. It is useful for the merchants who let their clients to transfer money from a credit card to some type of client’s account, e.g. game or mobile phone account.
bank-name	Bank name by customer card BIN.
paynet-processing-date	Acquirer transaction processing date.
approval-code	Bank approval code.
order-stage	Current stage of transaction processing.
descriptor	Bank identifier of the payment recipient.
original-gate-descriptor	Descriptor, which is set on gate level in the system.
error-message	Reason for decline (if declined/error/filtered).
error-code	Error code (if declined/error/filtered).
ips-src-payment-product-code	Code for card set by multinational financial service. (Visa/Mastercard).
ips-src-payment-product-name	Decrypted code for card set by multinational financial service. (Visa/Mastercard).
ips-src-payment-type-code	Type of card code set by multinational financial service. (Visa/Mastercard).
ips-src-payment-type-name	Decrypted code for type of card set by multinational financial service. (Visa/Mastercard).
merchantdata	merchant_data value from the initial request.
initial-amount	Original amount without fees or commissions (immutable).
BIC*	Bank Identification Code.
IBAN*	International Bank Account Number.
additional-status*	Appears when "open banking" method was used. Includes two values: "not_authorised" transaction was not verified, "authorised" transaction was verified.

Order Status Response Example

type=status-response
&serial-number=00000000-0000-0000-0000-0000005b5044
&merchant-order-id=902B4FF5
&processor-tx-id=PNTEST-159884
&paynet-order-id=159884
&status=approved
&amount=10.42
&descriptor=test-usd
&original-gate-descriptor=test 12345678 3Ds Bank
&gate-partial-reversal=enabled
&gate-partial-capture=enabled
&transaction-type=sale
&receipt-id=a5061379-6ff5-3565-a9ba-1b8a814d04f6
&name=TEST HOLDER
&cardholder-name=TEST HOLDER
&card-exp-month=1
&card-exp-year=2016
&email=john.smith@gmail.com
&last-name=Smith
&first-name=John
&processor-rrn=510321889824
&approval-code=242805
&order-stage=sale_approved
&last-four-digits=9001
&bin=520306
&masked_pan=111100******0008
&card-type=MASTERCARD
&phone=12063582043
&bank-name=CITIBANK
&paynet-processing-date=2015-04-09 17:14:26 MSK
&by-request-sn=00000000-0000-0000-0000-0000005b2a8a
&card-hash-id=1493114
&card-country-alpha-three-code=RUS
&verified-3d-status=AUTHENTICATED
&eci=02
&ips-src-payment-product-code=SAP
&ips-src-payment-product-name=SAP—Platinum Mastercard® Salary– Immediate Debit
&ips-src-payment-type-code=Debit
&ips-src-payment-type-name=MASTERCARD Debit
&merchantdata=promo
&initial-amount=10.42
&transaction-date=2023-01-10+12%3A46%3A28+MSK
&BIC=HBUKAT4B
&IBAN=AT483200000012345864
&additional-status=authorised

type=status-response
&serial-number=00000000-0000-0000-0000-0000005b5044
&merchant-order-id=902B4FF5
&processor-tx-id=PNTEST-159884
&paynet-order-id=159884
&status=approved
&amount=10.42
&descriptor=test-usd
&original-gate-descriptor=test 12345678 3Ds Bank
&gate-partial-reversal=enabled
&gate-partial-capture=enabled
&transaction-type=sale
&receipt-id=a5061379-6ff5-3565-a9ba-1b8a814d04f6
&name=TEST HOLDER
&cardholder-name=TEST HOLDER
&card-exp-month=1
&card-exp-year=2016
&email=john.smith@gmail.com
&last-name=Smith
&first-name=John
&processor-rrn=510321889824
&approval-code=242805
&order-stage=sale_approved
&last-four-digits=9001
&bin=520306
&masked_pan=111100******0008
&card-type=MASTERCARD
&phone=12063582043
&bank-name=CITIBANK
&paynet-processing-date=2015-04-09 17:14:26 MSK
&by-request-sn=00000000-0000-0000-0000-0000005b2a8a
&card-hash-id=1493114
&card-country-alpha-three-code=RUS
&verified-3d-status=AUTHENTICATED
&eci=02
&ips-src-payment-product-code=SAP
&ips-src-payment-product-name=SAP—Platinum Mastercard® Salary– Immediate Debit
&ips-src-payment-type-code=Debit
&ips-src-payment-type-name=MASTERCARD Debit
&merchantdata=promo
&initial-amount=10.42
&transaction-date=2023-01-10+12%3A46%3A28+MSK
&BIC=HBUKAT4B
&IBAN=AT483200000012345864
&additional-status=authorised

type=status-response
&serial-number=00000000-0000-0000-0000-0000005b5044
&merchant-order-id=902B4FF5
&processor-tx-id=PNTEST-159884
&paynet-order-id=159884
&status=approved
&amount=10.42
&descriptor=test-usd
&original-gate-descriptor=test 12345678 3Ds Bank
&gate-partial-reversal=enabled
&gate-partial-capture=enabled
&transaction-type=sale
&receipt-id=a5061379-6ff5-3565-a9ba-1b8a814d04f6
&name=TEST HOLDER
&cardholder-name=TEST HOLDER
&card-exp-month=1
&card-exp-year=2016
&email=john.smith@gmail.com
&last-name=Smith
&first-name=John
&processor-rrn=510321889824
&approval-code=242805
&order-stage=sale_approved
&last-four-digits=9001
&bin=520306
&masked_pan=111100******0008
&card-type=MASTERCARD
&phone=12063582043
&bank-name=CITIBANK
&paynet-processing-date=2015-04-09 17:14:26 MSK
&by-request-sn=00000000-0000-0000-0000-0000005b2a8a
&card-hash-id=1493114
&card-country-alpha-three-code=RUS
&verified-3d-status=AUTHENTICATED
&eci=02
&ips-src-payment-product-code=SAP
&ips-src-payment-product-name=SAP—Platinum Mastercard® Salary– Immediate Debit
&ips-src-payment-type-code=Debit
&ips-src-payment-type-name=MASTERCARD Debit
&merchantdata=promo
&initial-amount=10.42
&transaction-date=2023-01-10+12%3A46%3A28+MSK
&BIC=HBUKAT4B
&IBAN=AT483200000012345864
&additional-status=authorised

Order Status Postman Collection

--data-urlencode 'login=login' \
--data-urlencode 'client_orderid=552644' \
--data-urlencode 'orderid=1401648389' \
--data-urlencode 'control=76b66026b7dbff04a073baf962a612c413482b1b'

--data-urlencode 'login=login' \
--data-urlencode 'client_orderid=552644' \
--data-urlencode 'orderid=1401648389' \
--data-urlencode 'control=76b66026b7dbff04a073baf962a612c413482b1b'

--data-urlencode 'login=login' \
--data-urlencode 'client_orderid=552644' \
--data-urlencode 'orderid=1401648389' \
--data-urlencode 'control=76b66026b7dbff04a073baf962a612c413482b1b'

1.1.2 Payment Form Integration

Payment Form integration is for merchants who are not able to accept customer card details directly (i.e., merchant’s website has not completed PCI DSS certification). In this case, Whitelark handles all card data collection.

Supported Payment Methods coming soon

Whitelark Payment Form may display one or more of the following payment methods, depending on merchant configuration and customer device:

Card
Apple Pay
Google Pay
Click to Pay

No additional request parameters are required to enable Apple Pay, Google Pay, or Click to Pay. These payment methods are enabled and managed via Whitelark merchant configuration.

Note

Merchants do not need to integrate Apple Pay, Google Pay, or Click to Pay separately. These payment methods are handled entirely within the Whitelark-hosted Payment Form.

Payment Form URL

Note

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

POST https://gate.whitelark.io/paynet/api/v3/sale-form/endpointid

Payment Form Request Authentication

Uses the same control parameter calculation as the Payment request.

Payment Form Flow

Customer proceeds to checkout on the merchant website.
Merchant sends an HTTPS POST to the Payment Form endpoint with the parameters described in Payment Form Parameters.
Whitelark gateway returns a response containing a redirect-url parameter. This URL specifies where the merchant must redirect the customer’s browser.
Merchant sends an HTTP 302 redirect to the customer’s browser using the URL provided in the redirect-url response parameter.
Customer fills in payment details and submits the Payment Form.
Whitelark gateway processes the transaction (3D Secure or non-3D Secure flow).
After authorization is completed, Whitelark gateway redirects the customer’s browser to the redirect_url parameter provided by the merchant in the original request.

Payment Form Request Parameters

Note

Request must have content-type=application/x-www-form-urlencoded. Acquirer can redefine the necessity of some fields. Leading and trailing whitespace in input parameters is automatically trimmed.

Parameter	Length/Type	Necessity	Description
client_orderid	128/String	Mandatory	Merchant order identifier.
order_desc	64k/String	Mandatory	Brief order description.
amount	10/Numeric	Mandatory	Amount to be charged (highest units with . delimiter).
currency	3/String	Mandatory	Three-letter ISO currency code.
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	Two-letter ISO country code.
email	50/String	Mandatory	Customer’s email address.
ipaddress	45/String	Mandatory	Customer’s IP address (fraud screening).
control	40/String	Mandatory	SHA-1 checksum.
first_name	50/String	Conditional	Customer’s first name.
last_name	50/String	Conditional	Customer’s last name.
state	2/String	Conditional	Customer’s state. Mandatory for USA, Canada, Australia.
redirect_url	1024/String	Conditional	Redirect URL upon completion. Mandatory if `redirect_success_url` and `redirect_fail_url` are missing.
redirect_success_url	1024/String	Conditional	Redirect URL on approval only.
redirect_fail_url	1024/String	Conditional	Redirect URL on decline/filter only.
server_callback_url	1024/String	Optional	Server-to-server callback URL.
merchant_data	64k/String	Optional	Additional merchant information.
merchant_form_data	128/String	Optional	Custom parameters parsed into form macros (URL-encoded key=value pairs).
phone	15/String	Optional	Customer’s full international phone number.
ssn	4 / 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 mobile phone number in international format, including country code.
purpose	128 / String	Optional	Destination of funds (e.g., game account, mobile top-up). Used by fraud monitoring.
site_url	128 / String	Optional	URL of the merchant's website where the payment is initiated.

Payment Form Request Example

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
&amount=10.42
&email=john.smith@gmail.com
&currency=USD
&ipaddress=65.153.12.232
&site_url=https://www.google.com
&purpose=user_account1
&redirect_url=https://doc.example.com/doc/dummy.htm
&server_callback_url=https://httpstat.us/200
&merchant_data=VIP+customer
&control=768eb8162fc361a3e14150ec46e9a6dd8fbfa483

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
&amount=10.42
&email=john.smith@gmail.com
&currency=USD
&ipaddress=65.153.12.232
&site_url=https://www.google.com
&purpose=user_account1
&redirect_url=https://doc.example.com/doc/dummy.htm
&server_callback_url=https://httpstat.us/200
&merchant_data=VIP+customer
&control=768eb8162fc361a3e14150ec46e9a6dd8fbfa483

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
&amount=10.42
&email=john.smith@gmail.com
&currency=USD
&ipaddress=65.153.12.232
&site_url=https://www.google.com
&purpose=user_account1
&redirect_url=https://doc.example.com/doc/dummy.htm
&server_callback_url=https://httpstat.us/200
&merchant_data=VIP+customer
&control=768eb8162fc361a3e14150ec46e9a6dd8fbfa483

Payment Form Response Parameters

Note

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

Parameter Name	Description
type	Response type. Possible values: `async-form-response`, `validation-error`, `error`. If the value is `validation-error` or `error`, the `error-message` and `error-code` parameters contain additional error details
paynet-order-id	Order ID assigned by the Whitelark
merchant-order-id	Merchant order ID
serial-number	Unique number assigned by the Whitelark server to this specific merchant request
error-message	Reason for decline or detailed error description (returned for declined or error responses)
error-code	Error code (returned for declined or error responses)
redirect-url	URL to which the merchant must redirect the customer’s browser. Merchant should send HTTP 302 redirect.

Payment Form Final Redirect

Upon completion of the Payment Form process, the customer is automatically redirected to the merchant's redirect_url via an HTTPS POST request with the following parameters:

Parameter Name	Description
status	Current status of the transaction.
orderid	Order ID assigned by Whitelark.
merchant_order	Merchant order ID.
error_message	Reason for decline or detailed error description (returned for declined or error statuses).
control	Checksum used to verify that the request was initiated by Whitelark. Calculated as a SHA-1 hash of the concatenated values:`status + orderid + client_orderid + merchant-control`.
descriptor	Gateway descriptor.
processor-tx-id	Acquirer transaction identifier.
amount	Final transaction amount.
bin	Bank Identification Number (BIN) of the customer’s card.
type	Response type.
card-type	Card type (VISA, MASTERCARD, etc.).
phone	Customer phone number.
last-four-digits	Last four digits of the customer’s card.
card-holder-name	Cardholder name.
error_code	Gateway error code.

Payment Form Postman Collection

--data-urlencode 'client_orderid=pstmn504818' \
--data-urlencode 'order_desc=Test Order Description' \
--data-urlencode 'first_name=John' \
--data-urlencode 'last_name=Smith' \
--data-urlencode 'ssn=1267' \
--data-urlencode 'birthday=19820115' \
--data-urlencode 'address1=100 Main st' \
--data-urlencode 'city=Seattle' \
--data-urlencode 'state=WA' \
--data-urlencode 'zip_code=98102' \
--data-urlencode 'country=KZ' \
--data-urlencode 'phone=+12063582043' \
--data-urlencode 'cell_phone=+19023384543' \
--data-urlencode 'amount=1.01' \
--data-urlencode 'email=john.smith@gmail.com' \
--data-urlencode 'currency=USD' \
--data-urlencode 'ipaddress=65.153.12.232' \
--data-urlencode 'site_url=www.google.com' \
--data-urlencode 'purpose=user_account1' \
--data-urlencode 'redirect_url=https://fyst.com' \
--data-urlencode 'redirect_success_url=https://httpstat.us/200' \
--data-urlencode 'redirect_fail_url=https://httpstat.us/400' \
--data-urlencode 'server_callback_url=https://webhook.site/7183c250-a6ec-40d8-ab29-b92d6a399a60' \
--data-urlencode 'merchant_data=VIP customer' \
--data-urlencode 'merchant_form_data=testparam:test1' \
--data-urlencode 'control='

--data-urlencode 'client_orderid=pstmn504818' \
--data-urlencode 'order_desc=Test Order Description' \
--data-urlencode 'first_name=John' \
--data-urlencode 'last_name=Smith' \
--data-urlencode 'ssn=1267' \
--data-urlencode 'birthday=19820115' \
--data-urlencode 'address1=100 Main st' \
--data-urlencode 'city=Seattle' \
--data-urlencode 'state=WA' \
--data-urlencode 'zip_code=98102' \
--data-urlencode 'country=KZ' \
--data-urlencode 'phone=+12063582043' \
--data-urlencode 'cell_phone=+19023384543' \
--data-urlencode 'amount=1.01' \
--data-urlencode 'email=john.smith@gmail.com' \
--data-urlencode 'currency=USD' \
--data-urlencode 'ipaddress=65.153.12.232' \
--data-urlencode 'site_url=www.google.com' \
--data-urlencode 'purpose=user_account1' \
--data-urlencode 'redirect_url=https://fyst.com' \
--data-urlencode 'redirect_success_url=https://httpstat.us/200' \
--data-urlencode 'redirect_fail_url=https://httpstat.us/400' \
--data-urlencode 'server_callback_url=https://webhook.site/7183c250-a6ec-40d8-ab29-b92d6a399a60' \
--data-urlencode 'merchant_data=VIP customer' \
--data-urlencode 'merchant_form_data=testparam:test1' \
--data-urlencode 'control='

--data-urlencode 'client_orderid=pstmn504818' \
--data-urlencode 'order_desc=Test Order Description' \
--data-urlencode 'first_name=John' \
--data-urlencode 'last_name=Smith' \
--data-urlencode 'ssn=1267' \
--data-urlencode 'birthday=19820115' \
--data-urlencode 'address1=100 Main st' \
--data-urlencode 'city=Seattle' \
--data-urlencode 'state=WA' \
--data-urlencode 'zip_code=98102' \
--data-urlencode 'country=KZ' \
--data-urlencode 'phone=+12063582043' \
--data-urlencode 'cell_phone=+19023384543' \
--data-urlencode 'amount=1.01' \
--data-urlencode 'email=john.smith@gmail.com' \
--data-urlencode 'currency=USD' \
--data-urlencode 'ipaddress=65.153.12.232' \
--data-urlencode 'site_url=www.google.com' \
--data-urlencode 'purpose=user_account1' \
--data-urlencode 'redirect_url=https://fyst.com' \
--data-urlencode 'redirect_success_url=https://httpstat.us/200' \
--data-urlencode 'redirect_fail_url=https://httpstat.us/400' \
--data-urlencode 'server_callback_url=https://webhook.site/7183c250-a6ec-40d8-ab29-b92d6a399a60' \
--data-urlencode 'merchant_data=VIP customer' \
--data-urlencode 'merchant_form_data=testparam:test1' \
--data-urlencode 'control='

1.2 Refund Transactions

Note

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

Refund reverses a previously approved Payment transaction and returns funds to the cardholder. Both full and partial refunds are supported, depending on acquirer capabilities. The refund amount cannot exceed the original transaction amount.

Refund URL

Note

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

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

Refund Request Authentication

The control parameter has two variants depending on whether amount and currency are specified.

With amount and currency (partial refund):

SHA-1 hash of the following values concatenated in order:

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

Example input:

logic902B4FF5159884500EURB17F59B4-A7DC-41B4-8FF9-37D986B43D20

Resulting control value:

f9fcfd80c03a9ad9d813f67f11095512be4feffb

Without amount and currency (full refund):

SHA-1 hash of:

endpointid
login
client_orderid
orderid
merchant_control

Example input:

logic902B4FF5159884B17F59B4-A7DC-41B4-8FF9-37D986B43D20

Resulting control value:

6ef9cae82e765a7f43d4b596f8186cf20962e349

Refund Flow

Send Refund Request – Merchant sends an HTTPS POST to the Refund endpoint with the parameters described below.
Receive Order ID – Whitelark returns a response with paynet-order-id. Merchant starts polling the Order Status API.
Processing – Whitelark forwards the refund request to the acquirer.
Final Status – The acquirer responds with approve or decline. Whitelark returns the final status through the Order Status API.

Refund Request Parameters

Note

Note: Request must have content-type=application/x-www-form-urlencoded. The following characters must be escaped in parameter values: & + ".

Parameter	Length/Type	Necessity	Description
login	20/String	Mandatory	Merchant login name.
orderid	20/String	Mandatory	Unique identifier of the original Payment order assigned by Whitelark (returned as `paynet-order-id` in the Payment response).
client_orderid	128/String	Mandatory	Unique merchant identifier of the original Payment transaction.
amount	10/Numeric	Conditional	Refund amount in highest units with . delimiter (e.g., 10.50 for $10.50). If omitted, the full original amount is refunded. Amount cannot exceed the initial transaction amount. Must be accompanied by currency. Partial refunds depend on acquirer support.
currency	3/String	Conditional	Three-letter ISO currency code for the amount. Required if amount is specified.
control	128/String	Mandatory	SHA-1 checksum. See Refund Request Authentication below.
comment	50/String	Mandatory	Reason for the refund.

Refund Response

Note

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

Parameter	Description
type	Response type: async-response, validation-error, or error.
paynet-order-id	Order ID assigned by Whitelark.
merchant-order-id	Merchant order ID.
serial-number	Unique number assigned by Whitelark to this request.
end-point-id	Endpoint used for processing.
error-message	Error details (if status is error).
error-code	Error code (if status is error).

Refund Response Example

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

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

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

Refund Request Status

Use the same Order Status API as described in Payment Transactions. The refund status response includes additional parameters:

Parameter	Description
total-reversal-amount	Total amount of all processed refunds for this transaction.
reversal-amount	Amount of the last processed refund.
processor-credit-rrn	Retrieval Reference Number for the credit (refund) transaction.
processor-credit-arn	Acquirer card reference number for the credit (refund) transaction.
processor-debit-arn	Acquirer card reference number for the debit transaction.

Refund Request Postman Collection

--data-urlencode 'login=login' \
--data-urlencode 'orderid=1401522379' \
--data-urlencode 'client_orderid=347850' \
--data-urlencode 'comment=testrefund' \
--data-urlencode 'control=76b66026b7dbff04a073baf962a612c413482b1b'

--data-urlencode 'login=login' \
--data-urlencode 'orderid=1401522379' \
--data-urlencode 'client_orderid=347850' \
--data-urlencode 'comment=testrefund' \
--data-urlencode 'control=76b66026b7dbff04a073baf962a612c413482b1b'

--data-urlencode 'login=login' \
--data-urlencode 'orderid=1401522379' \
--data-urlencode 'client_orderid=347850' \
--data-urlencode 'comment=testrefund' \
--data-urlencode 'control=76b66026b7dbff04a073baf962a612c413482b1b'

3.2 Payouts

Payout enables merchants to disburse funds to customers via multiple methods: bank cards, bank accounts, e-wallets, and crypto wallets. Common use cases include withdrawals, refunds to alternative payment methods, salary disbursements, and account funding.

Request URL

Note

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

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

Payout Request Authentication (OAuth 1.0a)

Payout requests use OAuth 1.0a authorization with HMAC-SHA1 signature. oAuth libraries may be helpful to speed up the integration process.

HMAC Key

Concatenation of consumer secret (Merchant control key) + & + token secret (empty string):

F9F65098-1111-1111-1111-621611111111&

Signing Process

Arrange request body parameters in lexicographical order.
Generate a unique random nonce and current timestamp.
Include OAuth parameters in the request body: oauth_consumer_key, oauth_nonce, oauth_signature_method, oauth_timestamp, oauth_version.
Build the signature base string: POST&{percent-encoded URL}&{percent-encoded parameters}.
Compute HMAC-SHA1, Base64-encode and percent-encode the result.

Note

Merchant login is used as oauth_consumer_key but is NOT part of the HMAC signing key.

Authorization Header Example

Authorization: OAuth realm="",
  oauth_version="1.0",
  oauth_signature_method="HMAC-SHA1",
  oauth_consumer_key="merchantlogin",
  oauth_timestamp="1513785920",
  oauth_nonce="EqINVv5rkhx",
  oauth_signature="9bSeUoR5yJSSJ4KPhotT%2BofEHSQ%3D"

Authorization: OAuth realm="",
  oauth_version="1.0",
  oauth_signature_method="HMAC-SHA1",
  oauth_consumer_key="merchantlogin",
  oauth_timestamp="1513785920",
  oauth_nonce="EqINVv5rkhx",
  oauth_signature="9bSeUoR5yJSSJ4KPhotT%2BofEHSQ%3D"

Authorization: OAuth realm="",
  oauth_version="1.0",
  oauth_signature_method="HMAC-SHA1",
  oauth_consumer_key="merchantlogin",
  oauth_timestamp="1513785920",
  oauth_nonce="EqINVv5rkhx",
  oauth_signature="9bSeUoR5yJSSJ4KPhotT%2BofEHSQ%3D"

Payout Flow

Send Payout Request – Merchant sends an HTTPS POST to the Payout endpoint with the parameters described below.
Receive Order ID – Whitelark returns a response with paynet-order-id.
Processing – Whitelark forwards the payout to the acquirer.
Poll for Status – Merchant polls the Order Status API. Whitelark returns the final status (approved/declined) once the acquirer responds.

Payout Request Parameters

Note

Request must have content-type=application/x-www-form-urlencoded and Authorization headers (OAuth 1.0a). Contact your Support Manager to confirm if Conditional fields are Mandatory for your integration.

Core Parameters

Parameter	Length/Type	Necessity	Description
client_orderid	128/String	Mandatory	Merchant order identifier.
amount	10/Numeric	Mandatory	Amount in highest units with . delimiter (e.g., 10.50 for $10.50).
currency	3/String	Mandatory	Three-letter ISO currency code (e.g., USD, EUR).
order_desc	64/String	Optional	Brief order description.
ipaddress	7-45/String	Conditional	Customer’s IP address (IPv4 or IPv6). Used for fraud screening.
purpose	128/String	Optional	Payout purpose description.
server_callback_url	1024/String	Optional	Server-to-server callback URL.
redirect_url	1024/String	Conditional	Redirect URL upon completion. Mandatory if `redirect_success_url` and `redirect_fail_url` are missing. Used in payout-form integration.
redirect_success_url	1024/String	Conditional	Redirect URL on approval only.
redirect_fail_url	1024/String	Conditional	Redirect URL on decline/filter only.
merchant_data	64k/String	Optional	Additional merchant information. Returned in Status and Callback.

Card Destination Parameters

Parameter	Length/Type	Necessity	Description
credit_card_number	20/Numeric	Conditional	Destination card number. Processing limits are applied to this card.
card_printed_name	128/String	Conditional	Cardholder’s full name as printed on the card.
expire_month	2/Numeric	Conditional	Card expiration month.
expire_year	4/Numeric	Conditional	Card expiration year.

Bank Account Destination Parameters

Parameter	Length/Type	Necessity	Description
account_number	24/String	Conditional	Bank account number.
account_name	128/String	Optional	Bank account name.
bank_name	255/String	Conditional	Bank name.
bank_branch	255/String	Conditional	Bank branch name.
bank_code	32/String	Conditional	Bank code.
bank_bic	128/String	Conditional	BIC of the recipient’s bank.
bank_city	128/String	Conditional	Bank city.
bank_address1	255/String	Conditional	Bank address.
bank_zip_code	255/String	Conditional	Bank postal code.
bank_province	255/String	Conditional	Bank province.
bank_area	255/String	Conditional	Bank area.
routing_number	16/String	Conditional	Routing number (used in specific regions, e.g., China).

E-Wallet Destination Parameters

Parameter	Length/Type	Necessity	Description
ewallet_type	64/String	Conditional	Type of e-wallet.
ewallet_wallet	128/String	Conditional	E-wallet ID.

Receiver Information

Parameter	Length/Type	Necessity	Description
receiver_first_name	128/String	Conditional	Receiver first name (alias: first_name).
receiver_last_name	128/String	Conditional	Receiver last name (alias: last_name).
receiver_birthday	30/Numeric	Conditional	Receiver birthday (alias: birthday).
receiver_country_code	3/String	Conditional	Receiver country code (alias: country).
receiver_state	4/String	Conditional	Receiver state. Required for USA, Canada, Australia (alias: state).
receiver_city	128/String	Conditional	Receiver city (alias: city).
receiver_zip_code	32/Numeric	Conditional	Receiver postal code (alias: zip_code).
receiver_address1	256/String	Conditional	Receiver address (alias: address1).
receiver_phone	128/Numeric	Conditional	Receiver phone (alias: phone).
receiver_email	128/String	Conditional	Receiver email (alias: email).
receiver_inn	128/String	Conditional	Recipient’s INN (tax ID).
receiver_identity_document_id	128/String	Conditional	Identity document type (alias: identity_document_id).
receiver_identity_document_number	128/String	Conditional	Identity document number (alias: identity_document_number).
legal_person_name	128/String	Conditional	Name on legal document.
legal_person_document_number	128/String	Conditional	Legal document number.

Payout Request Example

account_number=1234567890
&amount=100
&bank_branch=test
&bank_name=test
&client_orderid=12345
&currency=USD
&oauth_consumer_key=payout_test
&oauth_nonce=EqINVv5rkhx
&oauth_signature_method=HMAC-SHA1
&oauth_timestamp=1513785920
&oauth_version=1.0
&routing_number=123456

account_number=1234567890
&amount=100
&bank_branch=test
&bank_name=test
&client_orderid=12345
&currency=USD
&oauth_consumer_key=payout_test
&oauth_nonce=EqINVv5rkhx
&oauth_signature_method=HMAC-SHA1
&oauth_timestamp=1513785920
&oauth_version=1.0
&routing_number=123456

account_number=1234567890
&amount=100
&bank_branch=test
&bank_name=test
&client_orderid=12345
&currency=USD
&oauth_consumer_key=payout_test
&oauth_nonce=EqINVv5rkhx
&oauth_signature_method=HMAC-SHA1
&oauth_timestamp=1513785920
&oauth_version=1.0
&routing_number=123456

Payout Response

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	Description
type	Response type: async-response, validation-error, or error.
paynet-order-id	Order ID assigned by Whitelark.
merchant-order-id	Merchant order ID.
serial-number	Unique number assigned by Whitelark to this request.
error-message	Error details (if status is error).
error-code	Error code (if status is error).

Payout Response Example

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

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

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

Payout Order Status

Use the same Order Status API as described in Payment Transactions. Poll using the paynet-order-id returned in the Payout response.

Server Callback

Upon transaction completion, Whitelark sends a GET request to the server_callback_url. See Callback Authentication in the Payment Transactions section for the control parameter calculation.

Payout Request Postman Collection

--data-urlencode 'amount=60.00' \
--data-urlencode 'currency=USD' \
--data-urlencode 'ipaddress=4.4.4.4' \
--data-urlencode 'redirect_url=http://www.example.com' \
--data-urlencode 'client_orderid=pstmn705288' \
--data-urlencode 'control=ba3d6b0c1ce75b30f852cc8d6d7464a4c6219340' \
--data-urlencode 'redirect_success_url=https://httpstat.us/200' \
--data-urlencode 'redirect_fail_url=https://httpstat.us/400'

--data-urlencode 'amount=60.00' \
--data-urlencode 'currency=USD' \
--data-urlencode 'ipaddress=4.4.4.4' \
--data-urlencode 'redirect_url=http://www.example.com' \
--data-urlencode 'client_orderid=pstmn705288' \
--data-urlencode 'control=ba3d6b0c1ce75b30f852cc8d6d7464a4c6219340' \
--data-urlencode 'redirect_success_url=https://httpstat.us/200' \
--data-urlencode 'redirect_fail_url=https://httpstat.us/400'

--data-urlencode 'amount=60.00' \
--data-urlencode 'currency=USD' \
--data-urlencode 'ipaddress=4.4.4.4' \
--data-urlencode 'redirect_url=http://www.example.com' \
--data-urlencode 'client_orderid=pstmn705288' \
--data-urlencode 'control=ba3d6b0c1ce75b30f852cc8d6d7464a4c6219340' \
--data-urlencode 'redirect_success_url=https://httpstat.us/200' \
--data-urlencode 'redirect_fail_url=https://httpstat.us/400'

3.3 Google Pay / Apple Pay

Google Pay and Apple Pay are digital wallet payment methods that allow customers to pay using tokenized card credentials stored on their devices. Instead of collecting card details directly, the merchant receives an encrypted or decrypted payment data payload from the wallet provider and passes it to Whitelark via the Payment API.

Integration Overview

Wallet transactions use the same Payment endpoint and flow described in Payment Transactions. The only difference is that card fields (credit_card_number, expire_month, expire_year, cvv2) are replaced by two wallet-specific parameters:

Parameter	Length/Type	Necessity	Description
payment_data	String	Conditional	Payment data received from Google Pay or Apple Pay. Must be JSON-stringified and Base64-encoded.
payment_data_type	String	Conditional	Specifies the format of payment_data. Possible values: googlepay_encrypted, googlepay_decrypted, applepay_encrypted, applepay_decrypted.

Note

The payment_data_type value must match the actual data format. If the data and the specified type do not match, Whitelark cannot process the payload correctly and the transaction will be rejected.

Note

For encrypted payment data (googlepay_encrypted, applepay_encrypted), the merchant must provide their decryption keys or certificates to Whitelark technical support for endpoint configuration. Without these, Whitelark cannot decrypt the payment data.

Preparing the payment_data Field

Regardless of wallet provider or encryption mode, the preparation follows three steps:

Obtain the payload – Receive the payment data object from the wallet SDK (decrypted by the merchant, or raw encrypted).
JSON-stringify – Convert the object to a JSON string with no extra whitespace.
Base64-encode – Encode the resulting string to Base64. This value becomes the payment_data parameter.

Example: googlepay_decrypted

After the merchant decrypts the Google Pay payload, the data looks like:

{
  "messageExpiration": "1758537951177",
  "messageId": "AH2Ejtdw...",
  "paymentMethod": "CARD",
  "paymentMethodDetails": {
    "expirationYear": 2027,
    "expirationMonth": 12,
    "pan": "4111111111111111",
    "authMethod": "PAN_ONLY"
  }
}

{
  "messageExpiration": "1758537951177",
  "messageId": "AH2Ejtdw...",
  "paymentMethod": "CARD",
  "paymentMethodDetails": {
    "expirationYear": 2027,
    "expirationMonth": 12,
    "pan": "4111111111111111",
    "authMethod": "PAN_ONLY"
  }
}

{
  "messageExpiration": "1758537951177",
  "messageId": "AH2Ejtdw...",
  "paymentMethod": "CARD",
  "paymentMethodDetails": {
    "expirationYear": 2027,
    "expirationMonth": 12,
    "pan": "4111111111111111",
    "authMethod": "PAN_ONLY"
  }
}

JSON-stringify and Base64-encode this object, then include it in the Payment request:

&payment_data=eyJtZXNzYWdl...
&payment_data_type=googlepay_decrypted

&payment_data=eyJtZXNzYWdl...
&payment_data_type=googlepay_decrypted

&payment_data=eyJtZXNzYWdl...
&payment_data_type=googlepay_decrypted

Example: googlepay_encrypted

The merchant receives the raw encrypted payload from Google Pay containing signature, intermediateSigningKey, protocolVersion, and signedMessage fields. JSON-stringify and Base64-encode the entire object:

&payment_data=eyJzaWduYXR1cmUi...
&payment_data_type=googlepay_encrypted

&payment_data=eyJzaWduYXR1cmUi...
&payment_data_type=googlepay_encrypted

&payment_data=eyJzaWduYXR1cmUi...
&payment_data_type=googlepay_encrypted

Apple Pay

Apple Pay transactions follow the same preparation steps. Use applepay_encrypted or applepay_decrypted as the payment_data_type value, depending on whether the merchant or Whitelark performs the decryption.

Complete Request Structure

The Wallet Payment request includes all standard Payment parameters (client_orderid, amount, currency, customer data, browser info, control, etc.) with card fields replaced by the wallet parameters:

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

client_orderid=ORDER123
&amount=25.00
&currency=USD
&first_name=John
&last_name=Doe
&email=john@example.com
&ipaddress=203.0.113.1
&address1=123 Main St
&city=New York
&state=NY
&zip_code=10001
&country=US
&site_url=https://merchant.example.com
&redirect_url=https://merchant.example.com/return
&server_callback_url=https://merchant.example.com/callback
&control=a1b2c3d4...
&payment_data=eyJzaWduYXR1cmUi...
&payment_data_type=googlepay_encrypted

client_orderid=ORDER123
&amount=25.00
&currency=USD
&first_name=John
&last_name=Doe
&email=john@example.com
&ipaddress=203.0.113.1
&address1=123 Main St
&city=New York
&state=NY
&zip_code=10001
&country=US
&site_url=https://merchant.example.com
&redirect_url=https://merchant.example.com/return
&server_callback_url=https://merchant.example.com/callback
&control=a1b2c3d4...
&payment_data=eyJzaWduYXR1cmUi...
&payment_data_type=googlepay_encrypted

client_orderid=ORDER123
&amount=25.00
&currency=USD
&first_name=John
&last_name=Doe
&email=john@example.com
&ipaddress=203.0.113.1
&address1=123 Main St
&city=New York
&state=NY
&zip_code=10001
&country=US
&site_url=https://merchant.example.com
&redirect_url=https://merchant.example.com/return
&server_callback_url=https://merchant.example.com/callback
&control=a1b2c3d4...
&payment_data=eyJzaWduYXR1cmUi...
&payment_data_type=googlepay_encrypted

Note

All response handling, Order Status polling, 3DS flow, and callback authentication work identically to standard Payment transactions. See Payment Transactions for details.

Transaction Types Overview

Common Utilities

Any other questions? Get in touch

Card Payment API

3.1 Card-Not-Present

1.1 Payment Transactions

Note

1.1.1 Direct Integration

Note

Tip

Note

Note

Note

Note

Note

Note

1.1.2 Payment Form Integration

Note

Note

Note

Note

1.2 Refund Transactions

Note

Note

Note

Note

3.2 Payouts

Note

Note

Note

Note

3.3 Google Pay / Apple Pay

Note

Note

Note