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://ext-api.vaultspay.com/external/v1/merchant-auth

  
  {
    "client_id": "vp_axaxaxaxaxaxaxaxaxax",
    "client_secret": "vp_axaxaxaxaxaxaxaxaxaxaxaxa",
  }

Access Token API Response:

data	All response details data is inside `data` attribute.
access_token	If the request is validated you will get an `access_token` which you will use to initiate a transaction. Token expiry will be in seconds . After getting the access_token you have to pass access_token in every API header while requesting.

  
  {
    "message": "Successful.",
    "data": {
        "access_token": "klpd2lkR0ZuSWpvaUluMD0i.oaMxU6NbFJ9NHyVtWUCF9Bn_HndB2Rt7h4qrMRC2xOI",
        "token_expiry": 300,
    },
    "code": 200
}

Allowed Payment Schemas

Allowed Payment Schemas API Request:

currencyCode	Required, Currency code in ISO3 format. You can check the list here.
ChannelName	Required, For example web

 POST: https://ext-api.vaultspay.com/external/v1/get-vaultspay-allowed-payment-methods

  
  {
    "currencyCode": "AED",
    "channelName": "web,
  }

Allowed Payment Schemas API Response:

data	All response details data is inside `data` attribute.
name	name is the schema name assigned to the account.
code	code will be used to initiating transactions.

  
  {
    "message": "Successful.",
    "data": [
        {
            "id": 2,
            "name": "VISA / MASTER ",
            "code": "SCM_02",
            "currency": {
                "id": 1,
                "name": "AED",
                "code": "AED"
            },
            "smart_routing": false
        }
    ],
    "code": 200
}

Initiate Payment

Initiate Payment API Request:

amount	Required
expiryInSeconds	Required, 0 for life time validity And 1 2 or other will define the time in seconds.
redirectUrl	Optional, This will be simple redirect url after payment to your site.
callBackUrl	Optional, This will be the hook that you will receive from vaultsPay.
schemaCode	Required, Get schema code from Get Allowed Payment Schema Api i-e SCM_00 for single payment schema. To iniatiate transaction in multiple schemas , then send Json string of schema codes i-e ["SCM_00","SCM_001"]
channelName	Required, web
clientReference	Optional, Reference that can be used to track transaction.

 POST: https://ext-api.vaultspay.com/external/v1/initialize-merchant-payment

  
  {
      "amount": 100,
      "expiryInSeconds": 0,
      "redirectUrl": "https://dummy/v1/redirect-url",
      "callBackUrl": "https://dummy/v1/call-back-url",
      "schemaCode": "SCM_02",
      "channelName": "Web",
      "clientReference": "VP-sdfs1245hdh",
  }

Initiate Payment API Response:

data	All response details data is inside `data` attribute.
paymentUrl	To complete the payment process user need to redirect to this URL. VaultsPay payment SDK will be open and the user can pay there.
paymentId	Payment id is the vaultsPay transaction id.

  
 {
    "message": "Successful.",
    "data": {
        "paymentUrl": "https://dummy/payment-url",
        "paymentId": "AP_ZM40ZDVDPU9PB"
    },
    "code": 200
}

Payment Status

Payment Status API Request:

transactionId	This will be vaultsPay transaction id.

 POST: https://ext-api.vaultspay.com/external/v1/get-transaction-details

  
  {
      "transactionId": "VPAPI_3A060766C190E912D362",
  }

Payment Status API Response:

data	All response details data is inside `data` attribute.

  
  {
    "message": "Successful.",
    "data": {
        "transactionStatus": "PENDING",
        "currency": "AED",
        "transactionId": "AP_ZM40ZDVDPU9PB",
        "transactionTime": "2024-08-20T08:36:11.000000Z",
        "transactionAmount": 100,
        "transactionVat": 0,
        "transactionFee": 0,
        "transactionSubTotalAmount": 100,
        "countryCode": "",
        "customerDetails": {
            "name": null,
            "email": null,
            "phoneNumber": null,
            "cardNumber": null,
            "cardHolderName": null
        }
    },
    "code": 200
}

Refund

Refund API Request:

transactionId	AP_t123
isPartial	0,1 if 1 amount is required. if full amount to refund both isPartial and amount is optional
redirectUrl	This will be simple redirect url after payment to your site.
amount	Required only if isPartial=1
description	Optional
callbackHookUrl	OPTIONAL. URL for refund hook to update status of refund.

 POST: https://ext-api.vaultspay.com/external/v1/create-refund-request

  
  {
      "transactionId": "VPAPI_3A060766C190E912D362",
      "isPartial": 1,
      "amount": 10,
      "description": "refund amount",
      "callbackHookUrl": "https://dumy/call-back-hook-url",
  }

Refund API Response:

uuid	This uuid is the refund transaction id.
transaction_id	This transaction_id is the vaultspay transaction id for which the refund initiated.

  
{
    "message": "Successful.",
    "data": {
        "uuid": "RFRQ_C9BDA779-2CF8-4007-BD40-A4807B303449",
        "transaction_id": "PL_RRXZN1ZSFYUQZ",
        "is_partial": 1,
        "amount": "50",
        "description": "",
        "status":1
          "created_at": "2021-09-02T07:01:12.000000Z",

    },
    "code": 200,
    "accessToken": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.ImV5SnBkaUk2SWtvdmRVSnVOakJDVUZkeWNuQXhPRUpuYnpNclkzYzlQU0lzSW5aaGJIVmxJam9pZG5wMlUwNHhla3h0YlVvMk5rUlZOMlJSZDBKdWREZDNPVXhSTlRKd2IwbzRWRmgwVDBkdFRpdE9RMEpGY1RGcEswOUhVWFpTUzBkdGF6WkZlR3BLVjNaM05HMURUMDUyTWt4WFpUTnFaWHB4T1hwSFVXTmlSbkZWY1daSVlURTNjR2xCWkhGbmMyVjRZemxVVWpjck0zaFhkWE52YkdOMk9HdEZkME50UTNwSldIRXlUVzFyVVc1WVVXUXhLeTlXVkVkUVNXdHZTVTFOVlU5SVdqRkpRa013YVRFM1NIRnlUbTVIYUVwSWRFTTBjMVpNYUdaTlQxWkVOMjh3TDJzdmN6aDVURXREZVcxRmVVUkphSFYyVlVoUFV6bDJhRlpqVDFrMWFqZDJTVGhoYm1WUE5uSlBOMnB5TW5wNE5FeEdTMk5RVVU5cU9GSXdaMUV4Wkd4dmFEYzRNWFF5WWs5eVFtaG9RV1pCU21sVWJGSXhXVGN4T1VsV01FRkRhVlZSV0VoUk0yNUJRM0F6SzBvcllYSXZkSG93VUd0VVV6QnlPRlpIWTJwYU9GTk9SbkJVYkN0ak5GSk9lV28zVnpCelZIUlRhR2hSUFQwaUxDSnRZV01pT2lJeU5qbGpPVEk1Wm1WaE9UQXlNV1pqT1dVME4yTmpNMkkzTUdZd1pqSmtaVE5tWVRJNE5UUTBaalF3TURjeFl6TXhaRFJsTlRNMU9XVmpZakpoTVdSaUluMD0i.ArXyY3hGp9gDjQ5629dZTtqkR57-_vAK3sSp4VIUMvs"
}

Direct Payments

In this section you can find more about direct payments.

Check Payment

Check Payment API Request:

paymentId	The merchant will provide the payment id in request.

 POST: https://ext-api.vaultspay.com/external/v1/check-payment

  
  {
    "paymentId": 100,
  }

Check Payment API Response:

data	All response details data is inside `data` attribute.
details	Details of initiated payment.
methods	Payment initiated with schema code will be returned and referenceId will be in the each schema , this reference id will be use in process payment API.

  
 {
    "message": "Successful.",
    "data": {
        "details": {
            "name": "Vaults TEST",
            "avatar": "https://MR_949F07D8-9FBF-4B46-8A32-2CBE0B24E942.png",
            "amount": "10000.00000000",
            "currency": "AED",
            "otherInfo": null
        },
        "methods": [
            {
                "name": "VISA / MASTER ",
                "code": "SCM_02",
                "referenceId": "Z25yVFNBbVdwQnBRa2N6SlAwL0VKRm9taFA2aHJ0THZ"
            }
        ]
    },
    "code": 200
}

Direct Payment Process

Process Payment API Request:

referenceId	Get from DIRECT-CHECK PAYMENT RESPONSE
name	Required
email	Required
phone	Required
cardHolderName	Required
cardNumber	Required
expMonth	Required
expYear	Required
cvc	Required

 POST: https://ext-api.vaultspay.com/external/v1/process-payment

  
  {

      "referenceId": "Z25yVFNBbVdwQnBRa2N6SlAwL0VKRm9taFA2aHJ0THZ2SE5PZE12UENwQT0=,
      "name": "Nizam",
      "email": "[email protected]",
      "phone": 11112221121,
      "cardHolderName": "Nizam",
      "cardNumber": 4111111111111111,
      "expMonth": 12,
      "expYear": 25,
      "cvc": 111,

  }

Process Payment API Response:

data	All response details data is inside `data` attribute.
bypass3DS	if true means check transaction status and transaction completed. if false need to redirect user to url.
transactionId	This is the vaultsPay payment id.
dateTime	This is the vaultsPay transaction date and time.
paymentUrl	If the bypass3DS is false user will be redirect on this url.

  
 {
    "message": "Successful.",
    "data": {
        "bypass3DS": false,
        "transactionId": "AP_ZM40ZDVDPU9PB",
        "dateTime": "2024-08-20T08:46:54.000000Z",
        "status": true,
        "paymentUrl": "https://MR_949F07D8-9FBF-4B46-8A32-2CBE0B24E942/payment-url"
    },
    "code": 200
}

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.

Response codes

200	Success
400	Error
401	unauthorized, unauthenticated

Payment Hook

If callbackUrl is provided in the initiate payment then vaultspay will hit the url on payment status changes.

hook payload	{"vpTransactionId":"PL_BMBQ20DSLUSMZ","clientReference":"merchantRef","amount":100,"fee":0,"vat":0,"status":"SUCCESS","time":"2024-08-30T07:00:58.000000Z"}.
Status values	Status values are PENDING if transaction pending, SUCCESS for transaction success and ERROR for failed.