Card To Card Transfer¶

Direct Integration
Payment Form Integration

Payneteasy supports few schemas of money transfer: Card2Card, Cash2Card or Deposit2Card. All of them could be initiated by customer itself or by Merchant using recurrent API. Simple Money transfer described in Sale Transactions for direct Card2Card transfer and in Payment Form Integration for integration by external form. Recurrent Money transfer transactions are made in three steps:

Initial payment – make initial payment to verify and authorize credit card
Card Registration Diagram – get cards reference ID card-ref-id and remember it
Money transfer – run money transfer using card-ref-id from previous step. In case of transfer from registered card merchant initiates transfer using given source-card-ref-id and destination-card-no or destination-card-ref-id. In case of transfer from account merchant initiates transfer using given destination-card-no or destination-card-ref-id
After the payment initiation Payneteasy returns new Order ID for the this transfer
Merchant starts polling Payneteasy
Payneteasy returns current status of the order. processing status means the order is still being processed
Payneteasy processes the payment using appropriate bank’s gateway
Merchant keeps polling Payneteasy by using Status API
Payneteasy returns current status of the order - approved, declined or filtered

Money transfer URL ¶

For integration purposes use staging environment sandbox.payneteasy.com instead of production gate.payneteasy.com. Sale transactions are initiated through HTTPS POST request by using URL in the following format:

Money transfer transaction by ENDPOINTID ¶

The End point ID is an entry point for incoming Merchant’s transactions for single currency integration.

https://gate.payneteasy.com/paynet/api/v2/transfer/ENDPOINTID – to make single currency transfer between two card numbers, for details see Sale Transactions
https://gate.payneteasy.com/paynet/api/v2/transfer-form/ENDPOINTID – to make single currency transfer between two card numbers, for details see Payment Form Integration
https://gate.payneteasy.com/paynet/api/v2/transfer-by-ref/ENDPOINTID – to make single currency transfer between two card-ref-id’s or from registered card-ref-id to card number

Money transfer transaction by ENDPOINTGROUPID ¶

The End point group ID is an entry point for incoming Merchant’s transactions for multi currency integration.

https://gate.payneteasy.com/paynet/api/v2/transfer/group/ENDPOINTGROUPID – to make multi currency transfer between two card numbers, for details see Sale Transactions
https://gate.payneteasy.com/paynet/api/v2/transfer-form/group/ENDPOINTGROUPID – to make multi currency transfer between two card numbers, for details see Payment Form Integration
https://gate.payneteasy.com/paynet/api/v2/transfer-by-ref/group/ENDPOINTGROUPID – to make multi currency transfer between two card-ref-id’s or from registered card-ref-id to card number

Process Money Transfer ¶

Money transfer request parameters ¶

Note

Request must have content-type=application/x-www-form-urlencoded and Authorization headers.
Acquirer can redefine the necessity of some fields so they become mandatory instead of optional.
Leading and trailing whitespace in input parameters will be omitted.

Money transfer request parameter	Length/Type	Comment	Necessity*
client_orderid	128/String	Merchant order identifier.	Mandatory
login	20/String	Merchant’s login	Mandatory
source-card-ref-id	20/Numeric	Card reference id to source card, obtained at Card Registration step, not used for Transfer from account transactions	Optional
destination-card-no	16-19/String	Card number of destination card. Mandatory if destination-card-ref-id omitted. Ignored if destination-card-ref-id is not empty	Conditional
destination-card-ref-id	20/Numeric	Card reference id to destination card, obtained at Card Registration step. Mandatory if destination-card-no omitted.	Conditional
order_desc	64k/String	Order description	Mandatory
amount	10/Numeric	Amount to be transferred. The amount has to be specified in the highest units with . delimiter. For instance, 10.5 for USD means 10 US Dollars and 50 Cents	Mandatory
currency	3/String	Currency the transaction is charged in (three-letter currency code). Example ofВ valid parameter values are: USD for US Dollar EUR for European Euro	Mandatory
cvv2	3-4/Numeric	Customer’s CVV2 code for source card. CVV2 (Card Verification Value) is a three- or four-digit number AFTER the credit card number in the signature area of the card. May be empty or absent if bank gateway supports processing without CVV2, not used for Transfer from account transactions if destination-card-no is used	Optional
ipaddress	45/String	Customer’s IP address, included for fraud screening purposes.	Mandatory
control	40/String	Checksum generated by SHA-1. This is SHA-1 checksum of the concatenation login + client_orderid + source-card-ref-id (if present) + destination-card-ref-id (if present) + amount_in_cents + currency + merchant_control.	Mandatory
first_name	128/String	Sender first name, not used for Transfer from account transactions if destination-card-no is used	Optional
middle_name	128/String	Sender middle name, not used for Transfer from account transactions if destination-card-no is used	Optional
last_name	128/String	Sender last name, not used for Transfer from account transactions if destination-card-no is used	Optional
ssn	32/Numeric	Last four digits of the Sender’s social security number, not used for Transfer from account transactions if destination-card-no is used. Mandatory for some acquirers for cross-country transfers.	Conditional
birthday	8/Numeric	Sender date of birth, in the format MMDDYY, not used for Transfer from account transactions if destination-card-no is used	Optional
address1	50/String	Sender address line 1, not used for Transfer from account transactions if destination-card-no is used	Optional
city	50/String	Sender city, not used for Transfer from account transactions if destination-card-no is used	Optional
state	2-3/String	Sender’s state . Please see Reference for a list of valid state codes, not used for Transfer from account transactions if destination-card-no is used. Mandatory for USA, Canada and Australia.	Conditional
zip_code	10/String	Sender ZIP code, not used for Transfer from account transactions if destination-card-no is used	Optional
country	2/String	Sender country(two-letter country code). Please see Reference for a list of valid country codes, not used for Transfer from account transactions if destination-card-no is used	Optional
phone	15/String	Sender full international phone number, including country code, not used for Transfer from account transactions if destination-card-no is used	Optional
cell_phone	15/String	Sender full international cell phone number, including country code, not used for Transfer from account transactions if destination-card-no is used	Optional
email	50/String	Sender email address, not used for Transfer from account transactions if destination-card-no is used	Optional
purpose	128/String	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. Sample values are: +7123456789; gamer0001@ereality.com etc. This value will be used by fraud monitoring system.	Optional
receiver_first_name	128/String	Receiver first name	Optional
receiver_middle_name	128/String	Receiver middle name	Optional
receiver_last_name	128/String	Receiver last name	Optional
receiver_resident	Boolean (true/false)	Is receiver a resident?	Optional
redirect_url	1024/String	URL the cardholder will be redirected to upon completion of the transaction. Please note that the cardholder will be redirected in any case, no matter whether the transaction is approved or declined. You should not use this parameter to retrieve results from Payneteasy gateway, because all parameters go through client’s browser and can be lost during transmission. To deliver the correct payment result to your backend use server_callback_url instead.	Optional
redirect_success_url	1024/String	URL the cardholder will be redirected to upon completion of the transaction. Please note that the cardholder will be redirected only in case if the transaction is approved. You should not use this parameter to retrieve results from Payneteasy gateway, because all parameters go through client’s browser and can be lost during transmission. To deliver the correct payment result to your backend use server_callback_url instead.	Optional
redirect_fail_url	1024/String	URL the cardholder will be redirected to upon completion of the transaction. Please note that the cardholder will be redirected only in case if the transaction is declined or filtered. You should not use this parameter to retrieve results from Payneteasy gateway, because all parameters go through client’s browser and can be lost during transmission. To deliver the correct payment result to your backend use server_callback_url instead.	Optional
server_callback_url	1024/String	URL the transaction result will be sent to. Merchant may use this URL for custom processing of the transaction completion, e.g. to collect sales data in Merchant’s database. See more details at Merchant Callbacks	Optional

