Asynchronous
In an asynchronous workflow, the customer completes a payment verification step and is then redirected to the merchantRedirectUrl. The merchant can verify the final payment status using the TWPayz API.
The initial request must contain all the required information:
- - authentication credentials
- - mode, brand , type and amount of transaction
- - merchantRedirectUrl
You can perform the following types of initial payments using our Asynchronous Workflow REST API.
Preauthorization (PA):
A Preauthorization (PA) transaction reserves funds without immediately capturing them. Send a POST request to /transactionServices/REST/v1/payments with paymentType=PA.
The authorized funds can be captured later using the TWPayz Backoffice APIs.
Debit (DB):
A Debit (DB) transaction authorizes and captures funds in a single step. Send a POST request to /transactionServices/REST/v1/payments with paymentType=DB.
Once authorized, the transaction is captured immediately.
In our API Specifications you can find a full list of parameters that can be sent in the initial request.
Workflow
1. Send an Initial Payment
After submitting the request to the TWPayz server, you will receive a response containing the transaction result and related transaction details.
2. Redirect the customer
After receiving a successful response, redirect the customer to the TWPayz checkout page to complete the payment process.
3. Get the payment status
After the payment is completed, verify the transaction status using the payment response or the relevant TWPayz API.
1. Send an Initial Payment
To start the payment process, send an initial server-to-server payment request to the TWPayz platform.
Note: The merchantRedirectUrl must be URL-encoded before sending the request.
Request specification:
| Parameter | Description | Format | Required |
|---|---|---|---|
| authentication.memberId | Unique merchant member ID provided by TWPayz. | N10 [0-9]{1,10} |
Yes |
| authentication.checksum | MD5 checksum generated using merchant credentials for request authentication. | AN32 [a-fA-F0-9]{32} |
Yes |
| authentication.terminalId | Merchant terminal ID assigned by TWPayz. | N10 [0-9]{1,10} |
Yes |
| merchantTransactionId | Unique transaction reference generated by the merchant. | AN100 [a-zA-Z0-9\\p{Space}\\-_.]{1,100} |
Yes |
| amount | Transaction request amount. Decimal format needs to be followed | N13
[0-9]{1,10}\.[0-9]{2} |
Yes |
| currency | Transaction request currency | A3
[a-zA-Z]{3} |
Yes |
| shipping.country | Country of the shipping address. | AN3 [a-zA-Z0-9]{2,3} |
Yes |
| shipping.city | City of the customer's shipping address. | AN50 [a-zA-Z0-9\\\\#&\\p{Space}\\p{L}\\p{M}\\-;.,~`/%$#@ ]{0,50} |
Yes |
| shipping.state | State or region of the customer's shipping address. | AN50 [\\ra-zA-Z0-9\\\\!@#$*%^&{}\\[\\]()_+\\p{L}\\p{M}\\-=,.~'` ]{0,50} |
Yes |
| shipping.postcode | Postal code/ Zip code of the customer's shipping address. | AN9 [A-Za-z0-9]{2,9} |
Yes |
| shipping.street1 | Building name, and or street name of the customer's shipping address. | AN150 [a-zA-Z0-9\\p{Space}\\,]+ |
Yes |
| customer.telnocc | Country code of the customer. | N4 [0-9]{1,4} |
Yes |
| customer.phone | Phone number of the customer. | N24 [0-9\+-. ]{6,24} |
Yes |
| customer.email | Email address of the customer. | AN100 [A-Za-z0-9._%'-]+@[A-Za-z0-9.-]+\\.[a-zA-Z]{2,100} |
Yes |
| customer.givenName | First name of the customer. | AN [a-zA-Z0-9\\p{Space}\\,.:'"-=+)({}[]]+ |
Yes |
| customer.surname | Last name or surname of the customer. | AN [a-zA-Z0-9\\p{Space}\\,.:'"-=+)({}[]]+ |
Yes |
| customer.ip | IP address of the customer. | AN255 (?:(?:25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)\\.){3}(?:25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?) |
Yes |
| paymentBrand | Type of Card while placing the transaction. | AN20
[a-zA-Z0-9] {1,20} |
Yes |
| paymentMode | It specifies the mode of payment for the request | AN10
[a-zA-Z0-9] {1,10} |
Yes |
| paymentType | The payment type for the request. You can send a transaction
requests with one of the following types:
|
A2 ((PA|DB|)) |
Yes |
| merchantRedirectUrl | This URL will receive the result of an asynchronous payment.
It must be sent URL encoded. |
AN2048
([htpfs]{3,5}\\:?\\/\\/[\\w\\.\\:\\/]*\\??[a-zA-Z0-9]*) |
Yes
|
| notificationUrl | Merchant callback URL for payment notifications. | AN2048 ([htpfs]{3,5}\\:?\\/\\/[\\w\\.\\:\\/]*\\??[a-zA-Z0-9]*) |
Yes |
| tmpl_amount | Template amount used for recurring transactions. | N13 [0-9]{1,10}\\.[0-9]{2} |
No |
| tmpl_currency | Template currency used for recurring transactions. | A3 [A-Z]{3} |
No |
Response specification:
| Parameter | Description | Format | Required |
|---|---|---|---|
| paymentId | Unique payment identifier generated by TWPayz. | N10 [0-9] |
Yes |
| paymentBrand | Type of Card while placing the transaction. | A20 [a-zA-Z0-9] {1,20} |
Yes |
| paymentType | The payment type for the request. You can send a transaction requests with one of the following types:
|
A2 ((PA|DB|)) |
Yes |
| paymentMode | It specifies the mode of payment for the request | A10 [a-zA-Z0-9] {1,10} |
Yes |
| amount | Transaction request amount. Decimal format needs to be followed. | N13 [0-9]{1,10}\.[0-9]{2} |
Yes |
| currency | Currency of the transaction. | A3 [a-zA-Z\\p{Space}\\,]+ |
Yes |
| result.code | Response code indicating the transaction status. | AN11 [0-9\.]{2,11} |
Yes |
| result.description | Description corresponding to the response code. | AN255 [a-zA-Z0-9\\p{Space}\\,]+[a-zA-Z0-9\\p{Space}\\,]+ |
Yes |
| timestamp | Shows at what time the transaction has been placed. | date yyyy-MM-dd hh:mm:ss |
Yes |
| transactionStatus | Status of the transaction processed. Possible values are, ‘Y’ – Successfully processed ‘N’ – Failed ‘P’ – Pending ‘3D’ – Pending for 3D authentication ‘C’ – Cancelled |
A2 [Y|N|P|3D|C] |
Yes |
| redirect.url | With this URL shopper gets redirected for the further transaction. | AN2048 ([htpfs]{3,5}\\:?\\/\\/[\\w\\.\\:\\/]*\\??[a-zA-Z0-9]*) |
Yes |
Sample Request
Sample Response
Hashing Rule
TWPayz is supporting MD5 Cryptographic Hash for the authenticity of payment request send to the server.
Below is the description of fields used for generating checksum:
- memberId <Merchant ID as shared by TWPayz>
- secureKey <Secure Key that can be generated through TWPayz's dashboard>
- merchantTransactionId <Unique transaction ID provided by merchant>
- amount <Amount of transaction>
How to generate Checksum?
Checksum has to be calculated with following
combination.
<memberId>|<secureKey>|<merchantTransactionId>|<amount>
Sample Code
2. Redirect the Customer
Redirect the customer to the redirect.url received in the initial payment response. If additional parameters are provided, submit them using the POST method.
After payment processing, the customer is redirected to the merchantRedirectUrl along with a resourcePath parameter, which can be used to retrieve the transaction status.
Sample Request
Sample response
3. Get Payment Status
To retrieve the payment status, send a GET request to baseUrl + resourcePath along with the required authentication parameters.
resourcePath example:
resourcePath=/transactionServices/REST/v1/payments/{id}
Sample Request
Sample Response
Hashing Rule for Get Status
TWPayz is supporting MD5 Cryptographic Hash for the authenticity of payment request send to the server.
Below are the description of fields used for generating checksum:
- memberId <Merchant ID as shared by TWPayz>
- secureKey <Secure Key that can be generated through TWPayz's dashboard>
- paymentId <Id of previous transaction>
How to generate Checksum?
Checksum has to be calculated with following combination & needs to be send
along with the authentication parameters in each server-to-server request:
<memberId>|<secureKey>|<paymentId>
Standard Notification/ Callback
Checksum has to be calculated with following combination.
<paymentId>|<merchantTransactionId>|<amount>|<short status of
transaction>|<secret key>
Example :
77251|011E1D8A5C034|156.00|N|<merchant secret key>
Sample Code
Below are the list of payment brands for asynchronous workflow which requires the payment data.