Valor API Sample Responses

Provides example success and error responses to help understand the valor API response structure and handling.

Add Customer Profile

Create a new customer profile in the vault.


Response — 201 Created

{
  "code": 201,
  "status": "OK",
  "vault_customer_id": 100864
}

Response fields

FieldTypeDescription
codeintegerHTTP status code (201)
statusstringOK on success
vault_customer_idintegerUnique identifier for the newly created customer profile

Response — 400 (Validation Error)

{
  "code": 400,
  "status": "FAILED",
  "errors": [
    "data must have required property 'customer_name'"
  ]
}

Response fields

FieldTypeDescription
codeintegerHTTP status code (400)
statusstringFAILED when the request cannot be processed
errorsarrayList of validation error messages

Error code reference

statusMeaningTypical cause
OKSuccessCustomer profile created
FAILEDValidation errorRequired field customer_name is missing from the request

Add Payment Profile

Add a card payment profile to an existing customer vault record.


Response — 201 Created

{
  "code": 201,
  "status": "OK",
  "payment_id": 97555
}

Response fields

FieldTypeDescription
codeintegerHTTP status code (201)
statusstringOK on success
payment_idintegerUnique identifier for the newly created payment profile

Response — 400 (Validation Error)

{
  "code": 400,
  "status": "FAILED",
  "errors": [
    "Customer not exist"
  ]
}

Response fields

FieldTypeDescription
codeintegerHTTP status code (400)
statusstringFAILED when the request cannot be processed
errorsarrayList of validation error messages

Error code reference

statusMeaningTypical cause
OKSuccessPayment profile created
FAILEDValidation errorCustomer ID does not exist in the vault

Add ACH Profile

Add a bank account (ACH) profile to an existing customer vault record.


Response — 200 OK

{
  "code": 200,
  "status": "SUCCESS",
  "ach_profile_id": 2290
}

Response fields

FieldTypeDescription
codeintegerHTTP status code (200)
statusstringSUCCESS on success
ach_profile_idintegerUnique identifier for the newly created ACH profile

Response — 400 (Validation Error)

{
  "code": 400,
  "status": "FAILED",
  "errors": "Missing required field(s): account_number"
}

Response fields

FieldTypeDescription
codeintegerHTTP status code (400)
statusstringFAILED when the request cannot be processed
errorsstringError message describing the missing or invalid field

Note: Unlike most endpoints where errors is an array, this endpoint returns errors as a plain string.


Error code reference

statusMeaningTypical cause
SUCCESSSuccessACH profile created
FAILEDValidation errorRequired field account_number is missing from the request

Add Payment Profile Using Token

Add a card payment profile to a customer vault record using an existing card token instead of raw card details.


Response — 201 Created

{
  "code": 201,
  "status": "OK",
  "payment_id": 97555
}

Response fields

FieldTypeDescription
codeintegerHTTP status code (201)
statusstringOK on success
payment_idintegerUnique identifier for the newly created payment profile

Response — 400 (Validation Error)

{
  "status": "FAILED",
  "errors": [
    "Invalid Token"
  ]
}

Response fields

FieldTypeDescription
statusstringFAILED when the request cannot be processed
errorsarrayList of validation error messages

Note: This error response does not include a code field.


Error code reference

statusMeaningTypical cause
OKSuccessPayment profile created from token
FAILEDValidation errorToken is invalid, expired, or not found

Edit Customer Profile

Update the details of an existing customer vault profile.


Response — 200 OK

{
  "code": 200,
  "status": "OK",
  "vault_customer_id": 100864
}

Response fields

FieldTypeDescription
codeintegerHTTP status code (200)
statusstringOK on success
vault_customer_idintegerIdentifier of the updated customer profile

Response — 400 (Validation Error)

{
  "code": 400,
  "status": "FAILED",
  "errors": [
    "data/customer_phone Enter a valid Phone Number"
  ]
}

Response fields

