Acquiring API Privileges
Tip
Reach VaultsPay customer service to get instant help. Our developers are evermore willing to help you integrate VaultsPay into your application.
KYC Verification
VaultsPay value our customers and their privacy is our great concern. Therefore, VaultsPay requires all merchants to verify their business details by providing proper evidence. Once you get VaultsPay KYC (Know Your Customer) approval, only then, you can start using VaultsPay services.
Warning
In case of counterfeit documents and fallacious information, a merchant shall liable to legal proceedings.
Payment Modes
VaultsPay believes in flexibility; therefore, it provides different payment modes to its customers. These payment modes vary according to a business agreement and other parameters. These payment modes, also, enables a merchant to use different payment methods simultaneously.
Example of Payment Modes:
| # |
Code |
Name |
Currency |
Additional Feature |
| 1 |
SCM_01 |
VISA |
AED |
IP Restriction Enabled |
| 2 |
SCM_02 |
MASTER |
AED |
3D Secure |
| 3 |
SCM_03 |
VISA |
USD |
S2S (Server to Server) Integration |
Authenticate Merchant
Firstly, you need to get an "accessToken" to initiate a transaction on VaultsPay. Authenticating merchant involves checking merchant credentials, whitelist IPs, and the privilege to perform an action. All subsequent API requests require AccessToken to make a request.
Getting API Credentials
You can get your API credentials by navigating to Dashboard > Header > API Keys on your VaultsPay merchant account.
Here you can get the clientId and clientSecret keys.
1. API Request:
POST: https://testapi.vaultspay.com/public/external/v1/merchant-auth
{
"clientId": "ID-1111111",
"clientSecret": "SECRET-XYXYXYXY-XYXY-XYXY-XYXY-XYXYXYXYXYXY",
}
2. API Response:
|
code
|
200 for success 400 for error. |
|
data
|
All reponse details data is inside data object. |
|
access_token
|
If the request is validated you will get an access_token which you will use in subsequent API requests. |
|
token_expiry
|
token_expiry is the number of seconds after your token expired. |
|
stores
|
One merchant can have multiple stores to collect payments from different branches and manage them separately. |
|
storeName
|
storeName is the title or name given to a store. |
|
terminalName
|
Each store can have multiple terminals to collect payments. |
|
channelName
|
channelName specifies the medium a customer use to complete the transaction. |
|
channelCode
|
channeCode also uniquely refers to the channelName. |
{
"message": "Successful.",
"code": "200",
"data":
{
"access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...",
"token_expiry": "7200",
"stores":
[
"storeName": "John Doe",
"terminalName": "John Doe",
"channelName": "web",
"channelCode": "CHN_xyxyxyxyxyxyx",
],
},
}
Important!
Always include the accessToken you've received in this API in the headers of all subsequent APIs.
Your API request will be denied if it does not include accessToken in the headers.
Allowed Payment Methods
In order to manage separate business entities for a merchant, you can use multiple stores to process customer payments. In this API, you will get the list of all stores you have procured to receive payments.
Manage finances in a smart way!
Try to use dedicated stores for each separate entity of your business. In this way, it will make it easier for you to manage your branch finances separately.
1. API Request:
|
currencyCode
|
Send currency code from the following list. |
|
channelName
|
The channelName of your store. You can get this attribute from accessToken API's response. |
|
accessToken
|
Include in headers. The access_token you haved received from Get AccessToken API. |
POST: https://testapi.vaultspay.com/public/external/v1/get-vaultspay-allowed-payment-methods
{
"currencyCode": "AED",
"channelName": "web",
}
2. API Response:
|
name
|
Payment method name. |
|
code
|
This is the schemaCode you will use to initiate a transaction in the next step. |
|
smart_routing
|
Smart routing will automatically detect alternative payment routes if one link is down. |
|
currency
|
Allowed currency code for a specific store. |
{
"message": "Successful.",
"code": "200",
"data":
[
{
"id": "1",
"name": "VISA",
"code": "SCM_01",
"currency":
{
"id": "1",
"name": "AED Dirham",
"code": "AED",
},
"smart_routing": "false",
},
]
}
Initialize Payment
In this step, you will specify payment details for a transaction. After initiating a transaction at VaultsPay, a customer will finally be able to pay.
1. API Request:
|
schemaCode
|
Type (Array or String): Specify which scheme methods you want to use for this transaction.
Use json string for multiple payment methods i.e; [SCM_01, SCM_04, SCM_03] or SCM_01 for single mode. |
|
amount
|
The amount you want to charge your customer. |
|
callBackUrl
|
This will automatically be invoked from the VaultsPay server to client server with the following attributes: vpTransactionId and status |
|
redirectUrl
|
Once a transaction has been completed successfully, customer will be redirected to this URL. |
|
expiryInSeconds
|
A customer can pay within expiryInSeconds for this transaction. After that the paymentUrl will expire. |
|
channelName
|
The channel you want to use for your transaction. |
|
schemaCode
|
Specify the schema you want to use to complete this transcation. |
|
clientReference (Optional)
|
Reference ID or token you will use to identify your customer. |
POST: https://testapi.vaultspay.com/public/external/v1/initialize-merchant-payment
{
"amount": "100",
"callBackUrl": "https://website.com/callbackURL",
"redirectUrl": "https://website.com/paymentInvoice",
"expiryInSeconds": "7200",
"channelName": "web",
"schemaCode": "SCM_01",
"clientReference": "ABC_8daDT8v5dfew61sdS5"
}
2. API Response:
|
paymentUrl
|
A customer can complete the transaction by going to this URL and completing payment details. |
|
paymentId
|
VaultsPay will generate a unique transaction ID for each transaction. You can use this payment ID to get details later on. |
{
"message": "Successful.",
"code": "200",
"data":
{
"paymentUrl": "https://sdk.vaultspay.com/payment-method?paymentId=AP-PL-CB295ACF-49D0-404F-A069-7BB8EB03EC78",
"paymentId": "AP-PL-CB295ACF-49D0-404F-A069-7BB8EB03EC78",
},
}
Complete Payment
In your web application, redirect your customer to paymentUrl. On this page, the user will enter card details to complete the transaction.
To check the status of a transaction whether it's completed or not use the Get Payment Details API.
If you don't want to redirect your customers to fill in card details - which you may already have collected or stored somewhere - then you can proceed
to the Direct Payment module. In this way,
you can avoid redirecting your customer to the external "redirectUrl" for payment completion.
Request Direct Payment
In this step, VaultsPay will verify if Direct Payment is enabled for your account or not. If you have acquired Direct Payment integration privilege then you will get available payment methods in response to complete the transaction.
Getting Direct Payment Privilege
If you have PCI compliance for your application then you might be eligible for this privilege. For more information about this requirement please
contact VaultsPay customer support.
1. API Request:
POST: https://testapi.vaultspay.com/public/external/v1/check-payment
|
paymentId
|
PaymentId you have received after initiating a payment in the previous step. |
{
"paymentId": "ID-1111111",
}
2. API Response:
|
details
|
The details object contains information related to payment. |
|
methods
|
In methods you will get all available options to complete a payment. |
|
referenceId
|
You will be using this referenceId in the next step to complete payment. |
{
"message": "Successful.",
"code": "200",
"data":
{
"details":
{
"name": "Test Merchant",
"avatar": "https://efun.ae/new/public/uploads/users/MR_941054B3-E820-4B3D-8D68-CE061F5C82AB.jpg",
"amount": "100.00000000",
"currency": "AED",
"otherInfo": "null",
},
"methods":
{
"name": "VISA",
"referenceId": "AP_ETROUZ0ZBZDAU&_MSY4NDA=",
},
},
}
Process Direct Payment
In the final step, you will send customer information along with card details and the referenceId to complete the payment.
1. API Request:
POST: https://testapi.vaultspay.com/public/external/v1/process-payment
|
referenceId
|
referenceId specifies the payment method for this transcation. |
{
"referenceId": "AP_KUE09G4E1HKGV&_XYXYXYX=",
"name": "John Doe",
"email": "[email protected]",
"phone": "+971 00 0000000",
"cardHolderName": "John Doe",
"cardNumber": "4111111111111111",
"expMonth": "12",
"expYear": "25",
"cvc": "111"
}
2. API Response:
|
bypass3DS
|
If bypass3DS istrue, the transaction will complete, and its success or failure will be determined by the status in the response:
if the status istrue, the transaction is successful
if the status is false, the transaction has failed. If bypass3DS is false, a redirection to the paymentUrl is required to complete the 3DS process and finalize the transaction. |
{
"message": "Successful.",
"code": "200",
"data":
{
"paymentUrl": "https://vaultspay.com/api/v1/gateway-callback/?ref=AP_ETROUZ0ZBZDAU",
"bypass3DS": "false",
"transactionId": "AP_ETROUZ0ZBZDAU",
"dateTime": "2021-08-31T10:20:04.000000Z",
"status": "true",
"redirectUrl": "http://localhost/redirect",
},
}
Complete Direct Transaction:
Now, if you received false in bypass3DS then hit paymentUrl to complete transaction.
It is important to hit this paymentUrl otherwise, your payment will not be completed.
Get Payment Details
This API returns transaction status, charges and other details. Before settling a transaction in your application, hit this API anytime to check the status of a transaction.
1. API Request:
POST: https://testapi.vaultspay.com/public/external/v1/get-transaction-details
{
"transactionId": "1",
"accessToken": "xxyyZZx...",
}
2. API Response:
|
transactionStatus
|
Human-readable transaction status. |
|
currency
|
The currency code of this transcation. |
|
transactionId
|
Unique transaction ID for this transaction. |
|
transactionTime
|
It is the time when this transation is performed. It returns time in Zulu timezone. |
|
transactionAmount
|
The total amount of this transaction. |
|
transactionVat
|
VAT charges for this transaction. |
|
transactionFee
|
Transaction service charges. |
|
transactionSubTotalAmount
|
Total sub amount of a transaction. |
|
countryCode
|
Transaction performed from country. |
|
customerDetails
|
All the customer details |
{
"message": "Successful.",
"code": "200",
"data":
{
"transactionStatus": "SUCCESS",
"currency": "AED",
"transactionId": "AP_HCLQNK2GGQOOH",
"transactionTime": "2021-08-26T04:32:06.000000Z",
"transactionAmount": "10000.00000000",
"transactionVat": "0.00000000",
"transactionFee": "0.00000000",
"transactionSubTotalAmount": "100",
"countryCode": "",
"customerDetails":{
"name": "nizam",
"email": "[email protected]",
"phoneNumber": "1231231231",
"cardNumber": "4111111111111111",
"cardHolderName": "Nizam",
}
},
}
What is VAT charge?
A value-added tax, known in some countries as a goods and services tax, is a type of tax that is assessed incrementally. It is levied on the price of a product or service at each stage of production, distribution, or sale to the end consumer. The rate of VAT is 5 per cent in UAE.
What are payment modes?
Payment modes are different ways to perform a transaction. Each payment mode has its unique set of properties. Payment mode specifies card type, payment processing technology, currency, and service charges.
How many payment modes can I use?
There are many payment modes available at VaultsPay to perform a transaction. Your acquired payment mode(s) will depend upon the business contract you have made with VaultsPay. To provide flexibility, VaultsPay offers customised payment modes to suit your business needs.
Why I am not getting AccessToken?
If IP restriction mode is activated for your account then you can only request AccessToken from resistered IP addresses. If you want to whitelist another IP then please contact VaultsPay suppport with valid credentials.
Request Refund
You can request a refund for a successful transaction. You have the option to request a partial or full refund. After initiating a refund, your request will be reviewed by our accounts department and will be processed manually within three working days.
1. API Request:
|
transactionId
|
The transactionId of the transaction you want to get refund. |
|
isPartial (optional)
|
You can refund a transaction, either partial or complete. Send "1" for Partial and "0" or null for Complete refund. |
|
amount
|
If you choose "isPartial" refund then you need to specify the amount here. The amount must be less than the transaction full amount. |
|
callbackHookUrl (Optional)
|
VaultsPay will hit this POST callback hook URL at your application server whenever the VaultsPay finance team process this refund request. |
POST: https://testapi.vaultspay.com/public/external/v1/create-refund-request
{
"transactionId": "PL_xyz",
"isPartial": "1",
"amount": "50.50",
"callbackHookUrl": "https://mywebsite.com/refund-request-hook",
}
2. API Response:
|
uuid
|
Unique ID of the refund request. |
|
transaction_id
|
The transaction ID of the transaction we requested the refund for. |
|
is_partial
|
Response for partial will be "1" and for full "0" |
|
amount
|
This amount will be refunded to the cusotmer. |
{
"message": "Successful.",
"code": "200",
"data":
{
"id": "1122",
"uuid": "RFRQ_xyz",
"transaction_id": "PL_xyz",
"is_partial": "1",
"amount": "50.50",
"description": "null",
"created_at": "2021-10-05T10:42:48.000000Z",
},
}
Callback Hook Body:
{
"vpTransactionId": "RF_C1KXG2T9H0RMK.",
"clientReference": "Refund request Id",
"amount": "10",
"fee": "0.5",
"vat": "0",
"status": "SUCCESS",
"referenceId": "RFRQ_....",
}
Check Refund Request Status
You can check the status of a refund request or trace your refund process.
1. API Request:
|
uuid
|
The uuid of the refund request. |
POST: https://testapi.vaultspay.com/public/external/v1/get-refund-request
{
"uuid": "RFRQ_57A4FCBC-60B7-4C32-AD90-9FD3C06F3B59",
}
2. API Response:
|
uuid
|
Unique ID of the refund request. |
|
transaction_id
|
The transaction ID of the transaction we requested the refund for. |
|
status
|
0 for pending, 1 for initiated, 2 for processed, 3 for cancelled, 4 for rejected |
{
"message": "Successful.",
"code": "200",
"data":
{
"uuid": "RFRQ_xyz",
"transaction_id": "PL_xyz",
"amount": "50.50",
"status": 2,
"description": "null",
"status_str": "Processed",
"created_at": "2021-10-05T10:42:48.000000Z",
},
"refunded_transaction":
{
"id": 123,
"uuid": "PL_xyz",
"reference_id": "50.50",
"sender_account_id": 2,
"amount": "null",
"total_amount": "Processed",
"fee": "2021-10-05T10:42:48.000000Z",
"vat": "2021-10-05T10:42:48.000000Z",
"currency_id": "2021-10-05T10:42:48.000000Z",
"created_at": "2021-10-05T10:42:48.000000Z",
"currency":
{
"id": 1,
"code": "AED"
},
},
}
