Documentation

Vault API

This specification document covers the list of API which requires adding customers to vault and perform transactions.

Authentication

For vault API endpoints at /api/valor-vault/, the required header parameters, App ID, and APP key must be passed. APP ID and APP Key can be found in the portal under Virtual Terminal > Manage > API KEYS

Valor-App-ID*
Valor-App-Key*

Below is the API for managing vault customers and performing transactions.

NOTE: A single vault customer can have up to 5 payment profiles and addresses.

Add Customer Profile

Add a new vault customer profile and return the vault unique id.

 Method       URL
 POST         /api/valor-vault/addcustomer
 Name                  Type        Example Value              Description                                                           
 customer_name *       string      Jack                       Vault Customer Name                                      
 customer_email        string      abc@xyzcom                 Vault Customer email address                              
 customer_phone        string      (123) 123-1234             Vault Customer Phone number                               
 company_name          string      abcd                       Vault Customer company name                               
 address_details       array       Refer to address object    An array of address details contains the address object.
 Name                       Type             Example Value                   Description
 address_label              string           Home                            Customer address Label
 billing_customer_name      string           Catherine P. Elliott            Billing customer Name
 billing_street_no          string           2629                            Billing street number
 billing_street_name        string           Rocket Drive                    Billing street Name 
 billing_unit               string           56                              Billing Unit
 billing_city               string           Golden Valley                   Billing city
 billing_state              string           MN                              Billing state use postal abbrevation
 billing_zip                string           55427                           Billing zip code min length 5 and max length 6
 shipping_customer_name     string           Carolina M. Morris              Shipping Customer Name
 shipping_street_no         string           1650                            Shipping street number
 shipping_street_name       string           Chicago Avenue                  Shipping street name
 shiiping_unit              string           56                              Shipping unit
 shipping_city              string           New York City                   Shipping city
 shipping_state             string           NY                              Billing state use postal abberivation
 shipping_zip               string           45664                           Shipping zip code min length 5 and max length 6
Name                    Type            Description
status                  string          API status
vault_customer_id       number          Customer unique profile ID
{
    "customer_name": "Sheila R. Mitch",
    "company_name": "Valor Paytech",
    "customer_phone": "49584583",
    "customer_email": "[email protected]",
    "address_details": [
        {
            "address_label": "Home",
            "billing_customer_name": "Carolina M. Morris",
            "billing_street_no": "3716",
            "billing_street_name": "Angie Drive",
            "billing_unit": "56",
            "billing_zip": "92646",
            "billing_city": "Huntington Beach",
            "billing_state": "CA",
            "shipping_customer_name": "Carolina M. Morris",
            "shipping_street_no": "1650",
            "shipping_street_name": "Chicago Avenue",
            "shipping_unit": "56",
            "shipping_zip": "93721",
            "shipping_city": "Fresno",
            "shipping_state": "CA"
        },
        {
            "address_label": "Office",
            "billing_customer_name": "Mary E. Nelson",
            "billing_street_no": "4188",
            "billing_street_name": "West Drive",
            "billing_unit": "56",
            "billing_zip": "60062",
            "billing_city": "Northbrook",
            "billing_state": "IL",
            "shipping_customer_name": "Mary E. Nelson",
            "shipping_street_no": "4893",
            "shipping_street_name": "Walkers Ridge Way",
            "shipping_unit": "56",
            "shipping_zip": "60148",
            "shipping_city": "Lombard",
            "shipping_state": "IL"
        }
    ]
}

Edit Customer Profile

Edit existing vault customers using vault id.

 Method       URL
 POST         /api/valor-vault/editcustomer/<vault_id>
Name                  Type               Description
vault_id*             number             Vault customer ID
 Name                  Type        Example Value            Description                                                           
 customer_email        string      abc@xyzcom               Vault Customer email address                              
 customer_phone        string      (123) 123-1234           Vault Customer Phone number                               
 company_name          string      abcd                     Vault Customer company name                               
 address_details       array       Refer address object     An array of address details contains the address object.
 Name                       Type             Example Value                   Description
 address_id                 number           739                             Address ID optional, If address id specified will
                                                                             update existing address else add a new address. 
 address_label              string           Home                            Customer address Label
 billing_customer_name      string           Catherine P. Elliott            Billing customer Name
 billing_street_no          string           2629                            Billing street number
 billing_street_name        string           Rocket Drive                    Billing street Name 
 billing_unit               string           56                              Billing Unit
 billing_city               string           Golden Valley                   Billing city
 billing_state              string           MN                              Billing state use postal abbrevation
 billing_zip                string           55427                           Billing zip code min length 5 and max length 6
 shipping_customer_name     string           Carolina M. Morris              Shipping Customer Name
 shipping_street_no         string           1650                            Shipping street number
 shipping_street_name       string           Chicago Avenue                  Shipping street name
 shiiping_unit              string           56                              Shipping unit
 shipping_city              string           New York City                   Shipping city
 shipping_state             string           NY                              Billing state use postal abberivation
 shipping_zip               string           45664                           Shipping zip code min length 5 and max length 6
