Chapter 5 - XML Payments Integration | Nuvei Technologies

It is also possible to send XML directly to the Nuvei payment server. This is useful in a scenario where your application needs full control of the payment process or where you wish to collect account details on your site.

The XML XSD description for all of the packet types below is available there:

https://testpayments.nuvei.com/merchant/gateway.xsd

Note that all data sent to us should be correctly uncoded using UTF-8 as the character encoding.

5.1 Request Types link

5.1.1 XML ACH Sale link

The following is a simple example of a payment via an XML POST:

XML

<?xml version="1.0" encoding="UTF-8"?>
<PAYMENTACH>
	<ORDERID>3472151837</ORDERID>
	<TERMINALID>2366006</TERMINALID>
	<AMOUNT>2.09</AMOUNT>
	<CURRENCY>USD</CURRENCY>
	<DATETIME>22-02-2017:18:02:31:849</DATETIME>
	<TERMINALTYPE>2</TERMINALTYPE>
	<SEC_CODE>CCD</SEC_CODE>
	<ACCOUNT_TYPE>CHECKING</ACCOUNT_TYPE>
	<ACCOUNT_NUMBER>2387654376</ACCOUNT_NUMBER>
	<ROUTING_NUMBER>101000187</ROUTING_NUMBER>
	<ACCOUNT_NAME>Billy Joel</ACCOUNT_NAME>
	<CHECK_NUMBER>1234</CHECK_NUMBER>
	<ADDRESS1>7th Avenu, 77</ADDRESS1>
	<ADDRESS2>5th Avenu, 13</ADDRESS2>
	<CITY>New York</CITY>
	<REGION>A1</REGION>
	<POSTCODE>117898</POSTCODE>
	<COUNTRY>US</COUNTRY>
	<PHONE>9563343234</PHONE>
	<IPADDRESS>192.168.0.1</IPADDRESS>
	<EMAIL>asd@asd.org</EMAIL>
	<DESCRIPTION>test</DESCRIPTION>
	<DL_STATE>NY</DL_STATE>
	<DL_NUMBER>4353446</DL_NUMBER>
	<HASH>ceb3fded5144eec6a8e821014f2e66f5</HASH>
</PAYMENTACH>

Request fields:

Field Name	Required	Description
ORDERID	Y	A unique identifer for the order created by the merchant. (Max 12 Characters).
TERMINALID	Y	A Terminal ID provided by Nuvei. NB – Please contact Nuvei to be issued with a test terminal ID.
AMOUNT	Y	The amount of the transaction as a 2 digit decimal
CURRENCY	Y	Must be "USD".
DATETIME	Y	Format: DD-MM-YYYY:HH:MM:SS:SSS.
TERMINALTYPE	Y	The type of the terminal: MOTO (Mail Order/Telephone Order) 2 – eCommerce
SEC_CODE	Y	See section 2.4 above.
ACCOUNT_TYPE	Y	CHECKING or SAVINGS. Required if ACH_SECURE=N.
ACCOUNT_NUMBER	Y	The ACH account number
ROUTING_NUMBER	Y	The ACH routing number.
ACCOUNT_NAME	Y	The customer’s frst and last name.
CHECK_NUMBER	N	Check number
ADDRESS1	N	First line of customer’s address.
ADDRESS2	N	Second line of customer’s address.
CITY	N	Customer’s home city.
REGION	N	Customer’s region.
POSTCODE	N	Customer’s post code.
COUNTRY	N	Customer’s country.
PHONE	N	Customer’s phone number.
IPADDRESS	N	Customer’s IP address.
EMAIL	N	Customer’s e-mail address.
DESCRIPTION	N	Optional transaction description feld.
DL_STATE	N	Customers driving licence state.
DL_NUMBER	N	Customers driving licence number.
HASH	Y	An SHA-512 HASH. See Note 1 below.

For testing, this XML is posted to:

https://testpayments.nuvei.com/merchant/xmlpayment

A response for this transaction would be:

XML

<?xml version="1.0" encoding="UTF-8" ?>
<PAYMENTACHRESPONSE>
	<UNIQUEREF>G6VPOBK1E7</UNIQUEREF>
	<RESPONSECODE>E</RESPONSECODE>
	<RESPONSETEXT>ACCEPTED</RESPONSETEXT>
	<APPROVALCODE>Success</APPROVALCODE>
	<DATETIME>2017-03-22T17:19:38</DATETIME>
	<HASH>a6cd3355928183ccb82dd8185fcfd39</HASH>
</PAYMENTACHRESPONSE>

Payment request fields description:

The following fields are returned in the response:

Field Name	Description
UNIQUEREF	Generated reference that should be stored for tracking and remote XML refunding.
RESPONSECODE	E:Initial Approval or D:Declined.
RESPONSETEXT	The text of the authorization.
APPROVALCODE	Original code provided by ACH JH as the authorization response.
DATETIME	The time of the transaction created by the bank. Format: YYYY-MM- DDTHH:MM:SS. Note that this is intentionally in a diferent format to the request timestamp to highlight the fact that it is a diferent time.
HASH	An SHA-512 HASH. See Note 2 below.

Notes:

1. The request SHA-512 HASH is generated using the following as an input string:

TERMINALID:ORDERID:AMOUNT:DATETIME:secret