Additional fields for money transfer transactions ¶

Note

Browser data for 3DS 2.X is gathered by Payneteasy system on 3DS authentication stage. For some processing channels, however, the browser data and/or merchant URL for 3DS challenge results must be provided in initial transaction request. Please contact Support manager to clarify if these parameters should be included in request parameters.

The merchant’s site needs to accurately populate the browser information for each transaction. This data can be obtained by merchant’s servers. Ensure that the data is not altered or hard-coded, and that it is unique to each transaction.

Field Name	Length/Type	Description	Conditional Inclusion
tds_areq_notification_url, alias tds_cres_notification_url	256/String	Fully qualified URL of merchant system that will receive the CRes message or Error Message. This CRes message must be sent to Payneteasy. See details here Upload CRes Result	Optional
customer_browser_info	Boolean	If true, then the fields below must be present	Optional
ipaddress	45/String	IP address of the browser as returned by the HTTP headers to the 3DS Requestor	Required
customer_browser_accept_header	2048/String	Exact content of the HTTP accept headers as sent to the 3DS Requestor from the Cardholder’s browser	Required
customer_browser_color_depth	2/String	Value representing the bit depth of the colour palette for displaying images, in bits per pixel	Required when browser_javaScript_enabled = true; otherwise Optional
customer_browser_java_enabled	Boolean	Boolean that represents the ability of the cardholder browser to execute Java	Required when browser_javaScript_enabled = true; otherwise Optional
customer_browser_javascript_enabled	Boolean	Boolean that represents the ability of the cardholder browser to execute JavaScript	Required
customer_browser_accept_language	8/String	Value representing the browser language as defined in IETF BCP47	Required
customer_browser_screen_height	6/Numeric	Total height of the Cardholder’s screen in pixels	Required when browser_javaScript_enabled = true; otherwise Optional
customer_browser_screen_width	6/Numeric	Total width of the cardholder’s screen in pixels	Required when browser_javaScript_enabled = true; otherwise Optional
customer_browser_time_zone	5/String	Time-zone offset in minutes between UTC and the Cardholder browser local time. Note that the offset is positive if the local time zone is behind UTC and negative if it is ahead	Required when browser_javaScript_enabled = true; otherwise Optional
customer_browser_user_agent	2048/String	Exact content of the HTTP user-agent header	Required

Transfer Response ¶

Note

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

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

Transfer Response Example ¶

type=async-response
&serial-number=00000000-0000-0000-0000-00000456f9e1
&merchant-order-id=902B4FF5
&paynet-order-id=3622255
&end-point-id=212

3DS redirect ¶

If your gate supports 3-D Secure you need to send status request and process html return parameter to send customer to 3-D Secure Authorisation. The simplified schema looks like:

Customer -> Merchant: Initiate transaction
activate Merchant

Merchant -> "Payneteasy": transfer-by-ref
activate "Payneteasy"
"Payneteasy" --> Merchant: async-response
Merchant -> "Payneteasy": status
"Payneteasy" --> Merchant: html
deactivate "Payneteasy"
Merchant --> Customer: urldecode(html)
deactivate Merchant

html field is always present for 3DS gates in status response, whether clients card supports 3-D Secure or not.

If source-card-ref-id is specified upon completion of 3DS authorization process by the Customer he/she is automatically redirected to redirect_url. The redirection is performed as an HTTPS POST request with the parameters specified in the following table.

Redirect parameter	Description
status	See Status List for details.
orderid	Order id assigned to the order by Payneteasy
merchant_order	Merchant order id
client_orderid	Merchant order id
error_message	If status is declined or error this parameter contains the reason for decline or error details
control	Checksum used to ensure that it is Payneteasy (and not a fraudster) that initiates the request. This is SHA-1 checksum of the concatenation status + orderid + client_orderid + merchant-control.
descriptor	Gate descriptor

If Merchant has passed server_callback_url in original Sale request Payneteasy will call this URL. Merchant may use it for custom processing of the transaction completion, e.g. to collect sales data in Merchant’s database. The parameters sent to this URL are specified in sale, return Callback Parameters