FieldTypeDescription
codeintegerHTTP status code (400)
statusstringFAILED when the request cannot be processed
errorsarrayList of validation error messages

Error code reference

statusMeaningTypical cause
OKSuccessCustomer profile updated
FAILEDValidation errorcustomer_phone is not a valid phone number format

Fetch Transaction With Date Range

Retrieve a paginated list of transactions linked to a vault customer profile, filtered by date range.


Response — 200 OK

{
  "code": 200,
  "status": "OK",
  "message": "SUCCESS",
  "data": [
    {
      "txn_id": 10176309,
      "epi_id": "2319916062",
      "txn_type": "SALE",
      "total_amount": 103,
      "base_amount": 100,
      "batch_no": "185",
      "card_holder_name": "Sheila Mitch",
      "card_scheme": "Visa",
      "city_tax_amount": 0,
      "custom_fee_amount": 0,
      "epi": "2319916062",
      "food_amount": 0,
      "masked_card_no": "4111 XXXX XXXX 1111",
      "reduced_tax_amount": 0,
      "request_date": "03/25/2026",
      "request_time": "02:22:37",
      "rrn": "608406501192",
      "state_tax_amount": 3,
      "surcharge_fee_amount": 0,
      "surcharge_label": "Adjustment",
      "invoicenumber": "",
      "orderdescription": "",
      "phone": "6129160161",
      "email": "[email protected]",
      "subscription_id": "",
      "company_name": "",
      "tran_no": 1,
      "stan_no": "689251",
      "card_type": "DEBIT",
      "approval_code": "TAS318",
      "response_code": "00",
      "switch_response_code": "00",
      "display_message": "",
      "tip_adjusted_count": 0,
      "is_voided": 0,
      "is_reversed": 0,
      "is_auth_completed": 0,
      "is_settled": 0,
      "settled_at": "2026-03-25T06:22:37.000Z",
      "is_offline_approved": 0,
      "is_partial_approved": 0,
      "addtl_data_label1": "Clerk ID",
      "addtl_data_value1": "",
      "addtl_data_label2": "",
      "addtl_data_value2": "",
      "timezone": "EST",
      "refunded_count": 0,
      "processor_name": "TSYS Sierra",
      "transactions_status": "Approved"
    }
  ],
  "total_count": 1,
  "limit": 25,
  "offset": 0
}

Response fields — top level

FieldTypeDescription
codeintegerHTTP status code (200)
statusstringOK on success
messagestringSUCCESS on success
dataarrayArray of transaction objects
total_countintegerTotal number of matching transactions
limitintegerMaximum number of records returned per page
offsetintegerPagination offset (starting record index)

data — transaction object fields