Name                     Type             Description
status                   string           API status
vault_customer_id        number           Customer unique profile ID
{
    "company_name": "Valor Paytech",
    "customer_phone": "49584583",
    "customer_email": "[email protected]",
    "address_details": [
        {
            "address_id": 455,
            "address_label": "Home",
            "billing_customer_name": "Carolina M. Morris",
            "billing_street_no": "3716",
            "billing_street_name": "Angie Drive",
            "billing_unit": "56",
            "billing_zip": "92646",
            "billing_city": "Huntington Beach",
            "billing_state": "CA",
            "shipping_customer_name": "Carolina M. Morris",
            "shipping_street_no": "1650",
            "shipping_street_name": "Chicago Avenue",
            "shipping_unit": "56",
            "shipping_zip": "93721",
            "shipping_city": "Fresno",
            "shipping_state": "CA"
        },
        {
            "address_label": "Office",
            "billing_customer_name": "Carolina M. Morris",
            "billing_street_no": "3716",
            "billing_street_name": "Angie Drive",
            "billing_unit": "56",
            "billing_zip": "92646",
            "billing_city": "Huntington Beach",
            "billing_state": "CA",
            "shipping_customer_name": "Carolina M. Morris",
            "shipping_street_no": "1650",
            "shipping_street_name": "Chicago Avenue",
            "shipping_unit": "56",
            "shipping_zip": "93721",
            "shipping_city": "Fresno",
            "shipping_state": "CA"
        }
    ]
}

Delete Customer Profile

Delete the vault customer using vault id.

 Method       URL
 DELETE       /api/valor-vault/deletecustomer/<vault_id>
Name                Type        Example Value      Description
vault_id*           number      1285               Vault customer ID
Name                 Type             Description
status               string           API status
message              string           Success message

Delete Customer Profile Single Address

Delete single address from the vault customer using vault id and address id.

 Method       URL
 DELETE       /api/valor-vault/deletecustomer/<vault_id>/<address_id>
Name                Type        Example Value      Description
vault_id*           number      1285               Vault customer ID
address_id*         number      739                Address ID
Name                 Type             Description
status               string           API status
message              string           Success message

Get Particular Customer Profile

Get existing vault customers using vault id.

 Method       URL
 GET         /api/valor-vault/getcustomer/<vault_id>
Name                Type        Example Value      Description
vault_id*           number      1285               Vault customer ID
{
    "status": "OK",
    "message": "Success",
    "data": {
        "id": 341,
        "customer_name": "Sheila R. Mitch",
        "email": "[email protected]",
        "phone": "49584583",
        "company": "Valor Paytech",
        "address_details": [
            {
                "address_id": 524,
                "billing_state": "CA",
                "shipping_state": "CA",
                "address_label": "Home",
                "billing_customer_name": "Carolina M. Morris",
                "billing_street_no": "3716",
                "billing_street_name": "Angie Drive",
                "billing_unit": "56",
                "billing_zip": "92646",
                "billing_city": "Huntington Beach",
                "shipping_customer_name": "Carolina M. Morris",
                "shipping_street_no": "1650",
                "shipping_street_name": "Chicago Avenue",
                "shipping_unit": "56",
                "shipping_zip": "93721",
                "shipping_city": "Fresno"
            },
            {
                "address_id": 527,
                "billing_state": "IL",
                "shipping_state": "IL",
                "address_label": "Office",
                "billing_customer_name": "Mary E. Nelson",
                "billing_street_no": "4188",
                "billing_street_name": "West Drive",
                "billing_unit": "56",
                "billing_zip": "60062",
                "billing_city": "Northbrook",
                "shipping_customer_name": "Mary E. Nelson",
                "shipping_street_no": "4893",
                "shipping_street_name": "Walkers Ridge Way",
                "shipping_unit": "56",
                "shipping_zip": "60148",
                "shipping_city": "Lombard"
            }
        ]
    }
}

Get Customer List

Get all vault customers for the specific merchant.

 Method       URL
 GET         /api/valor-vault/getcustomerslist
Name            Type      Example Value      Description
limit           number    0                  Limit for pagnation. Max 50 and default 0.
offset          number    5                  Offset for pagination. Default 0
{
    "status": "OK",
    "message": "Success",
    "data": {
        "customers": [
            {
                "vault_id": 407,
                "customer_name": "Sheila g. Mitch",
                "email": "[email protected]",
                "phone": "49584583",
                "company": "Valor Paytech",
                "total_card_count": 0
            },
            {
                "vault_id": 383,
                "customer_name": "Sheila Y. Mitch",
                "email": "[email protected]",
                "phone": "49584583",
                "company": "Valor Paytech",
                "total_card_count": 0
            },
             {
                "vault_id": 344,
                "customer_name": "Sheila R. Mitc",
                "email": "[email protected]",
                "phone": "49584583",
                "company": "Valor Paytech",
                "total_card_count": 0
            },
            {
                "vault_id": 341,
                "customer_name": "Sheila R. Mitch",
                "email": "[email protected]",
                "phone": "49584583",
                "company": "Valor Paytech",
                "total_card_count": 9
            },
            {
                "vault_id": 335,
                "customer_name": "Sheila R. Mitchel",
                "email": "[email protected]",
                "phone": "49584583",
                "company": "Valor Paytech",
                "total_card_count": 0
            }
        ]
    },
    "total_count": 26,
    "limit": 5,
    "offset": 0
}