Server callback result ¶

Upon completion by the System of 3DS request processing it returns the result on the specified server_callback_url with the following parameters described in sale, return Callback Parameters

The checksum is used to ensure that the callback is initiated for a particular Merchant, and not for anybody else claiming to be such Merchant. This SHA-1 checksum, the control parameter, is created by concatenation of the parameters values in the following order:

status
orderid
client_orderid
merchant_control

A complete string example may look as follows:

approvedS279G323P4T1209294c258d6536ababe653E8E45B5-7682-42D8-6ECC-FB794F6B11B1

Encrypt the string using SHA-1 algorithm. The resultant string yields the control parameter. For the above-mentioned example the control will take the following value:

e04bd50531f45f9fc76917ac78a82f3efaf0049c

All parameters are sent via GET method.

Server callback result example ¶

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

Transfer Request Debug ¶

endpointid or groupid		input your ENDPOINTID
login
client_orderid		make it or use your internal invoice ID
source-card-ref-id
credit_card_number		enter the beginning of the sequence, and then "i"
card_printed_name
expire_month
expire_year
destination-card-no
destination-card-ref-id
order_desc
amount
currency
cvv2
ipaddress
first_name
middle_name
last_name
ssn
birthday
address1
city
state
zip_code
country
phone
cell_phone
email
receiver_ffirst_name
receiver_fmiddle_name
receiver_flast_name
receiver_resident
purpose
merchant_control		input your Control Key
redirect_url
redirect_success_url
redirect_fail_url
server_callback_url
merchant_data

String to sign

Signature

Order status ¶

Merchant must use Order status API call to get the customer’s order transaction status. After any type of transaction is sent to Payneteasy server and order id is returned, Merchant should poll for transaction status. When transaction is processed on Payneteasy server side it returns it’s status back to Merchant and at this moment the Merchant is ready to show the customer transaction result, whether it’s approved or declined.

Status API URL ¶

Status API calls are initiated through HTTPS POST request by using URL in the following format:
https://gate.payneteasy.com/paynet/api/v2/status/ENDPOINTID
for integration purposes use staging environment sandbox.payneteasy.com instead of production gate.payneteasy.com

The End point ID is an entry point for incoming Merchant’s transactions and is actually the only Payneteasy object which is exposed via API.

Order status call parameters ¶

Status parameter	Description
login	Merchant login name
client_orderid	Merchant order identifier of the transaction for which the status is requested
orderid	Order id assigned to the order by Payneteasy
by-request-sn	Serial number assigned to the specific request by Payneteasy. If this field exist in status request, status response return for this specific request.
control	Checksum used to ensure that it is Payneteasy (and not a fraudster) that initiates the callback for a particular Merchant. This is SHA-1 checksum of the concatenation login + client-order-id + paynet-order-id + merchant-control. See Order status API call authorization through control parameter for more details about generating control checksum.

Order Status Response ¶

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.

Status Response Parameter	Description
type	The type of response. May be status-response
status	See Status List for details.
amount	Actual transaction amount. This value can be changed during the transaction flow.
paynet-order-id	Order id assigned to the order by Payneteasy
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. The Payneteasy System returns the following response parameters when it gets 3DS authorization form from the Issuer Bank. It contains auth form HTML code which must be passed through without any changes to the client’s browser. This parameter exists and has value only when the redirection HTML is already available. For non-3DS this never happens. For 3DS HTML has value after some short time after the processing has been started.
redirect-to	For 3DS authorization the merchant can redirect the customer to URL provided in this parameter using GET HTTP method instead of rendering the page provided in html parameter. The redirect-to parameter is returned only if the html parameter is returned. This parameter must be used to work with 3DS 2.0.
serial-number	Unique number assigned by Payneteasy server to particular request from the Merchant.
gate-partial-reversal	Processing gate support partial reversal (enabled or disabled).
gate-partial-capture	Processing gate support partial capture (enabled or disabled).
transaction-type	Transaction type (sale, reversal, capture, preauth).
processor-rrn	Bank Receiver Registration Number.
processor-tx-id	Acquirer transaction identifier.
receipt-id	Electronic link to receipt https://gate.payneteasy.com/paynet/view-receipt/ENDPOINTID/receipt-id/
name	Cardholder name.
cardholder-name	Cardholder name.
card-exp-month	Card expiration month.
card-exp-year	Card expiration year.
card-hash-id	Unique card identifier to use for loyalty programs or fraud checks.
destination-hash-id	Unique card identifier to use for loyalty programs or fraud checks.
email	Customer e-mail.
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. Sample values are: +7123456789; gamer0001@ereality.com etc. This value will be used by fraud monitoring system.
bank-name	Bank name by customer card BIN.
last-four-digits	Last four digits of customer credit card number.
bin	Bank BIN of customer credit card number.
card-type	Type of customer credit card (VISA, MASTERCARD, etc).
dest-bank-name	Destination bank name by customer card BIN.
dest-last-four-digits	Destination last four digits of customer credit card number.
dest-bin	Destination bank BIN of customer credit card number.
dest-card-type	Type of destination customer credit card (VISA, MASTERCARD, etc).
terminal-id	Acquirer terminal identifier to show in receipt.
paynet-processing-date	Acquirer transaction processing date.
approval-code	Bank approval code.
order-stage	The current stage of the transaction processing. See Order Stage for details
loyalty-balance	The current bonuses balance of the loyalty program for current operation. if available
loyalty-message	The message from the loyalty program. if available
loyalty-bonus	The bonus value of the loyalty program for current operation. if available
loyalty-program	The name of the loyalty program for current operation. if available
descriptor	Bank identifier of the payment recipient.
error-message	If status in declined, error, filtered this parameter contains the reason for decline
error-code	The error code is case status in declined, error, filtered.
by-request-sn	Serial number assigned to the specific request by Payneteasy. If this field exist in status request, status response return for this specific request.
verified-3d-status	See:ref:3d_secure_status_list for details
verified-rsc-status	See Random Sum Check Status List for details
initial-amount	Amount, set in initiating transaction, without any fees or commissions. This value can’t change during the transaction flow.
transaction-date	Date of final status assignment for transaction.

