In Host-to-Host (H2H) payment gateway integrations, understanding the flow of transaction responses is critical for ensuring a smooth payment experience. Transactions can be processed either asynchronously or synchronously, depending on the type of transaction. Here, we will explore both flows using SALE3D, SALE, and SALE by token as examples, providing an overview of how responses and callbacks are handled.
Key Transaction Types
SALE3D, AUTH3D: Have an asynchronous flow.
SALE, SALE by token, AUTH by token: Have a synchronous flow.
H2H integration workflow
1. Asynchronous Flow: SALE3D and AUTH3D transactions
In the asynchronous flow, the transaction is not completed in a single step. SALE3D transactions are a good example of this process, as they require additional security steps through a 3D Secure procedure.
Step-by-Step Breakdown:
- API Response (Initial response)
When a SALE3D transaction is initiated via API request, the merchant receives an immediate API response, that includes the parameter `acs_url`. This URL is where the client must be redirected by merchant to complete the 3D Secure procedure:
Sample code of the SALE3D response in "application/json" format:
{
"api_version": 1,
"merchant_account": "Account_MP_TRX",
"sessionid": "543e2136-d46c-4d7d-a3b3-075cf9adkl21",
"transaction_unique_id": "sale3d_request",
"token": "5524fa52-75d8-4c7a-84ec-039d3097ab6g",
"reference": "S3FF0000000039FDAEGG",
"timestamp": 1638001694,
"authcode": "",
"eci": 5,
"acs_url": "https://acs.bank.com/authentication",
"authcode": "",
"status": "success",
"code": 0,
"message": "Transaction processed successfully"
}
In this API response:
- `"status": "success"` and `"code": 0` indicate that the flow is progressing correctly, but this is not the final status of the transaction. The transaction is still pending as the client needs to complete the 3D authentication.
- Client Redirection:
The client should be redirected by merchant to the `acs_url` to complete the 3D authentication (usually a page where the user confirms their identity with a password or a one-time code). After the 3D procedure, the client is redirected by Maxpay to the `redirect_url` provided in the original API request.
Once the client completes the 3D Secure authentication, the system sends a callback to the `callback_url` provided in the API request. This callback contains the final status of the transaction.
Example of the callback request to merchant in application/x-www-form-urlencoded format:
transactionId=hppS1513841180.7902mId3126aId1335
&reference=SLFF00000006CAAC0F1B
&uniqueUserId=auto_yJJj935t8kyUX55Q
&totalAmount=9.99
¤cy=USD
&transactionType=SALE3D
&status=success
&message=Transaction+processed+successfully
&code=0
&productList[0][productId]=2131
&productList[0][name]=My Product
&productList[0][amount]=9.99
&productList[0][currency]=USD
&convertedAmount=9.99
&convertedCurrency=USD
&checkSum=91935c8e71dcac1473d6613e62e0d84d039a075971efd1e11fb4901001938a365d2bee325793a
This final status in the callback confirms whether the payment has been completed successfully or not.
2. Synchronous Flow: SALE , SALE by Token and AUTH by token Transactions
In the synchronous flow, the entire transaction process is completed in a single step, and the final status is provided directly in the API response.
Step-by-Step Breakdown:
- API Response (Final Response):
When a SALE, SALE by token or AUTH by token transaction is initiated, the system processes the payment and returns a final status in the API response. This status informs the merchant whether the transaction was successful or failed.
Sample code of the SALE response in "application/json" format:
{
"api_version": 1,
"merchant_account": "Account_MP_TRX",
"sessionid": "543e2136-d46c-4d7d-a3b3-075cf9adkl01",
"transaction_unique_id": "sale_request",
"token": "5524fa52-75d8-4c7a-84ec-039d3097ab6f",
"reference": "SLFF0000000039FDAEAB",
"timestamp": 1618001694,
"authcode": "",
"status": "success",
"code": 0,
"message": "Transaction processed successfully"
}
HPP integration workflow
For merchants using Hosted Payment Page (HPP) integration, the process is slightly different. Instead of receiving real-time API responses, merchants receive information exclusively via callbacks. This means that after the transaction is processed (either synchronously or asynchronously), the system sends a callback to the merchant's `callback_url` set up in Mportal, containing the final transaction status.
Example of the callback 2.0 request to merchant in application/json format:
X_SIGNATURE: c37484fc04e55e4a17ca3389f20010608b8822935badaac7275604854c6b5bf9
{
"uniqueTransactionId":"hpp180926125439m7059a4040uf62e5bb29b97bc",
"reference":"SLFF0000000040598D81",
"uniqueUserId":"auto_AH1IqGXIu555VyLF",
"totalAmount":5,
"currency":"USD",
"transactionType":"SALE",
"status":"success",
"message":"Transaction processed successfully",
"code":0,
"productList":[
{
"productId":"p_6e30432104",
"name":"Trial product without description",
"amount":5,
"currency":"USD"
}
],
"testMode":"0"
}
For 3D flow, the client is redirected by Maxpay to acs_url without the merchant's involvement and then returned to either success_url or decline_url set up in Mportal.