FieldTypeDescription
txn_idintegerUnique transaction identifier
epi_idstringTerminal / EPI identifier
txn_typestringTransaction type (e.g. SALE, REFUND, VOID)
total_amountnumberTotal charged amount in cents
base_amountnumberBase transaction amount in cents (excluding fees and taxes)
batch_nostringSettlement batch number
card_holder_namestringName on the card
card_schemestringCard network (e.g. Visa, Mastercard)
city_tax_amountnumberCity tax amount in cents
custom_fee_amountnumberCustom fee amount in cents
epistringMerchant terminal / EPI identifier
food_amountnumberFood amount in cents, if applicable
masked_card_nostringMasked card number (e.g. 4111 XXXX XXXX 1111)
reduced_tax_amountnumberReduced tax amount in cents, if applicable
request_datestringTransaction date in MM/DD/YYYY format
request_timestringTransaction time in HH:MM:SS format
rrnstringRetrieval reference number
state_tax_amountnumberState tax amount in cents
surcharge_fee_amountnumberSurcharge fee amount in cents
surcharge_labelstringDisplay label for the surcharge
invoicenumberstringMerchant-supplied invoice reference, if provided
orderdescriptionstringOrder or item description, if provided
phonestringCardholder phone number, if provided
emailstringCardholder email address, if provided
subscription_idstringSubscription identifier, if this transaction is part of a subscription
company_namestringCompany name, if provided
tran_nointegerSequential transaction number within the batch
stan_nostringSystem trace audit number
card_typestringCard type (e.g. DEBIT, CREDIT)
approval_codestringIssuer-returned authorization code
response_codestringGateway response code. 00 = approved
switch_response_codestringSwitch-level response code
display_messagestringDisplay message from the processor, if any
tip_adjusted_countintegerNumber of tip adjustments made on this transaction
is_voidedinteger1 if voided; 0 otherwise
is_reversedinteger1 if reversed; 0 otherwise
is_auth_completedinteger1 if auth has been captured; 0 otherwise
is_settledinteger1 if settled; 0 if pending settlement
settled_atstringSettlement timestamp (ISO 8601)
is_offline_approvedinteger1 if approved offline; 0 otherwise
is_partial_approvedinteger1 if partially approved; 0 for full approval
addtl_data_label1stringAdditional data label 1
addtl_data_value1stringAdditional data value 1
addtl_data_label2stringAdditional data label 2
addtl_data_value2stringAdditional data value 2
timezonestringTimezone of the terminal (e.g. EST)
refunded_countintegerNumber of refunds issued against this transaction
processor_namestringName of the payment processor (e.g. TSYS Sierra)
transactions_statusstringTransaction status (e.g. Approved, Declined)

Response — 400 (Validation Error)

{
  "status": "FAILED",
  "errors": [
    "Vault customer ID does not exist."
  ]
}

Response fields

FieldTypeDescription
statusstringFAILED when the request cannot be processed
errorsarrayList of validation error messages

Error code reference

statusMeaningTypical cause
OKSuccessTransaction records returned
FAILEDValidation errorVault customer ID not found

Update Payment Profile

Update the card details of an existing payment profile in the vault.


Response — 200 OK

{
  "code": 200,
  "status": "OK",
  "payment_id": 97555
}

Response fields

FieldTypeDescription
codeintegerHTTP status code (200)
statusstringOK on success
payment_idintegerIdentifier of the updated payment profile

Response — 400 (Validation Error)

{
  "status": "FAILED",
  "errors": [
    "Please provide a valid payment profile ID."
  ]
}

Response fields

FieldTypeDescription
statusstringFAILED when the request cannot be processed
errorsarrayList of validation error messages

Error code reference

statusMeaningTypical cause
OKSuccessPayment profile updated
FAILEDValidation errorPayment profile ID is invalid or not found

Map Transaction to Customer Profile

Link an existing transaction to a vault customer profile by creating a payment profile from the transaction's card data.


Response — 201 Created

{
  "code": 201,
  "status": "OK",
  "payment_id": 97558
}

Response fields

FieldTypeDescription
codeintegerHTTP status code (201)
statusstringOK on success
payment_idintegerUnique identifier for the payment profile created from the mapped transaction

Response — 400 (Validation Error)

{
  "status": "FAILED",
  "errors": [
    "Reference transaction ID missing"
  ]
}

Response fields

FieldTypeDescription
statusstringFAILED when the request cannot be processed
errorsarrayList of validation error messages

Error code reference

statusMeaningTypical cause
OKSuccessTransaction mapped and payment profile created
FAILEDValidation errorReference transaction ID was not provided in the request

Update ACH Profile

Update the bank account details of an existing ACH profile in the vault.


Response — 200 OK

{
  "code": 200,
  "status": "SUCCESS",
  "ach_profile_id": "2290"
}

Response fields

FieldTypeDescription
codeintegerHTTP status code (200)
statusstringSUCCESS on success
ach_profile_idstringIdentifier of the updated ACH profile

Response — 400 (Validation Error)

{
  "code": 400,
  "status": "FAILED",
  "errors": "No changes detected. ACH profile already contains the same information"
}

Response fields

FieldTypeDescription
codeintegerHTTP status code (400)
statusstringFAILED when the request cannot be processed
errorsstringError message describing the reason for failure