Order Status Response Example ¶

type=status-response
&serial-number=00000000-0000-0000-0000-00000456f9e6
&merchant-order-id=902B4FF5
&processor-tx-id=PNTEST-3622257
&paynet-order-id=3622257
&status=approved
&amount=10.42
&descriptor=3D
&transaction-type=transfer
&receipt-id=93c8ea85-9126-3d72-bca2-98e999107c82
&name=CARD+HOLDER
&cardholder-name=CARD+HOLDER
&card-exp-month=12
&card-exp-year=2099
&email=john.smith%40gmail.com
&processor-rrn=511000302615
&approval-code=965452
&order-stage=transfer_approved
&merchantdata=VIP+customer
&last-four-digits=1111
&bin=444455
&card-type=VISA
&phone=12063582043
&bank-name=UNKNOWN
&dest-bank-name=CITIBANK
&dest-bin=520306
&dest-last-four-digits=9001
&dest-card-type=MASTERCARD
&paynet-processing-date=2015-04-20+22%3A53%3A37+MSK
&card-hash-id=212609
&destination-card-hash-id=212608
&verified-3d-status=AUTHENTICATED
&verified-rsc-status=AUTHENTICATED
&transaction-date=2023-01-10+12%3A46%3A28+MSK

Status request authorization through control parameter ¶

The checksum is used to ensure that it is Merchant (and not a fraudster) that sends the request to Payneteasy. This SHA-1 checksum, the parameter control, is created by concatenating of the values of the parameters in the following order:

login
client_orderid
orderid
merchant_control

For example assume the following values are corresponds the parameters above:

Parameter name	Parameter Value
login	cool_merchant
client_orderid	5624444333322221111110
orderid	9625
merchant_control	r45a019070772d1c4c2b503bbdc0fa22

The complete string example may look as follows:

cool_merchant56244443333222211111109625r45a019070772d1c4c2b503bbdc0fa22

Encrypt the string using SHA-1 algorithm. The resultant string yields the control parameter which is required for authorizing the callback. For the example control above will take the following value:

c52cfb609f20a3677eb280cc4709278ea8f7024c

Order status Debug ¶

endpointid or groupid		input your ENDPOINTID or ENDPOINTGROUPID
login
client_orderid		input your Invoice Number
orderid
merchant_control		input your Control Key
by-request-sn

String to sign

Signature

>

Payment Form Integration ¶

Payment Form integration is relevant for merchants who are not able to accept customer card details (merchant’s website must complete PCI DSS certification). In case of Payment Form integration merchant is released of accepting payment details and all this stuff is completely implemented on the Payneteasy gateway side. In addition merchant may customize the look and feel of the Payment Form. Merchant must send the template to his/her Manager for approval before it could be used.

Merchant Site initiates a Pre-auth transaction by sending corresponding HTTPS POST request to the specified URL
The System processes the transaction and sends corresponding response (depending on 3D/non-3DS processing type). Upon successful completion of a transfer transaction the bank blocks the specified amount in the credit card account and does not allow the cardholder to use this blocked money. It is important to know that the block remains for a definite period of time depending on whether this is a debit or a credit card (usually the maximum block period is 7 days for debit cards and 28 days for credit cards).
Merchant sends Capture transaction in order to deduct the locked amount from credit card.
System processes capture transaction and returns corresponding response. In this case the money is actually transferred from the bank-issuer account to the bank-acquirer account, which means the end of the transaction.
Merchant is using single entry point for both 3DS and non-3DS Transfer transactions. Actually the Merchant can not know beforehand if the sale will be driven through 3DS authorization scheme. The Merchant should use Payneteasy API as described below.

Payment Form API URL ¶

For integration purposes use staging environment sandbox.payneteasy.com instead of production gate.payneteasy.com. Payment Form transactions are initiated through HTTPS POST request by using URL in the following format:

Form Transaction by ENDPOINTID ¶

The End point ID is an entry point for incoming Merchant’s transactions for single currency integration.

https://gate.payneteasy.com/paynet/api/v2/transfer-form/ENDPOINTID - for transfer transactions

Form Transaction by ENDPOINTGROUPID ¶

The End point group ID is an entry point for incoming Merchant’s transactions for multi currency integration.

https://gate.payneteasy.com/paynet/api/v2/transfer-form/group/ENDPOINTGROUPID - for transfer transactions

General Payment Form Process Flow ¶

Checkout – Customer proceeds to order checkout.
Merchant initiates a transaction by sending HTTPS POST request to the specified URL.
Payneteasy gateway returns response which contains an additional parameter redirect-url. This is the URL where merchant must redirect Customer’s browser to.
See details about response format in Payment Form Response.
Merchant sends HTTP 302 redirect to Customer’s browser using URL which is obtained from the redirect-url response parameter.
Customer fills in payment details and submits the Payment Form.
Payneteasy gateway processes the transaction according to 3D or Non 3D process.
When transfer authorization is completed Payneteasy gateway redirects the Customer’s browser to redirect_url request parameter provided by merchant in the original request accomplished at step 2. See details in Payment Form final redirect.

Payment form fields ¶

This form contains the following fields:

Form field name	Description
credit_card_number	Customer’s credit card number 4455555555555544
expire_month	Credit card expiration month 01 or 12
expire_year	Credit card expiration year 2016
cvv2	Card security code 432

Initiating a transaction with Payment Form ¶

Merchant must supply the following parameters to initiate a transfer transaction using payment form template.

Payment Form Request Parameters ¶