Add Payment Profile

Add payment profile for a vault id.

 Method       URL
 POST        /api/valor-vault/addpaymentprofile/<vault_id>
Name                Type        Example Value      Description
vault_id*           number      1285               Vault customer ID
 Name                  Type       Example Value        Description
 pan_num*             string      4111111111111111     PAN Number
 expiry*              string      1226                 Card expiry date, Accepted expiry MMYY or MM/YY
 cardholder_name      string      John                 Card holder name
Name                 Type             Description
status               string           API status
payment_id           number           Payment profile ID
{
  "pan_num": "4000056655665556",
  "expiry": "12/26",
  "cardholder_name": "Frederik Spencer"
}

Get Customer Payment Profile

Get vault customer payment profiles.

 Method       URL
 GET          /api/valor-vault/getpaymentprofile/<vault_id>
Name                Type        Example Value      Description
vault_id*           number      1285               Vault customer ID
{
    "status": "OK",
    "message": "Success",
    "data": [
        {
            "payment_id": 326,
            "masked_pan": "XXXX1111",
            "token": "BB5C27581603AE2E5E5E3C8B416FB7BFEC80366B",
            "cardholder_name": null
        },
        {
            "payment_id": 332,
            "masked_pan": "XXXX5556",
            "token": "A2D99E1106F582DD2BFEAC990E6198099DDEC034",
            "cardholder_name": null
        }
    ]
}

Update Payment Profile

Update payment profile status.

 Method       URL
 PATCH        /api/valor-vault/editpaymentprofile/<vault_id>/<payment_id>
Name                Type        Example Value      Description
vault_id*           number      1285               Vault customer ID
payment_id*         number      2876               Payment profile ID
 Name             Type         Description
 status*          string       Allow either active or inactive
Name              Type         Description
status            string       API status
message           number       Success message

Delete Payment Profile

Delete a single payment profile

 Method       URL
 DELETE      /api/valor-vault/deletepaymentprofile/<vault_id>/<payment_id>
Name                Type        Example Value      Description
vault_id*           number      1285               Vault customer ID
payment_id*         number      2876               Payment profile ID
Name              Type          Description
status            string        API status
message           number        Success message

Get Customer Transaction List

Call list of customer transactions list for a specified customer ID and date range.

 Method       URL
 GE         /api/valor-vault/fetchtransaction/<vault_id>
Name                Type        Example Value      Description
vault_id*           number      1285               Vault customer ID
Code			Type				Message
Name 			Type				Description		
limit			number				Limit for pagination. Max 50 and default 25.
offset			number				Offset for pagination. Default 0
 Name              Type         Example Value        Description
 start_date*       string       2023-03-03           Start date, Accepeted date YYYY-MM-DD
 end_date*         string       2023-03-28           End date, Accepeted date YYYY-MM-DD
{
    "code": 200,
    "status": "OK",
    "message": "Success",
    "data": [
        {
            "txn_id": 222920021387,
            "txn_type": "SALE",
            "txamount": 32436,
            "base_amount": 30000,
            "batch_no": "33",
            "card_holder_name": "",
            "card_scheme": "Visa",
            "city_tax_amount": 300,
            "custom_fee_amount": 936,
            "epi": "2302516694",
            "food_amount": 0,
            "invoice_no": "4",
            "masked_card_no": "4111 XXXX XXXX 1111",
            "reduced_tax_amount": 0,
            "request_date": "2023-03-30T00:00:00.000Z",
            "request_time": "01:37:27",
            "rrn": "308905501679",
            "state_tax_amount": 1200,
            "surcharge_fee_amount": 0,
            "surcharge_label": "Non-Cash Charge",
            "invoicenumber": "",
            "orderdescription": "",
            "phone": "6381671513",
            "processor_name": "TSYS Sierra",
            "transactions_status": "Approved"
        }
    ],
    "limit": 10,
    "total_count": 5,
    "offset": 0
}

Map Transaction to Customer Profile

The transaction card migration to the vault will be initiated based on the specific transaction.

 Method       URL
 GE           api/valor-vault/addpaymentprofiletxn/<vault_id>
Name                Type        Example Value      Description
vault_id*           number      1285               Vault customer ID
Name 			   Type		 Description		
ref_txn_id                 5754274      A unique response transaction id from the 
                                        response of a sale transaction (Numeric - Length of 20 chars)
{
  "code": 201,
  "status": "OK",
  "payment_id": 4433
}