Note: errors is returned as a plain string for this endpoint, not an array.


Error code reference

statusMeaningTypical cause
SUCCESSSuccessACH profile updated
FAILEDValidation errorThe submitted data is identical to the existing ACH profile — no changes to apply

Edit Payment Profile

Update the status or metadata of an existing payment profile.


Response — 200 OK

{
  "code": 200,
  "status": "OK",
  "message": "Success"
}

Response fields

FieldTypeDescription
codeintegerHTTP status code (200)
statusstringOK on success
messagestringSuccess on success

Response — 400 (Validation Error)

{
  "status": "FAILED",
  "errors": [
    "data must have required property 'status'"
  ]
}

Response fields

FieldTypeDescription
statusstringFAILED when the request cannot be processed
errorsarrayList of validation error messages

Error code reference

statusMeaningTypical cause
OKSuccessPayment profile updated
FAILEDValidation errorRequired field status is missing from the request

View Customer Profile

Retrieve the full profile details for a single vault customer, including address information.


Response — 200 OK

{
  "code": 200,
  "status": "OK",
  "message": "Success",
  "data": {
    "id": 100867,
    "customer_name": "Melvin",
    "email": "[email protected]",
    "phone": "6129160161",
    "company": "Home Centers",
    "total_card_count": 0,
    "address_details": [
      {
        "address_id": 154246,
        "address_label": "Home",
        "billing_customer_name": "Catherine P. Elliott",
        "billing_street_no": "2629",
        "billing_street_name": "Rocket Drive",
        "billing_unit": "56",
        "billing_zip": "55427",
        "billing_city": "Golden Valley",
        "billing_state": "MN",
        "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"
      }
    ]
  }
}

Response fields — top level

FieldTypeDescription
codeintegerHTTP status code (200)
statusstringOK on success
messagestringSuccess on success
dataobjectCustomer profile object

data — customer profile fields

FieldTypeDescription
idintegerUnique vault customer ID
customer_namestringCustomer's full name
emailstringCustomer email address
phonestringCustomer phone number
companystringCompany name, if provided
total_card_countintegerNumber of payment profiles linked to this customer
address_detailsarrayList of saved address records (see below)

address_details — address object fields

FieldTypeDescription
address_idintegerUnique identifier for this address record
address_labelstringLabel for the address (e.g. Home, Work)
billing_customer_namestringName on the billing address
billing_street_nostringBilling street number
billing_street_namestringBilling street name
billing_unitstringBilling unit or apartment number, if applicable
billing_zipstringBilling ZIP code
billing_citystringBilling city
billing_statestringBilling state (2-letter code)
shipping_customer_namestringName on the shipping address
shipping_street_nostringShipping street number
shipping_street_namestringShipping street name
shipping_unitstringShipping unit or apartment number, if applicable
shipping_zipstringShipping ZIP code
shipping_citystringShipping city
shipping_statestringShipping state (2-letter code)

Response — 400 (Validation Error)

{
  "code": 400,
  "status": "FAILED",
  "errors": [
    "Customer not exist"
  ]
}

Response fields

FieldTypeDescription
codeintegerHTTP status code (400)
statusstringFAILED when the request cannot be processed
errorsarrayList of validation error messages

Error code reference

statusMeaningTypical cause
OKSuccessCustomer profile returned
FAILEDValidation errorCustomer ID does not exist in the vault

Get Payment Profile

Retrieve all card payment profiles linked to a vault customer.


Response — 200 OK

{
  "code": 200,
  "status": "OK",
  "message": "Success",
  "data": [
    {
      "payment_id": 97555,
      "masked_pan": "XXXX1111",
      "token": "416B4ED27B1700DFC5769D3B70C36DF3A0C5FFB6",
      "card_type": "D",
      "card_brand": "Visa",
      "cardholder_name": "Sheila Mitch",
      "status": "active"
    }
  ]
}

