API Payments

To integrate VaultsPay payment gateway in your web portal follow below steps.

Prerequisites

Before going ahead just make sure you have completed the following steps and have a few things at your disposal.

API Payments Checlist:

1. Active Profile

Your merchant account and owner account must be in activate state by the VaultsPay team. Complete your profile by giving all required information in order to get approval. Beware! By providing fallacious documents and information you will be blocked permenantly on VaultsPay.

2. Privilege Check

For any payment function on VaultsPay you must have the privilege for that operation otherwise you can not perform the operation. By default you will get your privileges according to your package plan.

3. IP Restriction

If your merchant account is activated for IP Restriction Check then you need to get your server's static IP listed for your account. Any payment request coming from IPs other then allowed ones will be rejected.

If you have completed all above steps then your are good to go.

Getting Access Token

To initiate a transaction on VaultsPay system you need to get an AccessToken first.

Getting API Keys

You can get your API keys by going to the App Settings section on your dashboard. Here you can get the client_id and client_secret keys.

Access Token API Request:
POST: https://vaultspay.com/sdk/access-token
  
  {
    "client_id": "vp_axaxaxaxaxaxaxaxaxax",
    "client_secret": "vp_axaxaxaxaxaxaxaxaxaxaxaxa",
  }
  
Access Token API Response:

status

The status attribute is simply a request response status "success" or "error".

message

User firendly message regarding the status of response.

data

All reponses details data is inside data attribute.

accessToken

If the request is validated you will get an accessToken which you will use to initiate a transaction.
  
  {
    "status": "success",
    "message": "Access token generated successfully.",
    "data": 
      {
        "accessToken": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...",
      },
  }
  

Initiate Payment

In this step we will initiate the actual payment after getting the accessToken.

Initiate Payment API Request:

token

The accessToken you have get in previous step.

amount

Amount up to two decimal places.

currency

Currency code in ISO3 format. You can check the list here.

callback_url

A valid url, response will be redirected to this URL upon success or failure.

method

You have to specify which method to use for the payment. You can only use the method for which you have privilege. List of all methods

user_ip

This IP is the the user's IP who is performing the transaction. You have to capture it on your system and send it to us for reference. i.e. "94.47.71.58"
POST: https://vaultspay.com/sdk/initiate-payment
  
  {
    "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...",
    "amount": 152.55,
    "currency": "AED",
    "callback_url": "https://www.mywebsite.com/callback_url",
    "method": "VPAY1",
    "user_ip": "94.47.71.58",
  }
  
Initiate Payment API Response:

status

The status attribute is simply a request response status "success" or "error".

message

User firendly message regarding the status of response.

data

All reponses details data is inside data attribute.

transaction_id

You can track your transaction with this transaction_id. It will remain the same throughout the transaction process.

payment_url

To complete the payment process user need to go this URL. VaultsPay payment portal will be open and the user can pay there.
POST: https://vaultspay.com/sdk/initiate-payment
  
  {
    "status": "success",
    "message": "Transaction initiated successfully.",
    "data": 
    {
      "transaction_id": "VPAPI_3A060766C190E912D362",
      "payment_url": "http://vaults.test/pay/initiate/VPAPI_3A060766C190E912D362",
    },
  }
  

Payment Status

Once you get a transaction_id you can trace the status of this transaction and check whether it's complete or not.


To fetch result of a transaction you first need to get an accessToken as describe above.


Payment Status API Request:
POST: https://vaultspay.com/pay/payment-status
  
  {
    "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...",
    "transaction_id": "VPAPI_3A060766C190E912D362",
  }
  
Payment Status API Response:

status

The status attribute is simply a request response status "success" or "error".

transaction_status

"completed" means the transaction is successful. "initiated" means the transaction is still in pending and has not been paind.

type

A transaction type can be "API Payment" or "Qr Payment" etc.

message

User firendly message regarding the status of response.

date

Transaction completion date.

source

Transaction initiation details.

transaction

Complete transaction details can be found here when the transaction completed.
  
  {
    "status": "success",
    "transaction_status": "completed",
    "type": "API Payment",
    "message": "Transaction initiated successfully.",
    "data": 
    {
      "transaction_id": "VPAPI_3A060766C190E912D362",
      "date": "2020-12-08T08:28:29.000000Z",
      "source": 
      {
           "amount": 150.55,
           "currency": "AED",
           "callback_url": "http://mywebsite.com/callback_url",
           "status": "success",
      },
      "transaction": 
      {
           "currency": "AED",
           "method": "VPAY1",
           "amount": 150.55,
           "charges": 3.21,
           "subtotal": 147.34,
      }
      "customer": 
      {
           "name": "Test User",
           "email": "[email protected]",
           "phone": "+9710000000000",
           "address": "Dubai, UAE",
           "card": "411111xxxxxx1111",
           "card_brand": "Visa",
      }
    }
  }
  

Appendix

The purpose of this section is to describe all possible terms and keyworkds used in this document. This is not just a reference document while integrating VaultsPay payment gateway in your system follow the keywords used here strictly.

Payment Methods

These are all the payment methods available at VaultsPay

Warning

Below listed payment methods will be enabled for specific user groups which means you can not necessarily use all of them. In API Payment Request use code name for "method".

# Method Code
1 Bank bank
2 Crypto crypto
3 Visa/Master VPAY2
4 Debit/Credit VPAY3
5 Visa/Master VPAY1
6 PayPal paypal
7 Stripe stripe
8 VaultsPay vaultspay