NAV Navbar
cURL
  • Introduction
  • Checkout
  • Query
  • Cancel
  • Errors
  • Callback
  • Introduction

    Welcome to the Vault Payment API! You can use our API to access Vault API endpoints.

    Checkout

    Checkout via API

    To checkout, use this code:

      $.ajax({
        url:"https://www.thevaultapp.com/api/buildrequest",
        data:{
          token:{api_key},
          phone:{customer_phone_number},
          amount:{amount to checkout},
          subid1:{subid1 to send uniqueId},
          quantity:{number of items being sold},
          store:{name of store you'd like this transaction to be credited to}
        },
        type:"POST"
      })
    
    

    Make sure to replace api_key with your API key.

    Vault uses API keys to allow access to the API. You can register a new Vault API key at our (https://www.thevaultapp.com/business/api).

    HTTP Request

    POST https://www.thevaultapp.com/api/buildrequest

    Post Parameters

    Parameter Default Description Required
    token empty The api key registered at our site. true
    phone empty The customer's phone number where the payment request is sent. true
    amount empty The payment amount to checkout true
    subid1 empty The subid1 can be used as a variable to send own unique ID in your system. false
    quantity empty The number of items being sold in this transaction. Must be a numeric value. false
    store empty The name of the Store you'd like this transaction to be credited to. The Store must already exist in your account, and must be an exact match. false

    The above command returns JSON structured like this:

      {
        "status": "ok",
        "result": {
          "requestid":"829191sfwiwiw2923sf",
          "amount":10.44,
          "phone":"+12402211454",
          "subid1":"12345678",
          "quantity":"11",
          "store":"Test Store",
          "employeeemail":"test@thevaultapp.com",
          "status":"pending"
        }
      }
    

    Query

    Get Status of the payment request

      $.ajax({
        url:"https://www.thevaultapp.com/api/checkout_query/{request_id}",
        data:{
          token:{api_key}
        },
        type:"POST"
      }).done(function(response, status){
        //Process api calling success
      }).fail(function(response, status){
        //Process api calling fail
      })
    

    The above command returns JSON structured like this:

      {
        "status":"ok",
        "result":{
          "id": "9ss023swowflwsow293023",
          "status":"Approved"
        },
        "code":1
      }
    

    This endpoint retrieves status of the request.

    HTTP Request

    POST https://www.thevaultapp.com/api/checkout_query/{request_id}

    Query Parameters

    Parameter Default Description Reuqired
    request_id empty The request id gotten from the checkout api. true

    Post Parameters

    Parameter Default Description Reuqired
    token empty Registered the api key in the business/api. true

    Payment Request Status Codes

    Status Code Status Text Description
    0 Pending Waiting for a customer to approve or deny the $ Request in The Vault App
    1 Approved Customer has approved the $ Request in The Vault App
    2 Denied Customer has denied the $ Request in The Vault App
    3 Time Out The $ Request timed out with no response from the customer. The default time is 2 hours
    4 Payment Failed The customer's bank rejected the transaction
    5 Payment Canceled The client canceled the $ Request

    Cancel

    Cancel the payment request

      $.ajax({
        url:"https://www.thevaultapp.com/api/cancel_request/{request_id}",
        data:{
          token:{api_key}
        },
        type:"POST"
      }).done(function(response, status){
        //Process api calling success
      }).fail(function(response, status){
        //Process api calling fail
      })
    

    The above command returns JSON structured like this:

      {
        "status":"ok",
        "error":"",
        "code":1
      }
    

    This endpoint cancels the payment request.

    HTTP Request

    POST https://www.thevaultapp.com/api/cancel_request/{request_id}

    Query Parameters

    Parameter Default Description Reuqired
    request_id empty The request id gotten from the checkout api. true

    Post Parameters

    Parameter Default Description Reuqired
    token empty Registered the api key in the business/api. true

    Errors

    The Vault API uses the following status codes:

    Status Code Meaning
    0 Request Failed -- The api calling is failed.
    1 Api Success -- The api calling is success.

    Callback

    Once the payment request was approved or denied by the customer, the callback_url will be called by Vault.

    Post Parameters

    Parameter Description
    request_id The request id gotten from the checkout api.
    tid Transaction ID
    sale_amount Sale amount
    amount Gross Transaction Amount
    received_amount Net Retailer Amount
    subid1 The subid1 sent by checkout api.
    store Store name
    status Approved/Declined/Denied/Timeout/Canceled
    tip Tip amount
    tax Tax amount
    customer_fee Customer fee amount
    vps_fee_% VPS fee %
    vps_fee_# VPS fee #