Response fields — top level

FieldTypeDescription
codeintegerHTTP status code (200)
statusstringOK on success
messagestringSuccess on success
dataarrayArray of payment profile objects

data — payment profile object fields

FieldTypeDescription
payment_idintegerUnique identifier for this payment profile
masked_panstringMasked card number — last 4 digits shown (e.g. XXXX1111)
tokenstringCard token associated with this profile
card_typestringCard type — D = Debit, C = Credit
card_brandstringCard network (e.g. Visa, Mastercard)
cardholder_namestringName on the card
statusstringProfile status (e.g. active, inactive)

Response — 400 (Validation Error)

{
  "status": false,
  "code": "400",
  "message": "Not a valid APP ID or APP Key."
}

Response fields

FieldTypeDescription
statusbooleanfalse when authentication fails
codestringHTTP status code as a string ("400")
messagestringError message

Note: This error response uses a different shape — status is a boolean false and code is a string rather than an integer. This indicates an authentication error rather than a data validation error.


Error code reference

statusMeaningTypical cause
OKSuccessPayment profiles returned
falseAuthentication errorApp ID or App Key is invalid

Get ACH Profile

Retrieve all ACH (bank account) profiles linked to a vault customer.


Response — 200 OK

{
  "code": 200,
  "status": "SUCCESS",
  "data": [
    {
      "ach_profile_id": 2290,
      "account_number": "XXXX0510",
      "routing_number": "XXXX0021",
      "payee_name": "John",
      "account_type": "C",
      "entry_class": "Business"
    }
  ]
}

Response fields — top level

FieldTypeDescription
codeintegerHTTP status code (200)
statusstringSUCCESS on success
dataarrayArray of ACH profile objects

data — ACH profile object fields

FieldTypeDescription
ach_profile_idintegerUnique identifier for this ACH profile
account_numberstringMasked bank account number — last 4 digits shown (e.g. XXXX0510)
routing_numberstringMasked bank routing number — last 4 digits shown (e.g. XXXX0021)
payee_namestringName of the account holder
account_typestringAccount type — C = Checking, S = Savings
entry_classstringACH entry class (e.g. Business, Personal)

Response — 400 (Validation Error)

{
  "code": 400,
  "status": "FAILED",
  "errors": "Customer not exist"
}

Response fields

FieldTypeDescription
codeintegerHTTP status code (400)
statusstringFAILED when the request cannot be processed
errorsstringError message describing the reason for failure

Note: errors is returned as a plain string for this endpoint, not an array.


Error code reference

statusMeaningTypical cause
SUCCESSSuccessACH profiles returned
FAILEDValidation errorCustomer ID does not exist in the vault

Get Customer List

Retrieve a paginated list of vault customer profiles.


Response — 200 OK

{
  "code": 200,
  "status": "OK",
  "message": "Success",
  "data": {
    "customers": [
      {
        "vault_id": 100867,
        "customer_name": "Melvin",
        "email": "[email protected]",
        "phone": "6129160161",
        "company": "Home Centers",
        "total_card_count": 0,
        "total_recursive_billing": 0,
        "transaction_count": 0,
        "last_txn_date": null
      }
    ]
  },
  "number_of_records": 1,
  "page_number": 1,
  "total_pages": 61,
  "total_count": 61,
  "page_size": 1
}

Response fields — top level

FieldTypeDescription
codeintegerHTTP status code (200)
statusstringOK on success
messagestringSuccess on success
dataobjectContains the customers array
number_of_recordsintegerNumber of customer records returned on this page
page_numberintegerCurrent page number
total_pagesintegerTotal number of pages available
total_countintegerTotal number of vault customers
page_sizeintegerNumber of records per page

data.customers — customer object fields