Request parameter name	Length/Type	Comment	Necessity*
client_orderid	128/String	Merchant order identifier.	Mandatory
order_desc	64k/String	Brief order description	Mandatory
first_name	50/String	Customer’s first name	Mandatory
last_name	50/String	Customer’s last name	Mandatory
ssn	4/Numeric	Last four digits of the customer’s social security number.	Optional
birthday	8/Numeric	Customer’s date of birth, in the format YYYYMMDD.	Optional
address1	50/String	Customer’s address line 1.	Mandatory
city	50/String	Customer’s city.	Mandatory
state	2/String	Customer’s state (two-letter state code). Please see Country Codes for a list of valid state codes. Mandatory for USA, Canada and Australia	Conditional
zip_code	10/String	Customer’s ZIP code	Mandatory
country	2/String	Customer’s country(two-letter country code). Please see Country Codes for a list of valid country codes.	Mandatory
phone	15/String	Customer’s full international phone number, including country code.	Mandatory
cell_phone	15/String	Customer’s full international cell phone number, including country code.	Optional
email	50/String	Customer’s email address.	Mandatory
amount	10/Numeric	Amount to be charged. The amount has to be specified in the highest units with . delimiter. 10.5 for USD means 10 US Dollars and 50 Cents	Mandatory
currency	3/String	Currency the transaction is charged in (three-letter currency code). Sample values are: USD for US Dollar EUR for European Euro	Mandatory
ipaddress	45/String	Customer’s IP address, included for fraud screening purposes.	Mandatory
site_url	128/String	URL the original sale is made from.	Optional
control	40/String	Checksum generated by SHA-1. See Request authorization through control parameter for more details.	Mandatory
redirect_url	1024/String	URL the cardholder will be redirected to upon completion of the transaction. Please note that the cardholder will be redirected in any case, no matter whether the transaction is approved or declined. You should not use this parameter to retrieve results from Payneteasy gateway, because all parameters go through client’s browser and can be lost during transmission. To deliver the correct payment result to your backend use server_callback_url instead.	Mandatory if both redirect_success_url and redirect_fail_url are missing
redirect_success_url	1024/String	URL the cardholder will be redirected to upon completion of the transaction. Please note that the cardholder will be redirected only in case if the transaction is approved. You should not use this parameter to retrieve results from Payneteasy gateway, because all parameters go through client’s browser and can be lost during transmission. To deliver the correct payment result to your backend use server_callback_url instead. Pass http://google.com if you use non-3DS schema for transactions processing and you have no need to return customer anywhere.	Mandatory if redirect_url parameter is missing
redirect_fail_url	1024/String	URL the cardholder will be redirected to upon completion of the transaction. Please note that the cardholder will be redirected only in case if the transaction is declined or filtered. You should not use this parameter to retrieve results from Payneteasy gateway, because all parameters go through client’s browser and can be lost during transmission. To deliver the correct payment result to your backend use server_callback_url instead. Pass http://google.com if you use non-3DS schema for transactions processing and you have no need to return customer anywhere.	Mandatory if redirect_url parameter is missing
server_callback_url	1024/String	URL the transaction result will be sent to. Merchant may use this URL for custom processing of the transaction completion, e.g. to collect sales data in Merchant’s database. See more details at Merchant Callbacks	Optional
preferred_language	2/String	Customer’s two-letter language code for multi-language payment forms	Optional
merchant_form_data	128/String	Parameters sent in merchant_form_data API parameter are parsed into macros with the same name, the parameter is url-encoded, example: testparam%3Dtest1%26mynewparam%3Dtest2 and is parsed into $MFD_testparam = test1 and $MFD_mynewparam = test2 macros in the form. Parameter name characters[a-zA-Z0-9], parameter value characters[a-zA-Z0-9], control characters [=&], 2MB max size. For example, this parameter can be used to display payment form in light/dark mode depending on the value passed by Connecting Party (e.g. pass merchant_form_data=theme%3Ddark in request and $MFD_theme macro placeholder on payment form will be changed to dark.	Optional

* acquirer can redefine the necessity of some fields so they become mandatory instead of optional

* leading and trailing whitespace in input parameters will be omitted

Additional fields for form transactions ¶

Note

Browser data for 3DS 2.X is gathered by Payneteasy system on 3DS authentication stage. For some processing channels, however, the browser data and/or merchant URL for 3DS challenge results must be provided in initial transaction request. Please contact Support manager to clarify if these parameters should be included in request parameters.

The merchant’s site needs to accurately populate the browser information for each transaction. This data can be obtained by merchant’s servers. Ensure that the data is not altered or hard-coded, and that it is unique to each transaction.

Field Name	Length/Type	Description	Conditional Inclusion
tds_areq_notification_url, alias tds_cres_notification_url	256/String	Fully qualified URL of merchant system that will receive the CRes message or Error Message. This CRes message must be sent to Payneteasy. See details here Upload CRes Result	Optional
customer_browser_info	Boolean	If true, then the fields below must be present	Optional
ipaddress	45/String	IP address of the browser as returned by the HTTP headers to the 3DS Requestor	Required
customer_browser_accept_header	2048/String	Exact content of the HTTP accept headers as sent to the 3DS Requestor from the Cardholder’s browser	Required
customer_browser_color_depth	2/String	Value representing the bit depth of the colour palette for displaying images, in bits per pixel	Required when browser_javaScript_enabled = true; otherwise Optional
customer_browser_java_enabled	Boolean	Boolean that represents the ability of the cardholder browser to execute Java	Required when browser_javaScript_enabled = true; otherwise Optional
customer_browser_javascript_enabled	Boolean	Boolean that represents the ability of the cardholder browser to execute JavaScript	Required
customer_browser_accept_language	8/String	Value representing the browser language as defined in IETF BCP47	Required
customer_browser_screen_height	6/Numeric	Total height of the Cardholder’s screen in pixels	Required when browser_javaScript_enabled = true; otherwise Optional
customer_browser_screen_width	6/Numeric	Total width of the cardholder’s screen in pixels	Required when browser_javaScript_enabled = true; otherwise Optional
customer_browser_time_zone	5/String	Time-zone offset in minutes between UTC and the Cardholder browser local time. Note that the offset is positive if the local time zone is behind UTC and negative if it is ahead	Required when browser_javaScript_enabled = true; otherwise Optional
customer_browser_user_agent	2048/String	Exact content of the HTTP user-agent header	Required

Payment Form Response ¶

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

Response parameter name	Description
type	The type of response. May be async-form-response, validation-error, error. If type equals validation-error or error, error-message and error-code parameters contain error details.
paynet-order-id	Order id assigned to the order by Payneteasy
merchant-order-id	Merchant order id
serial-number	Unique number assigned by Payneteasy server to particular request from the Merchant.
error-message	If status is declined or error this parameter contains the reason for decline or error details
error-code	The error code in case of declined or error status
redirect-url	The URL to the page where the Merchant should redirect the client’s browser. Merchant should send HTTP 302 redirect, see General Payment Form Process Flow

Payment Form final redirect ¶

Upon completion of Payment Form process by the Customer he/she is automatically redirected to redirect_url. The redirection is performed as an HTTPS POST request with the parameters specified in the following table.

Redirect parameter name	Description
status	See Status List for details.
orderid	Order id assigned to the order by Payneteasy
merchant_order	Merchant order id
client_orderid	Merchant order id
error_message	If status is declined or error this parameter contains the reason for decline or error details
control	Checksum used to ensure that it is Payneteasy (and not a fraudster) that initiates the request. This is SHA-1 checksum of the concatenation status + orderid + client_orderid + merchant-control.
descriptor	Gate descriptor
processor-tx-id	Acquirer transaction identifier
amount	Actual transaction amount.
bin	Bank BIN of customer credit card number
type	The type of response.
card-type	Type of customer credit card
phone	Customer phone
last-four-digits	Last four digits of customer credit card number
card-holder-name	Cardholder name
error_code	Error Code

If Merchant has passed server_callback_url in original Payment Form request Payneteasy will call this URL. Merchant may use it for custom processing of the transaction completion, e.g. to collect sales data in Merchant’s database. The parameters sent to this URL are specified in Sale, Return Callback Parameters

Payment Form Template Sample ¶

<html>
<head>
<script type="text/javascript">
  function isCCValid(r){var n=r.length;if(n>19||13>n)return!1;
    for(i=0,s=0,m=1,l=n;i<l;i++)d=parseInt(r.substring(l-i-1,l-i),10)*m,s+=d>=10?d%10+1:d,1==m?m++:m--;
    return s%10==0?!0:!1}
</script>
</head>
<body>
<h3>Order #$!MERCHANT_ORDER_ID - $!ORDERDESCRIPTION</h3>
<h3>Total amount: $!AMOUNT $!CURRENCY to $!MERCHANT</h3>

<form action="${ACTION}" method="post">
  <div>Cardholder name: <input name="${CARDHOLDER}" type="text" maxlength="64"/></div>
  <div><label for="cc-number">Credit Card Number</label> <input id="cc-number" name="${CARDNO}" type="text" maxlength="19" autocomplete="cc-number"/></div>
  <div>Card verification value: <input name="${CVV2}" type="text" maxlength="4" autocomplete="off"/></div>
  <div>
    Expiration date:
    <select class="expiry-month" name="${EXPMONTH}" size="1" autocomplete="cc-exp-month" >
      <option value="01">January</option><option value="02">February</option><option value="03">March</option>
      <option value="04">April</option><option value="05">May</option><option value="06">June</option>
      <option value="07">July</option><option value="08">August</option><option value="09">September</option>
      <option value="10">October</option><option value="11">November</option><option value="12">December</option>
    </select>
      <select class="expiry-year" id="cc-exp-year" name="${EXPYEAR}" size="1" autocomplete="cc-exp-year">
      ${EXPIRE_YEARS}
    </select>
  </div>
  $!{INTERNAL_SECTION}
  #if($!card_error)
  <div style="color: red;">$!card_error</div>
  #end
  <input name="submit" onclick="return isCCValid(document.getElementById('cardnumber').value);" type="submit" value="Pay"/>
</form>
</body>
</html>

Payment form autofill ¶

If you want to use autofill in your payment form, certain element attributes <id> <autocomplete> <label for> should be hardcoded in the following manner:

<label for="cc-number">Credit Card Number</label><span class="form-label-comment">The 13-19 digits on the front of your card</span>
<input class="card-number-field" id="cc-number" name="${CARDNO}" type="text" maxlength="19" autocomplete="cc-number" />

Our default payment form template supports autocomplete. In case if you want to add additional fields for autocomplete, this specification should be used for naming references.

Payment form macros ¶

Field Name Macro	Field Value Macro	Description
${CARDNO}	${CARDNOVALUE}	Customer’s credit card number.
${EXPMONTH}	n/a	Credit card expiration month
${EXPYEAR}	n/a	Credit card expiration year
${CVV2}	${CVV2VALUE}	Card security code 432
${CARDHOLDER}	${CARDHOLDER_VALUE}	Card printed name
${MERCHANT}	n/a	End point display name
${SKIN_VERSION}	n/a	CSS skin version
${ORDERDESCRIPTION}	n/a	Order description
${CUSTOMER_FIRST_NAME}	n/a	Customer first name sent by merchant via input parameters
${CUSTOMER_LAST_NAME}	n/a	Customer last name sent by merchant via input parameters
${CUSTOMER_EMAIL}	n/a	Customer E-mail address sent by merchant via input parameters
${AMOUNT}	n/a	Amount
${CURRENCY}	n/a	Currency
${PAYNET_ORDER_ID}	n/a	Payneteasy order id
${MERCHANT_ORDER_ID}	n/a	Merchant order id
${refresh_interval}	n/a	Refresh interval recommended by system
${uuid}	n/a	Internal
${INTERNAL_SECTION}	n/a	Internal for iFrame integration
${CUSTOMER_IP_COUNTRY_ISO_CODE}	n/a	Customer country defined by IP Address
${PREFERRED_LANGUAGE}	n/a	Customer language sent by merchant via input parameters
${BROWSER_LANGUAGE}	n/a	Customer language defined by browser settings
${CUSTOMER_LANGUAGE}	n/a	Customer language sent by merchant via input parameters or defined by browser settings if first is not set
${MERCHANT_FORM_DATA}	n/a	Parameters sent in merchant_form_data API parameter are parsed into macros with the same name, the parameter is url-encoded, example: testparam%3Dtest1%26mynewparam%3Dtest2 and is parsed into $MFD_testparam = test1 and $MFD_mynewparam = test2 macros in the form. Parameter name characters[a-zA-Z0-9], parameter value characters[a-zA-Z0-9], control characters [=&], 2MB max size. For example, this parameter can be used to display payment form in light/dark mode depending on the value passed by Connecting Party (e.g. pass merchant_form_data=theme%3Ddark in request and $MFD_theme macro placeholder on payment form will be changed to dark.
${CUSTOMER_ZIP_CODE}	n/a	Generates a ZIP code to send to the processor if it was not received from the client

Wait Page Template Sample ¶

<html>
<head>
<script type="text/javascript">
  function fc(t) {
    document.getElementById("seconds-remaining").innerHTML = t;
    (t > 0) ? setTimeout(function(){fc(--t);}, 1000) : document.checkform.submit();}
</script>
</head>
<body onload="fc($!refresh_interval)">
<h3>Order #$!MERCHANT_ORDER_ID - $!ORDERDESCRIPTION</h3>
<h3>Total amount: $!AMOUNT $!CURRENCY to $!MERCHANT</h3>
Please wait, your payment is being processed, remaining <span id="seconds-remaining">&nbsp;</span> seconds.
<form name="checkform" method="post">
  <input type="hidden" name="tmp" value="$!uuid"/>
      $!{INTERNAL_SECTION}
  <input type="submit" value="Check" />
</form>
</body>
</html>

Wait Page macros ¶

Field Name Macro	Field Value Macro	Description
${MERCHANT}	n/a	End point display name
${SKIN_VERSION}	n/a	CSS skin version
${ORDERDESCRIPTION}	n/a	Order description
${AMOUNT}	n/a	Amount
${CURRENCY}	n/a	Currency
${PAYNET_ORDER_ID}	n/a	Payneteasy order id
${MERCHANT_ORDER_ID}	n/a	Merchant order id
${refresh_interval}	n/a	Refresh interval recommended by system
${uuid}	n/a	Internal
${INTERNAL_SECTION}	n/a	Internal for iFrame integration
${CUSTOMER_IP_COUNTRY_ISO_CODE}	n/a	Customer country defined by IP Address
${PREFERRED_LANGUAGE}	n/a	Customer language send by merchant via input parameters
${BROWSER_LANGUAGE}	n/a	Customer language defined by browser settings
${CUSTOMER_LANGUAGE}	n/a	Customer language send by merchant via input parameters or defined by browser settings if first is not set

Finish Page Template Sample ¶

<html>
    <head>
    </head>
    <body>
        <h3>Processing of the payment has finished</h3>
        <h3>Order Invoice: $!{MERCHANT_ORDER_ID}</h3>
            <h3>Order ID: $!{PAYNET_ORDER_ID}</h3>
            <h3>Status: $!{STATUS}</h3>

        #if($ERROR_MESSAGE)
            <h3>Error: $!{ERROR_MESSAGE}</h3>
        #end
    </body>
</html>

Finish Page Macros ¶

Field Name Macro	Field Value Macro	Description
${STATUS}	n/a	Order status
${PAYNET_ORDER_ID}	n/a	System order id
${MERCHANT_ORDER_ID}	n/a	Merchant order id
${ERROR_MESSAGE}	n/a	Contains the reason for decline or error details
${SKIN_VERSION}	n/a	CSS skin version
${CUSTOMER_IP_COUNTRY_ISO_CODE}	n/a	Customer country defined by IP Address
${PREFERRED_LANGUAGE}	n/a	Customer language send by merchant via input parameters
${BROWSER_LANGUAGE}	n/a	Customer language defined by browser settings
${CUSTOMER_LANGUAGE}	n/a	Customer language send by merchant via input parameters or defined by browser settings if first is not set

Request authorization through control parameter ¶

The checksum is used to ensure that it is a particular Merchant (and not a fraudster) that initiates the transaction. This SHA-1 checksum, the parameter control, is created by concatenation of the parameters values in the following order:

ENDPOINTID/ENDPOINTGROUPID
client_orderid
minimal monetary units amount (i.e. cent, penny etc. For amount 0.94 USD value in signing string will be 94, for 10.15 USD value in signing string will be 1015)
email
merchant_control

A complete string example may look as follows:

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

Encrypt the string using SHA-1 algorithm. The resultant string yields the control parameter (see Payment Form Request Parameters) which is required for request authorization. For the above-mentioned example the control will take the following value:

d02e67236575a8e02dea5e094f3c8f12f0db43d7

Payment Form Request Debug ¶

endpointid or groupid		input your ENDPOINTID or ENDPOINTGROUPID
client_orderid		make it or use your internal invoice ID
order_desc
first_name
last_name
ssn
birthday
address1
city
state
zip_code
country
phone
cell_phone
amount
email
currency
ipaddress
site_url
purpose
merchant_control		input your Control Key
redirect_url
redirect_success_url
redirect_fail_url
server_callback_url
merchant_data
merchant_form_data

String to sign

Signature

Order status ¶

Merchant must use Order status API call to get the customer’s order transaction status. After any type of transaction is sent to Payneteasy server and order id is returned, Merchant should poll for transaction status. When transaction is processed on Payneteasy server side it returns it’s status back to Merchant and at this moment the Merchant is ready to show the customer transaction result, whether it’s approved or declined.

Status API URL ¶

For integration purposes use staging environment sandbox.payneteasy.com instead of production gate.payneteasy.com. Status API calls are initiated through HTTPS POST request by using URL in the following format:

The End point ID is an entry point for incoming Merchant’s transactions for single currency integration.

https://gate.payneteasy.com/paynet/api/v2/status/ENDPOINTID

The End point group ID is an entry point for incoming Merchant’s transactions for multi currency integration.

https://gate.payneteasy.com/paynet/api/v2/status/group/ENDPOINTGROUPID

Order status call parameters ¶

Status Call Parameter	Description	Necessity
login	Merchant login name	Mandatory
client_orderid	Merchant order identifier of the transaction for which the status is requested	Mandatory
orderid	Order id assigned to the order by Payneteasy	Conditional
control	Checksum used to ensure that it is Payneteasy (and not a fraudster) that initiates the callback for a particular Merchant. This is SHA-1 checksum of the concatenation login + client-order-id + paynet-order-id + merchant-control. See Order status API call authorization through control parameter for more details about generating control checksum.	Mandatory
by-request-sn	Serial number assigned to the specific request by Payneteasy. If this field exist in status request, status response return for this specific request. Include this parameter to get the status response with the particular transaction stage (can be used in specific cases). To get the latest transaction status, don’t include this parameter in status request.	Optional

In most common cases, the best option is to include both client_orderid and orderid parameters to status request. Order status can be requested with only client_orderid if it’s unique to merchant and orderid is not received. If orderid is not received in response, but this response contains an error, see the received error message to get the information why transaction was not created in the system.

Order Status Response ¶

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

Status Response Parameter	Description
type	The type of response. May be status-response
status	See Status List for details.
amount	Amount of the initial transaction.
currency	Currency of the initial transaction.
paynet-order-id	Order id assigned to the order by Payneteasy
merchant-order-id	Merchant order id
phone	Customer phone.
serial-number	Unique number assigned by Payneteasy server to particular request from the Merchant.
last-four-digits	Last four digits of customer credit card number.
bin	Bank BIN of customer credit card number.
card-type	Type of customer credit card (VISA, MASTERCARD, etc).
gate-partial-reversal	Processing gate support partial reversal (enabled or disabled).
gate-partial-capture	Processing gate support partial capture (enabled or disabled).
transaction-type	Transaction type (sale, reversal, capture, preauth).
processor-rrn	Bank Receiver Registration Number.
processor-tx-id	Acquirer transaction identifier.
receipt-id	Electronic link to receipt https://gate.payneteasy.com/paynet/view-receipt/ENDPOINTID/receipt-id/
cardholder-name	Cardholder name.
card-exp-month	Card expiration month.
card-exp-year	Card expiration year.
card-hash-id	Unique card identifier to use for loyalty programs or fraud checks.
card-country-alpha-three-code	Three letter country code of source card issuer. See Country Codes for details
email	Customer e-mail.
bank-name	Bank name by customer card BIN.
terminal-id	Acquirer terminal identifier to show in receipt.
paynet-processing-date	Acquirer transaction processing date.
approval-code	Bank approval code.
order-stage	The current stage of the transaction processing. See Order Stage for details.
loyalty-balance	The current bonuses balance of the loyalty program for current operation. if available
loyalty-message	The message from the loyalty program. if available
loyalty-bonus	The bonus value of the loyalty program for current operation. if available
loyalty-program	The name of the loyalty program for current operation. if available
descriptor	Bank identifier of the payment recipient.
error-message	If status in declined, error, filtered this parameter contains the reason for decline
error-code	The error code is case status in declined, error, filtered.
by-request-sn	Serial number from status request, if exists in request. Warning parameter amount always shows initial transaction amount, even if status is requested by-request-sn.
verified-3d-status	See 3-D Secure Status List for details
verified-rsc-status	See Random Sum Check Status List for details
transaction-date	Date of final status assignment for transaction.

Order Status Response Example ¶

type=status-response
&serial-number=00000000-0000-0000-0000-0000005b5eec
&merchant-order-id=6132tc
&processor-tx-id=9568-47ed-912d-3a1067ae1d22
&paynet-order-id=161944
&status=approved
&amount=7.56
&descriptor=no
&gate-partial-reversal=enabled
&gate-partial-capture=enabled
&transaction-type=cancel
&receipt-id=2050-3c93-a061-8a19b6c0068f
&name=FirstName
&cardholder-name=FirstName
&card-exp-month=3
&card-exp-year=2028
&email=no
&processor-rrn=510458047886
&approval-code=380424
&order-stage=cancel_approved
&last-four-digits=1111
&bin=444455
&card-type=VISA
&phone=%2B79685787194
&bank-name=UNKNOWN
&paynet-processing-date=2015-04-14+10%3A23%3A34+MSK
&by-request-sn=00000000-0000-0000-0000-0000005b5ece
&card-hash-id=1569311
&verified-3d-status=AUTHENTICATED
&verified-rsc-status=AUTHENTICATED
&transaction-date=2023-01-10+12%3A46%3A28+MSK

Status request authorization through control parameter ¶

The checksum is used to ensure that it is Merchant (and not a fraudster) that sends the request to Payneteasy. This SHA-1 checksum, the parameter control, is created by concatenating of the values of the parameters in the following order:

login
client_orderid
orderid
merchant_control

For example assume the following values are corresponds the parameters above:

Parameter Name	Parameter Value
login	cool_merchant
client_orderid	5624444333322221111110
orderid	9625
merchant_control	r45a019070772d1c4c2b503bbdc0fa22

The complete string example may look as follows:

cool_merchant56244443333222211111109625r45a019070772d1c4c2b503bbdc0fa22

Encrypt the string using SHA-1 algorithm. The resultant string yields the control parameter which is required for authorizing the callback. For the example control above will take the following value:

c52cfb609f20a3677eb280cc4709278ea8f7024c

Order status Debug ¶

endpointid or groupid		input your ENDPOINTID or ENDPOINTGROUPID
login
client_orderid		input your Invoice Number
orderid
merchant_control		input your Control Key
by-request-sn

String to sign

Signature

Quick search

Card To Card Transfer¶