Get started
API Endpoint
TEST https://targetURL/ -- Provided By URWAY
LIVE https://targetURL/ -- Provided By URWAY
URWAY payment integration kit allows merchants to instantly collect payments from their users using various payment modes like Credit Cards, Debit Cards, Wallet, Payout etc. The URWAY payment integration supports a seamless payment experience on Merchant platform, while protecting Merchant application from payment frauds and complexity related to various regulations.
Testing and Production Environment
URWAY test and production environments are separate. Merchants need an active URWAY account to use the test environment and production environment. Merchants will have to log in to their URWAY Dashboard account and get the API credentials for using these environments. All transactions initiated by the merchant on our test environment are not processed. Test environment is strictly for testing the request and response functions. After successfully testing the integration, merchant can move to the production environment by changing the URL.
sample Payment Objects:
{
"trackid": "",// Order ID
"terminalId": "*****",// Provided by URWAY
"action": "", //refer the table below
"customerEmail" : "customer@mail.com",
"merchantIp": "*.*.*.*", // Merchant Server IP
"country": "SA", // country code
"password": "*****", // Provided by URWAY
"currency": "SAR", // Currency code
"amount": "20.00", // amount
"requestHash":
"********" // secret_key Per order Created using SHA256 online
}
Payment Objects
| Field | Type | Description |
|---|---|---|
| trackid | String | Order ID. |
| terminalId | String | Provided by URWAY. |
| password | String | Provided by URWAY. |
| action | String | Provided by URWAY |
| country | String | Ex : SA,UAE |
| currency | String | Currency code used for transaction.Ex:SAR,USD |
| amount | String | Please type-cast the amount to float type Example: 10.00 |
| requestHash | String | Hash is a crucial parameter – used specifically to avoid any tampering during the transaction |
| customerEmail | String | (Email of the customer |
| merchantIp | String | Merchant Server IP Address. Ex:201.201.10.10 |
metadata
Metadata Parameters :
{
"udf1": "",
"udf2": "",//Callback URL
"udf3": "",//AR / EN
"udf4": "", //refer the table below
"udf5": ""
}
| Field | Type | Description |
|---|---|---|
| Optional Prameters : * First_name * Last_name * Address * City * State * Zip * Phoneno | String | Details of the Customer. |
| udf1 | String | This parameter has been made for you to keep any information corresponding to the transaction,. |
| udf2 | String | Callback URL |
| udf3 | String | AR / EN |
| udf4 | String | User defined field 4 – Same description as UDF1 |
| udf5 | String | apple pay parameters |
create payment
Creating Payment Parameters :
{
"trackid": "10",
"terminalId": "****",
"action": "**",
"merchantIp": "*.*.*.*",
"password": "****",
"currency": "SAR",
"country": "SA",
"amount": "20",
"requestHash": "*****"
"udf1": "",
"udf2": "",//Callback URL
"udf3": "",//AR / EN
"udf4": "", //refer the table below
"udf5": ""
}
Step 1 - HASH Creation
Transaction Pre requisties. Hash Key : For Transation process you will require to generate a hash key, the format will be provided by URWAY.
Credentials and Request URL : For test credentials please do contact the URWAY Suport team
For registering Click : Register Here
Step 2 - Passing Parameters
After generating hash make JSON call to get transaction url. This URL will be provided by URWAY,it will be different for Testing and Production environment.
Values in Action Code Parameter
| Transaction Type | Action Code | Description |
|---|---|---|
| Purchase | 1 | An Automatic Capture |
| Refund | 2 | Refund of Purchase or Captured Transaction |
| Pre- Authorization | 4 | Transaction is Authorised. This will hold the amount. |
| Capture | 5 | 2nd Leg of Authorised Transaction, The amount is Captured. You Require to pass the transaction id received in First Leg of Authorization (Action : 4). This will release the held amount. |
| Void Authorization | 9 | Cancel of Authorised Transaction |
| Transaction Inquiry | 10 | Transaction inquiry |
Parameters in create payment Request
| Field | Type | Description |
|---|---|---|
| trackid | String | Order ID. |
| terminalId | String | Provided by URWAY. |
| password | String | Provided by URWAY. |
| action | String | Provided by URWAY |
| country | String | Ex : SA,UAE |
| currency | String | Currency code used for transaction.Ex:SAR,USD |
| merchantIp | String | Merchent Server IP |
| amount | String | Please type-cast the amount to float type Example: 10.00 |
| requestHash | String | Hash is a crucial parameter – used specifically to avoid any tampering during the transaction |
Link-based Payment
Link Based Payment Parameters :
{
"amount":"10.00",
"address":"Riyadh",
"customerIp":"10.10.10.10", // Customer IP
"city":"Riyadh", // customer address
"trackid":"***", // Order ID
"terminalId":"****", // Provided by URWAY
"action":"15",
"password":"******", // Provided by URWAY
"merchantIp":"10.10.10.10", // Merchant server IP
"requestHash":"*****-******", // secret_key Per order Created using SHA256 online
"country":"SA", // country code
"currency":"SAR", // Currency code
"customerEmail":"customer@gmail.com",
"zipCode":"410209",
"udf3":"",
"udf1":"",
"udf2":"",
"udf4":"",
"udf5":"
{\"paymentFor\":\"Shirt\",\"partialPaymentAllowed\":\"y\",
\"linkFlag\":\"a\",\"expiryDays\":\"4\",
\"smsLanguage\":\"AR\",\"contactNumber\":\"9665xxxxxxx\",
\"sendLinkMode\":\"2\",\"transactionType\":\"1\"}"
}
Response
{"result":"Successful","responseCode":"000","authcode":null,
"tranid":"***********","trackid":"1000","terminalid":"*****",
"udf1":"","udf2":null,"udf3":"","udf4":"",
"udf5":"{\"paymentFor\":\"Shirt\",\"partialPaymentAllowed\":\"y\",\"linkFlag\":\"a\",
\"expiryDays\":\"4\",\"smsLanguage\":\"AR\",\"contactNumber\":\"9665*******\",
\"sendLinkMode\":\"0\",\"transactionType\":\"1\"}","rrn":null,"eci":null,
"subscriptionId":null,"trandate":null,"tranType":null,"integrationModule":null,
"integrationData":null,"payid":null,"targetUrl":null,"postData":null,"intUrl":null,
"responseHash":"******************************************",
"amount":"10.00","cardBrand":"DEFAULT","maskedPAN":null,
"linkBasedUrl":"https://*******/IcjTxLUSXKWQ",
"sadadNumber":null,"billNumber":null,"cardToken":null}
Step 1 - HASH Creation
Create SHA256 Hash with below mention Parameters.Merchant needs to form the below hash sequence before posting the transaction to URWAY.
Step 2 - Passing Parameters
After generating hash make JSON call to get transaction url. This URL will be provided by URWAY,it will be different for Testing and Production environment.
Step 3 - Sending Notification
The mail will be send to the mail address mentioned in customerEmail field. If the email needs to be send from merchant platform the link received in response can be shared to customer.
Values in Action Code Parameter
| Transaction Type | Action Code | Description |
|---|---|---|
| Link Payment | 15 | Action code for creating Link-based Payment |
Parameters in create link based payment Request
| Field | Type | Description |
|---|---|---|
| trackid | String | Order ID. |
| terminalId | String | Provided by URWAY. |
| password | String | Provided by URWAY. |
| action | String | Provided by URWAY |
| country | String | Ex : SA,UAE |
| currency | String | Currency code used for transaction.Ex:SAR,USD |
| amount | String | Please type-cast the amount to float type Example: 10.00 |
| requestHash | String | Hash is a crucial parameter – used specifically to avoid any tampering during the transaction |
| udf5 | String | User defined field 5 – Please refer below table |
Values in UDF5 Parameter
| Parameter | Parameter DESCRIPTION |
|---|---|
| paymentFor | The description for payment.The payment purpose |
| partialPaymentAllowed | Value : Y or N. If customer requires to pay only partial amount Pass Y. |
| linkFlag | Value : A or D A: Create a Link D: Delete the generated Link |
| expiryDays | Value : 1 to 4 The days for expiry of link generated |
| smsLanguage | Value : EN - for english AR- for Arabic |
| contactNumber | Value : 966549212123 With international code without + |
| sendLinkMode | Value : 0 - only sms 1- only email 2- both email and sms (Note : If you require Only SMS please do inform URWAY with monthly limit) |
| transactionType | Value : 1 Purchase (Default) 2 - Authorization |
Transaction enquiry
Transaction enquiry Parameters :
{
"trackid": "************",
"terminalId": "****",
"action": "10",
"merchantIp": "*.*.*.*",
"password": "****",
"currency": "SAR",
"country": "SA",
"amount": "20",
"requestHash": "*****"
"udf1": "",
"udf2": "",//Callback URL
"udf3": "",// AR/ EN
"udf4": "", //refer the table below
"udf5": ""
}
Transaction inquiry is used for checking the status of the payment performed.
Parameters in Transaction inquiry Request
| Field | Type | Description |
|---|---|---|
| transid | String | This parameter is known as Transaction ID. This value is received when an Order is placed with the trackid. transid will be unique for each transaction. |
| trackid | String | Order ID. |
| terminalId | String | Provided by URWAY. |
| password | String | Provided by URWAY. |
| action | String | 10 |
| country | String | Ex : SA,UAE |
| currency | String | Currency code used for transaction.Ex:SAR,USD |
| amount | String | Please type-cast the amount to float type Example: 10.00 |
| requestHash | String | Hash is a crucial parameter – used specifically to avoid any tampering during the transaction |
| udf1 | String | If the merchant want to inquire about a particular Transaction type, he have to pass the action code.Refer Table below |
Values in UDF1 Parameter
| Field | Type | Description |
|---|---|---|
| Purchase | 1 | An Automatic Capture |
| Refund | 2 | Refund of Purchase or Captured Transaction |
| Authorization | 4 | Transaction is Authorised. This will hold the amount. |
| Capture | 5 | 2nd Leg of Authorised Transaction, The amount is Captured. You Require to pass the transaction id received in First Leg of Authorization (Action : 4). This will release the held amount. |
| Void Authorization | 9 | Cancel of Authorised Transaction |
Response
Response Parameter in Transaction Inquiry
{"result":"Successful","responseCode":"000","authcode":"315659",
"tranid":"2023717620519795287","trackid":"6781595593478",
"terminalid":"celeverAut","udf1":"","udf2":"2020612350872734303",
"udf3":"","udf4":"","udf5":"","rrn":"020612315659","eci":"02","subscriptionId":null,
"trandate":"2020-07-24 12:25:16:000550","tranType":"3D","integrationModule":null,
"integrationData":null,"payid":null,"targetUrl":null,"postData":null,"intUrl":null,
"responseHash":"caf195b888d2859c6981ae4d01ec613a1892508c91812c68448a3763a03a98cd",
"amount":"500.00","cardBrand":"MASTER","maskedPAN":"512345XXXXXX0008","cardToken":""}
URWAY will send the response back with transaction status. This is to be checked for the transaction response page of the Merchant.
URWAY will send the response back with transaction status. This is to be checked for the transaction response page of the Merchant.
Response Parameters of Payment Transaction
| Variable | Description |
|---|---|
| TranId | It is a unique reference number created for each transaction at URWAY end. |
| TrackId | This parameter is known as Transaction ID (or Order ID). It is the order reference number generated at Merchant (Merchant’s) end. It is an identifier which Merchant (merchant) would use to track a particular order. |
| Result | Transaction result (Successful/ UnSuccessful) |
| ResponseCode | Transaction response code |
| responseHash | This parameter is absolutely crucial and is similar to the hash parameter used in the transaction request send by the merchant to URWAY. |
| amount | The amount for which transaction was made |
| CardBrand | Contains card brand used for transaction.MADA,MASTER,VISA |
| UserField1, UserField3, UserField4, UserField5 | These field will contain values if any values are passed in request through udf1,udf3,udf4,udf5 |
ERRORS
API uses the following error codes:
| Error Code | Meaning |
|---|---|
| 000 | Transaction Successful. |
| 5XX | Bank Rejections |
| 601 | System Error, Please contact System Admin. |
| 659 | Request authentication failed |
| 701 | Error while processing ApplePay payment Token request |
| 906 | Invalid Card Token |