Skip to main content

Customer Vault: Billing IDs

Updated

Table of Contents

  1. Overview
  2. Adding A Billing Record
  3. Updating A Billing Record
  4. Deleting a Billing Record
  5. Additional Notes

Overview

The Customer Vault is designed to allow merchants to transmit their payment information through a Secure Sockets Layer (SSL) connection for storage in our Level 1 PCI certified data facility.

When using the Customer Vault with the Payment API, you can manipulate not only Customer Vault records, but also the billing records within a Customer Vault record. Each billing record belongs to a Billing ID for each customer. Just like with Customer Vault records, you can add, delete, and update Billing IDs. This allows you to adjust the billing methods that belong to a customer through the API.

Adding A Billing Record

Below is an example of a request to the Payment API that would add a new billing record to the pre-existing Customer Vault record of Customer Vault ID TestCustomerVault1.

PARAMS:[
    security_key : your_security_key
    customer_vault : add_billing
    customer_vault_id : TestCustomerVault1
    billing_id : BillingId1
    ccnumber : 4111111111111111
    ccexp : 1225
    first_name : John
    last_name : Smith
    company : Company Inc.
    address1 : 1234 Main St.
    address2 : Apartment 2
    city : Chicago
    state : IL
    zip : 60193
    country : US
    phone : +1 (847) 352 4850
    email : test@example.com
]
  • A billing record can hold either credit card data or ACH (electronic check) data, so if you intended to add an ACH billing method, you would use the variables checkname, checkaba, and checkaccount instead.
  • A billing record cannot hold both credit card and ACH data at the same time.
  • If a Billing ID is not provided, one will be randomly generated by the gateway for the new billing record.
  • The optional variables above like the name, address, phone, etc. only apply to the billing record, and not the customer's shipping information.

Updating A Billing Record

Below is an example of a request to the Payment API that would update the billing record of billing ID BillingId1, belonging to Customer Vault record of Customer Vault ID TestCustomerVault1. This update would change the billing record's credit card number, expiration, address, and email address.

PARAMS:[
    security_key : your_security_key
    customer_vault : update_billing
    customer_vault_id : TestCustomerVault1
    billing_id : BillingId1
    ccnumber : 4000000000002503
    ccexp : 1234
    address1 : 2000 Park Place
    address2 : Condo 3
    email : new@testing.org
]
  • If a Billing ID is not specified, the update will apply the data to the customer's oldest billing record (the record with the highest priority).

Deleting a Billing Record

Below is an example of a request to the Payment API that would delete the billing record of billing ID BillingId1, belonging to Customer Vault record of Customer Vault ID TestCustomerVault1.

PARAMS:[

    security_key : your_security_key
    customer_vault : delete_billing
    customer_vault_id : TestCustomerVault1
    billing_id : BillingId1

]
  • A Billing ID must be specified in order to delete the desired billing record.
  • You cannot delete the last remaining billing record of a Customer Vault record. Instead, delete the Customer Vault record itself to remove the entire Customer Vault record for that customer. Documentation regarding Customer Vault variables can be found on the Integration Portal.

Additional Notes

  • The priority of billing records cannot be changed through the API. Priority is assigned in order of creation (i.e. the first billing ID created will have a priority of 1, the second billing ID created will have a priority of 2, and so on. The newest billing record always has the next lowest priority).
  • This article only applies to billing method records. Shipping address records cannot be individually manipulated through the API at this time.