For multi-currency Terminal IDs (see section 2.2 above) this should be:

TERMINALID:ORDERID:CURRENCY:AMOUNT:DATETIME:secret

2. The response SHA-512 HASH is generated using the following as an input string:

TERMINALID:ORDERID:UNIQUEREF:AMOUNT:DATETIME:RESPONSECODE:RESPONSETEXT:secret

For multi-currency Terminal IDs (see section 2.2 above ) this should be

TERMINALID:ORDERID:UNIQUEREF:CURRENCY:AMOUNT:DATETIME:RESPONSECODE: RESPONSETEXT:secret

Many code examples on how to generate an SHA-512 HASH can be found in the Internet. For assistance, please contact Nuvei.

3. In case you desire to inform your customer's email and desire to provide his/ her receipt in another language, you can use the Accept-Language parameter of the request to set language the customer should receive the receipt in. If the language informed is not supported, the Payment Gateway will use its default language (EN). Possible values are 'fr-FR' or even 'fr,en-US;q=0.9,en;q=0.8,ru;q=0.7,de;q=0.6,ru-RU;q=0.5,de-DE;q=0.4'.

Error handling

If there is an error processing the transaction, the error string is returned in an XML message with the simple:

XML

<ERROR>
	<ERRORCODE>E01</ERRORCODE>
	<ERRORSTRING>Invalid ACH Order ID</ERRORSTRING>
</ERROR>

The following felds are returned in the response:

5.1.2 Standard ACH Refunds link

Standard refunds can be be performed on any ACH payments in the Nuvei system, either in the Open Batch or Closed Batch. Partial refunds re not allowed.

The following is a simple example of a refund via an XML POST:

XML

<?xml version="1.0" encoding="UTF-8"?>
<REFUND>
	<UNIQUEREF>LS2O5CO1XB</UNIQUEREF>
	<TERMINALID>2366006</TERMINALID>
	<AMOUNT>3.45</AMOUNT>
	<DATETIME>24-01-2017:15:23:14:422</DATETIME>
	<HASH>e71b02501e7eb9b4cedaa955e5b86e11</HASH>
	<OPERATOR>opr</OPERATOR>
	<REASON>reason</REASON>
</REFUND>

For testing, this XML is posted to:

https://testpayments.nuvei.com/merchant/xmlpayment

A response for this transaction would be:

XML

<REFUNDRESPONSE>
	<RESPONSECODE>E</RESPONSECODE>
	<RESPONSETEXT>ACCEPTED</RESPONSETEXT>
	<UNIQUEREF>KN5FQL15J6</UNIQUEREF>
	<DATETIME>24-01-2017:14:23:15:801</DATETIME>
	<HASH>c0b52adcce8a710df40bc68bf2dfe427</HASH>
</REFUNDRESPONSE>

The Nuvei payment system then handles subsequent payment settlement and storage.

The following is a description of each field:

Field Name	Required	Description
UNIQUEREF	Y	The UNIQUEREF for the original payment.
TERMINALID	Y	A Terminal ID provided by Nuvei. NB – Please contact Nuvei to be issued with a test terminal ID.
AMOUNT	Y	The amount of the refund transaction as a 2 digits decimal or an Integer value for JPY amounts.
DATETIME	Y	Format: DD-MM-YYYY:HH:MM:SS:SSS. HASH
	Y	An SHA-512 HASH. See note 1 below.
OPERATOR	Y	An identifer for who executed this transaction.
REASON	Y	The reason for the refund.

The following felds are returned in the response:

Field Name	Description
RESPONSECODE	E: Initial Approval (fnal approval for voided transaction) or D: Declined. If E is received, then fnal approval will be provided by background notifcation (except voided transaction).
RESPONSETEXT	The text of the authorization.
UNIQUEREF	The UNIQUEREF for this refund.
DATETIME	Format DD-MM-YYYY:HH:MM:SS:SSS.
HASH	An SHA-512 HASH. See note 2 below.

Notes:

1. The request SHA-512 HASH is generated using the following as an input string:

TERMINALID:UNIQUEREF:AMOUNT:DATETIME:secret

For multi-currency Terminal IDs (see section 2.2 above) this should be:

TERMINALID:UNIQUEREF:CURRENCY:AMOUNT:DATETIME:secret

2. The response SHA-512 HASH is generated using the following as an input string:

TERMINALID:ORDERID:UNIQUEREF:AMOUNT:DATETIME:RESPONSECODE:RESPONSETEXT:secret

For multi-currency Terminal IDs (see section 2.2 above ) this should be:

TERMINALID:ORDERID:UNIQUEREF:CURRENCY:AMOUNT:DATETIME:RESPONSECODE: RESPONSETEXT:secret

n.b. The response UNIQUEREF is to be used here.

3. In case you desire to inform your customer’s email to provide his/ her receipt in another language, you can use the Accept-Language parameter of the request to set language the customer should receive the receipt in. If the language informed is not supported, the Payment Gateway will use its default language (EN). Possible values are 'fr-FR' or even
'fr,en-US;q=0.9,en;q=0.8,ru;q=0.7,de;q=0.6,ru-RU;q=0.5,de-DE;q=0.4'.

Developers

Chapter 5 - XML Payments Integration

5.1 Request Types link

5.1.1 XML ACH Sale link

5.1.2 Standard ACH Refunds link

Need Help?