SALE request | Ikajo - global payment provider

API

SALE request

Payment Platform supports two main operation type: Single Message System (SMS) and Dual Message System (DMS).

SMS is represented by SALE transaction. It is used for authorization and capture at a time. This operation is commonly used for immediate payments.

DMS is represented by AUTH and CAPTURE transactions. AUTH  is used for authorization only, without capture. This operation used to hold the funds on card account (for example to check card validity).

SALE request is used to make both SALE and AUTH transactions.

If you want to make AUTH transaction, you need to use parameter auth with value Y. If you want to send a payment for the specific sub-account (channel), you need to use channel_id, that specified in your Payment Platform account settings.

This request is sent by POST in the background (eg, through PHP CURL).

Request parameters

Parameter  Description Values Required field
action Sale SALE +
async Asynchronous or synchronous mode Y or N (default N)
client_key Unique client key (CLIENT_KEY) +
channel_id Payment channel (Sub-account) String up to 16 characters
order_id Transaction ID in the Clients system String up to 255 characters +
order_amount The amount of the transaction Numbers in the form XXXX.XX (without leading zeros)  

+

order_currency Currency 3-letter code +
order_description Description of the transaction (product name) String up to 1024 characters +
req_token Special attribute pointing for further tokenization Y or N (default N)
gpay_token Token received by a merchant from Google Y or N (default N)
card_token Credit card token value String 64 characters
card_number Credit Card Number +1
card_exp_month Month of expiry of the credit card Month in the form XX +1
card_exp_year Year of expiry of the credit card Year in the form XXXX +1
card_cvv22 CVV/CVC2 credit card verification code 3-4 symbols +1
payer_first_name Customer’s name String up to 32 characters +
payer_last_name Customer’s surname String up to 32 characters +
payer_middle_name Customer’s middle name String up to 32 characters +
payer_birth_date Customer’s birthday format yyyy-MM-dd, e.g. 1970-02-17 +
payer_address Customer’s address String up to 255 characters +
payer_address2 The adjoining road or locality (if required) of the сustomer’s address String up to 255 characters +
payer_country Customer’s country 2-letter code +
payer_state Customer’s state String up to 32 characters +
payer_city Customer’s city String up to 32 characters +
payer_zip ZIP-code of the Customer String up to 32 characters +
payer_email Customer’s email String up to 256 characters +
payer_phone Customer’s phone String up to 32 characters +
payer_ip IP-address of the Customer XXX.XXX.XXX.XXX +
term_url_3ds URL to which Customer should be returned after 3D-Secure String up to 1024 characters +
recurring_init Initialization of the transaction with possible following recurring Y or N (default N)
ext1 Client Parameter 1
ext… Client Parameter …
ext10 Client Parameter 10
auth Indicates that transaction must be only authenticated, but not captured Y or N (default N)
hash Special signature to validate your request to Payment Platform * (Appendix A) +

1 – This field becomes optional if card_token is specified
2 – This field becomes optional if acquirer handles non-CVV2 transactions

If the optional parameter card_token and card data are specified, card_token will be ignored. If the optional parameters req_token and card_token are specified, req_token will be ignored.

If the optional parameters gpay token = Y, fields: card_number, card_exp_month, card_exp_year, card_cvv2 will be not required.

Response parameters

You will get JSON encoded string (see an example on Appendix B) with transaction result. If your account supports 3D-Secure, transaction result will be sent to your Callback URL.

Synchronous mode

Successful sale response:

Parameter Description
action SALE
result SUCCESS
status PENDING/SETTLED; only PENDING when auth=Y
order_id Transaction ID in the Client’s system
trans_id Transaction ID in the Payment Platform
trans_date Transaction date in the Payment Platform
descriptor This is a string which the owner of the credit card will see in the statement from the bank. In most cases, this is the Customers support web-site.
recurring_token Recurring token (get if account support recurring sales and was initialization transaction for following recurring)
amount Order amount
currency Currency
card_token If the parameter req_token was enabled Payment Platform returns the token value

 

Unsuccessful sale response:

Parameter Description
action SALE
result DECLINED
status DECLINED
order_id Transaction ID in the Client’s system
trans_id Transaction ID in the Payment Platform
trans_date Transaction date in the Payment Platform
decline_reason The reason why the transaction was declined

3D-Secure transaction response:

Parameter Description
action SALE
result REDIRECT
status 3DS
order_id Transaction ID in the Client’s system
trans_id Transaction ID in the Payment Platform
trans_date Transaction date in the Payment Platform
redirect_url URL to which the Client should redirect the Customer
redirect_params Array of specific 3DS parameters
redirect_method The method of transferring parameters (POST/GET)

Asynchronous mode

If you want to use asynchronous mode, you need to use async parameter with value “Y” in your sale request.

Using this mode you will get synchronous response (JSON encoded string) below that transaction is accepted for processing and result will be sent to your Callback URL.

Parameter Description
action SALE
result ACCEPTED
order_id Transaction ID in the Client’s system
trans_id Transaction ID in the Payment Platform
trans_date Transaction date in the Payment Platform

Callback parameters

Successful sale response:

Parameter Description
action SALE
result SUCCESS
status PENDING/SETTLED
order_id Transaction ID in the Client’s system
trans_id Transaction ID in the Payment Platform
trans_date Transaction date in the Payment Platform
descriptor This is a string which the owner of the credit card will see in the statement from the bank. In most cases, this is the Customers support web-site.
auth_code Bank approval code
recurring_token Recurring token (get if account support recurring sales and was initialization transaction for following recurring)
amount Order amount
currency Currency
card_token If the parameter req_token was enabled Payment Platform returns the token value
hash Special signature, used to validate callback **(Appendix A)

Unsuccessful sale response:

Parameter Description
action SALE
result DECLINED
status DECLINED
order_id Transaction ID in the Client’s system
trans_id Transaction ID in the Payment Platform
trans_date Transaction date in the Payment Platform
decline_reason Description of the cancellation of the transaction
hash Special signature, used to validate callback **(Appendix A)

3D-Secure transaction response:

Parameter Description
action SALE
result REDIRECT
status 3DS
order_id Transaction ID in the Client’s system
trans_id Transaction ID in the Payment Platform
trans_date Transaction date in the Payment Platform
redirect_url URL to which the Client should redirect the Customer
redirect_params Array parameters
redirect_method The method of transferring parameters (POST/GET)
hash Special signature, used to validate callback **(Appendix A)
Thank You For Order
Thank you!

Thanks for filling that out. We really appreciate you giving us a moment of your time today. Your ticket on its way to your email.