1.1.5. Return Transactions

Return transaction diagram

Merchant -> "XPATE": Return request
activate "XPATE"
"XPATE" --> Merchant: Order ID

"XPATE" -> Acquirer: Process refund
activate Acquirer

Merchant -> "XPATE": Get status by Order ID

Acquirer --> "XPATE": Processing result
deactivate Acquirer

"XPATE" --> Merchant: Final status
deactivate "XPATE"

Return request Merchant sends Return request to XPATE server with specified parameters described in Return Request Parameters.
Order ID XPATE server sends back the response. Merchant starts polling for status with given orderid as described in Order status asynchronous call.
Process refund XPATE server determines the actual type of Return transaction(Cancel or Reversal) depending o the type of initial sale transaction. XPATE server forwards the appropriate request to bank acquirer asynchronously. The bank starts processing the transaction.
Get status by Order Id Merchant is polling for status with given orderid as described in Order status asynchronous call.
Processing result The bank responds to XPATE server with approve or decline for requested return transaction.
Final Status XPATE server returns status to Merchant through Order status asynchronous call.

Process Return transaction

For integration purposes use staging environment sandbox.sg.xpate.com instead of production gate.sg.xpate.com. Return API call returns money back to the customer. For Preauth it makes Cancel transaction, for Capture and SaleReversal. Void API call excludes transaction from clearing. Void transaction is always the result of this call. Void might not be supported by your acquirer, ask manager for details. Return and Void API calls are initiated through HTTPS POST request by using URL in the following format:

Return transaction request URL

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

https://gate.sg.xpate.com/paynet/api/v2/return/ENDPOINTID – for return transaction
https://gate.sg.xpate.com/paynet/api/v2/void/ENDPOINTID – for void transaction

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

https://gate.sg.xpate.com/paynet/api/v2/return/group/ENDPOINTGROUPID – for return transaction
https://gate.sg.xpate.com/paynet/api/v2/void/group/ENDPOINTGROUPID – for void transaction

Return Request Parameters

Return Request Parameter Length/Type Comment Necessity*
login 20/String Merchant login name Mandatory
orderid 20/String Unique identifier of Sale (SMS) or Preauth/Capture (DMS) order assigned by XPATE system and returned in the order_id response parameter. Please note that return can be made On a preauth transaction if the relative capture transaction has not taken place yet; or on a capture transaction. In the latter case, processing of a return on a preauth transaction is restricted. For cashier integration (Parallel form) send return request to master ENDPOINTID or ENDPOINTGROUPID with auxiliary orderid value in this parameter Mandatory
client_orderid 128/String Unique merchant identifier of Sale (SMS) or Preauth/Capture (DMS) transaction which is send to XPATE system in the client_orderid parameter Mandatory
amount 10/Numeric This optional parameter specifies amount to be reversed. 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. If this parameter is omitted, initial transaction is reversed as a whole. Amount only makes sense for reversals, not cancels. Amount cannot exceed initial transaction amount. Please note that you MUST specify currency if you specify amount! Not supported for void transactions Mandatory
currency 3/String Currency in which amount is specified (three-letter currency code). Valid parameter values are: USD for US Dollar EUR for European Euro. Not supported for void transactions Conditional
control 128/String Checksum used to ensure that it is Merchant (and not a fraudster) that initiates the return request. This is SHA-1 checksum of the concatenation login + client_orderid + orderid + merchant-control if amount is not specified, and login + client_orderid + orderid + amount_in_cents + currency + merchant-control if amount is specified Mandatory
comment 50/String A brief description of reason Mandatory

Please note the following characters must be escaped in the parameter values: & + .

Return Response

Return 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 XPATE
merchant-order-id Merchant order id
serial-number Unique number assigned by XPATE server to particular request from the Merchant
end-point-id Entry point used for processing this transaction
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

Return Response Example

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

Return Request Postman Collection

Return Request Debug

endpointid or groupid input your ENDPOINTID or ENDPOINTGROUPID
login
client_orderid input your Invoice Number
orderid
amount
currency
merchant_control input your Control Key
comment

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 XPATE server and order id is returned, Merchant should poll for transaction status. When transaction is processed on XPATE 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.sg.xpate.com instead of production gate.sg.xpate.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.sg.xpate.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.sg.xpate.com/paynet/api/v2/status/group/ENDPOINTGROUPID

Order status call parameters

Status call 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 XPATE
by-request-sn Serial number assigned to the specific request by XPATE. If this field exist in status request, status response return for this specific request
control Checksum used to ensure that it is XPATE (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

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 the transaction is charged in (three-letter currency code). Example of valid parameter values are: USD for US Dollar EUR for European Euro
paynet-order-id Order id assigned to the order by XPATE
merchant-order-id Merchant order id
phone Customer phone
serial-number Unique number assigned by XPATE 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 Retrieval Reference Number
processor-tx-id Acquirer transaction identifier
receipt-id Electronic link to receipt https://gate.sg.xpate.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
card-country-alpha-three-code Three letter country code of card issuer. See Country Codes for details
total-reversal-amount Total amount of processed reversals
reversal-amount The amount of the last processed reversal
email Customer e-mail
bank-name Bank name by customer card BIN
auth-response-code Response code used in Iso8583 protocol. Only returned in specific cases
terminal-id Acquirer terminal identifier to show in receipt
paynet-processing-date System transaction processing date
acquirer-processing-date Acquirer transaction processing date
approval-code Bank approval code
order-stage The current stage of the transaction processing. See Order Stage
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 Identifier of the used processing channel. In some cases can contain bank identifier of the payment recipient
original-gate-descriptor Original descriptor set on the gate
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
merchantdata Custom information provided by merchant in initial transaction request
purpose Destination of payment sent by merchant in initial request
eci Electronic Commerce Indicator of 3-D Secure authentication
processor-auth-credit-code Approval credit code. Only returned in specific cases
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
processor-credit-rrn Retrieval Reference Number for credit transaction
processor-credit-arn Acquirer card reference number for credit transaction
processor-debit-arn Acquirer card reference number for debit transaction
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)
initial-amount Amount, set in initiating transaction, without any fees or commissions. This value can’t change during the transaction flow

Order Status Response Example

type=status-response
&serial-number=00000000-0000-0000-0000-0000005b5ef2
&merchant-order-id=423432-324
&processor-tx-id=1428585590552
&paynet-order-id=159874
&status=approved
&amount=390000.00
&descriptor=no
&original-gate-descriptor=test 12345678 3Ds Bank
&gate-partial-reversal=enabled
&gate-partial-capture=enabled
&transaction-type=fraud
&receipt-id=2438-3c9f-a299-f185e639d827
&name=Nikolay+Popov
&cardholder-name=Nikolay+Popov
&card-exp-month=8
&card-exp-year=2017
&email=alex
&processor-rrn=509995959724
&approval-code=825335
&order-stage=reversal_approved
&last-four-digits=1111
&bin=444455
&card-type=VISA
&phone=%2B79636910155
&bank-name=UNKNOWN
&terminal-id=12345678
&paynet-processing-date=2015-04-09+16%3A14%3A46+MSK
&card-hash-id=1569311
&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
&initial-amount=390000.00

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 XPATE. This SHA-1 checksum, the parameter control, is created by concatenation of these parameters values in the following order:

  • login
  • client_orderid
  • orderid
  • merchant_control

For example, assume these parameters have the values as listed below:

Parameter Description
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 Postman Collection

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