3D Flow
In a 3D workflow the account holder has to verify the payment. Once the account holder verifies the payment he/she is redirected back to the merchantRedirectUrl. The merchant then can query the status of payment.
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):
Preauthorization request has to be sent to our REST endpoint i.e. /transactionServices/REST/v1/payments using POST method.
The paymentType for this request will be PA.
You can also place a capture transaction request against a successful PA using our Backoffice APIs.
Debit (DB):
With the DB request a successfully authorized transaction gets captured immediately.
Debit request has to be sent to our REST endpoint i.e. /transactionServices/REST/v1/payments using POST method.
The paymentType for this request will be DB.
In our API Specifications you can find a full list of parameters that can be sent in the initial request.
Workflow
1. Send a 3D Payment
After you send the request parameters server-to-server you receive the redirected information with all the parameters for ACS check.
2. Redirect the customer
Redirect the consumer to the ACS page with provided parameters.
3. Get the payment status
Now you can check if the payment was successful.
1. Send a 3D Payment
To start the process, the merchant has to send a server-to-server initial payment request. Here merchantRedirectUrl has to be url-encoded.
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 |
| attemptThreeD |
|
AN10 [Direct|3D|Only3D] |
No |
| deviceDetails.user_Agent | Content of HTTP user-agent header. | AN [a-zA-Z0-9\\p{Space}\\,.;:'"*-=+)({}[]]+ |
Conditional |
| deviceDetails.browserLanguage | Language of Cardholder Browser. For e.g en-US = English. Returned from navigator.language property. | A [a-zA-Z_-] |
Conditional |
| deviceDetails.browserTimezoneOffset | Time difference between UTC time and the Cardholder browser local time, in minutes | N [-+?][0-9] |
Conditional |
| deviceDetails.browserColorDepth | Value representing the bit depth of the colour palette for displaying images, in bits per pixel. Obtained from Cardholder browser using the screen.colorDepth property | N [0-9] |
Conditional |
| deviceDetails.browserAcceptHeader | Content of HTTP Accept header. | AN [a-zA-Z0-9\\p{Space}\\,.:'"*-=+)({}[]]+ |
Conditional |
| deviceDetails.browserScreenHeight | Total height of the Cardholder’s screen in pixels. Value is returned from the screen.height property. | N [0-9] |
Conditional |
| deviceDetails.browserScreenWidth | Total height of the Cardholder’s screen in pixels. Value is returned from the screen.width property. | N [0-9] |
Conditional |
| deviceDetails.browserJavaEnabled | Boolean that represents the ability of the cardholder browser to execute Java. Value is returned from the navigator.javaEnabled property | A5 true/false |
Conditional |
| 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 |
| 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 |
| 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 |
| 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 |
| redirect.url | With this URL shopper gets redirected for the further transaction. | AN2048 ([htpfs]{3,5}\\:?\\/\\/[\\w\\.\\:\\/]*\\??[a-zA-Z0-9]*) |
Conditional |
| redirect.method | Redirect method can be GET/POST. By default the method is POST. | A10 [a-zA-Z] |
Conditional |
| redirect.target | The target can be blank/_self. blank opens the linked document in a new window or tab whereas, _self opens the linked document in the same frame as it was clicked. By default the target is blank. | A10 [a-zA-Z] |
Conditional |
| redirect.parameters[n].name | List of parameter names for the redirect.url. The corresponding parameter value is the same parameter number ending with .value like described in the line below. The actual return format is JSON as shown in the example snippet below. | AN255 [a-zA-Z0-9\\p{Space}\\,]+ |
Conditional |
| redirect.parameters[n].value | The parameter values corresponding to the names as described above. | AN255 [a-zA-Z0-9\\p{Space}\\,]+ |
Conditional |
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 TWPayzTWPayz>
- 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 & needs to be send along with the authentication parameters in each server-to-server request:
<memberId>|<secureKey>|<merchantTransactionId>|<amount>
Sample Code
2. Redirect the Customer
The account holder has to be redirected to redirect.url received in the initial payment response. If any parameters are present in the initial payment response than they should be POST in the redirect. If not, it’s enough to forward it straight to the redirect.url.
Once the payment has been processed, the customer is redirected to your merchantRedirectUrl along with a POST parameter resourcePath.
Sample Request
Sample Response
3. Get Payment Status
To get the status of the payment you have to use a GET request. The request goes to the baseUrl + resourcePath and includes the 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.
<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
Payment Modes and Brands
Below are the list of payment brands for asynchronous workflow which requires the payment data.