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
}