Synchronous
In a synchronous workflow, payment details are sent directly to the TWPayz server along with the initial payment request, allowing the transaction to be processed immediately and the result returned in real time.
Your request has to include the following information:
- - Authentication Credentials
- - Type and amount of transactions
- - Payment information like card details, Payment Mode and Payment Brand
For our Synchronous Workflow REST API you can use the following types of initial payments:
Preauthorization (PA):
Send a POST request to /transactionServices/REST/v1/payments with paymentType=PA to create a preauthorization transaction.
After a successful preauthorization, the transaction can be captured later using the TWPayz Backoffice APIs
Debit (DB):
A Debit transaction authorizes and captures the payment amount in a single step, enabling immediate processing and settlement of the transaction.
To initiate a debit transaction, send a POST request to the following REST API endpoint: /transactionServices/REST/v1/payments
For debit transactions, the paymentType parameter must be set to DB.
With a successful Debit (DB) request, the transaction is authorized and captured immediately, eliminating the need for a separate capture operation.
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 |
| orderDescriptor | Description of the order or transaction. | AN255 [a-zA-Z0-9\\p{Space}\\,.:'&()/_-]{1,255} |
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 |
| customer.birthDate | Birth date of the customer in the format YYYYMMDD. | AN8 {19|20)([0-9]{2})(0[1-9]|1[0-2])(0[1-9]|1[0-9]|2[0-9]|3[0-1]} |
Yes |
| customer.customerId | Unique customer identifier assigned by the merchant. | AN100 [a-zA-Z0-9\\-_]{1,100} |
Yes |
| card.number | Customer card number (PAN). | N19 [0-9]{13,19} |
Yes |
| card.expiryMonth | Card expiry month. | N2 (0[1-9]|1[0-2]) |
Yes |
| card.expiryYear | Card expiry year. | N4 [0-9]{4} |
Yes |
| card.cvv | Card verification value (CVV/CVC). | N4 [0-9]{3,4} |
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 |
| recurringType | Type of recurring transaction. | AN20 (INITIAL|REPEATED) |
No |
| createRegistration | Indicates whether card registration should be created. | Boolean (true|false) |
No |
| merchant_website_url | Merchant website URL. | AN2048 ([htpfs]{3,5}\\:?\\/\\/[\\w\\.\\:\\/]*\\??[a-zA-Z0-9]*) |
Yes |
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 |
| descriptor | Transaction descriptor displayed for the payment. | AN127 [a-zA-Z0-9\\p{Space}\\,]+[a-zA-Z0-9\\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 |
| card.bin | First six digits (BIN) of the payment card. | N6 [0-9]{6} |
Yes |
| card.last4Digits | Last four digits of the payment card. | N4 [0-9]{4} |
Yes |
| card.holder | Name of the customer on card. | AN255 [a-zA-Z0-9] |
Yes |
| card.expiryMonth | Expiry month on card.. | N2 [0-9] |
Yes |
| card.expiryYear | Expiry year on card. | N4 [0-9] |
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 |
| merchantTransactionId | Unique ID sent at the time of transaction. | AN100 [.\\p[0-9a-zA-Z\\p{Space}\\-]{0,100} |
Yes |
| remark | Transaction remark from respective gateway. | AN255 [a-zA-Z0-9] |
Yes |
| currency | Currency of the transaction. | A3 [a-zA-Z\\p{Space}\\,]+ |
Yes |
| tmpl_currency | Currency of the customized amount to facilitate customer, template currency can be same as transaction currency, Accept only 3 character currency code in capital letters. | A3 [A-Z]{3} |
No |
| tmpl_amount | Customized amount of customer, template amount can be same as transaction amount. | N13 [0-9]{1,10}\\.[0-9]{2} |
No |
Sample Request
Sample Response
Hashing Rule
TWPayz uses MD5 cryptographic hashing to validate the authenticity of payment requests sent to the server. The generated hash value must be included in the request for verification.
Below is the description of fields use 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 prived by merchant>
- amount <Amount of transaction>
How to generate Checksum ?
Checksum has to be calculated with following combination and need to be send along with the authentication parameters in each server-to-server request:
<memberId>|<secureKey>|<merchantTransactionId>|<amount>
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
Payment Modes and Brands
Find below the list of payment modes and brands for synchronous workflow.
| Mode | Brand |
|---|