FieldTypeDescription
vault_idintegerUnique vault customer identifier
customer_namestringCustomer's full name
emailstringCustomer email address
phonestringCustomer phone number
companystringCompany name, if provided
total_card_countintegerNumber of card payment profiles linked to this customer
total_recursive_billingintegerNumber of active recurring billing schedules linked to this customer
transaction_countintegerTotal number of transactions associated with this customer
last_txn_datestring | nullDate of the most recent transaction; null if no transactions on record

Response — 400 (Authentication Error)

{
  "status": false,
  "code": "400",
  "message": "Please provide a valid APP ID or APP Key."
}

Response fields

FieldTypeDescription
statusbooleanfalse when authentication fails
codestringHTTP status code as a string ("400")
messagestringError message

Note: This error response uses a different shape — status is a boolean false and code is a string. This indicates an authentication error rather than a data validation error.


Error code reference

statusMeaningTypical cause
OKSuccessCustomer list returned
falseAuthentication errorApp ID or App Key is invalid or not provided

Delete ACH Profile

Remove an ACH profile from a customer vault record.


Response — 200 OK

{
  "code": 200,
  "status": "SUCCESS",
  "ach_profile_id": "2290"
}

Response fields

FieldTypeDescription
codeintegerHTTP status code (200)
statusstringSUCCESS on success
ach_profile_idstringIdentifier of the deleted ACH profile

Response — 400 (Validation Error)

{
  "code": 400,
  "status": "FAILED",
  "errors": "ACH profile ID does not exist"
}

Response fields

FieldTypeDescription
codeintegerHTTP status code (400)
statusstringFAILED when the request cannot be processed
errorsstringError message describing the reason for failure

Note: errors is returned as a plain string for this endpoint, not an array.


Error code reference

statusMeaningTypical cause
SUCCESSSuccessACH profile deleted
FAILEDValidation errorACH profile ID not found

Delete Customer Address

Remove a saved address from a customer vault profile.


Response — 200 OK

{
  "code": 200,
  "status": "OK",
  "message": "Success"
}

Response fields

FieldTypeDescription
codeintegerHTTP status code (200)
statusstringOK on success
messagestringSuccess on success

Response — 400 (Validation Error)

{
  "code": 400,
  "status": "FAILED",
  "errors": [
    "Unable to delete the address."
  ]
}

Response fields

FieldTypeDescription
codeintegerHTTP status code (400)
statusstringFAILED when the request cannot be processed
errorsarrayList of validation error messages

Error code reference

statusMeaningTypical cause
OKSuccessCustomer address deleted
FAILEDValidation errorAddress ID not found or address cannot be deleted

Delete Customer Profile

Permanently remove a customer profile and all associated data from the vault.


Response — 200 OK

{
  "code": 200,
  "status": "OK",
  "message": "Success"
}

Response fields

FieldTypeDescription
codeintegerHTTP status code (200)
statusstringOK on success
messagestringSuccess on success

Response — 400 (Validation Error)

{
  "code": 400,
  "status": "FAILED",
  "errors": [
    "Customer not exist"
  ]
}

Response fields

FieldTypeDescription
codeintegerHTTP status code (400)
statusstringFAILED when the request cannot be processed
errorsarrayList of validation error messages

Error code reference

statusMeaningTypical cause
OKSuccessCustomer profile deleted
FAILEDValidation errorCustomer ID does not exist in the vault

Delete Payment Profile

Remove a card payment profile from a customer vault record.


Response — 200 OK

{
  "code": 200,
  "status": "OK",
  "message": "Success"
}

Response fields

FieldTypeDescription
codeintegerHTTP status code (200)
statusstringOK on success
messagestringSuccess on success

Response — 400 (Validation Error)

{
  "code": 400,
  "status": "FAILED",
  "errors": [
    "Unable to delete the payment profile"
  ]
}

Response fields

FieldTypeDescription
codeintegerHTTP status code (400)
statusstringFAILED when the request cannot be processed
errorsarrayList of validation error messages

Error code reference

statusMeaningTypical cause
OKSuccessPayment profile deleted
FAILEDValidation errorPayment profile ID not found or cannot be deleted