B2B API Specification

B2B Payment API

Customer Profile (Vault)

What is a Customer Database (Vault) at PayTrace?

PayTrace provides a PCI-compliant Customer Database (Vault) for your account. You can store a customer's billing and payment information in this database with your customer ID (token). This database can eliminate your application requirements for storing sensitive payment information. The customer IDs can be used with future transactions. When an existing Customer ID is used for transactions, the associated billing and payment information from the database will be used.

You can manage your customer profiles using various create, update, delete and export methods in your PayTrace database (Vault).

Get ACH Customer Detail

get /v3/customer/ach/{customer_id}

Pull details of a single ach customer based on the passed in customer_id.

Parameters

customer_id required

Type

integer

X-Integrator-Id

Type

string

Maximum Length

X-Permalinks

Type

string

Maximum Length

Example Response

200 Successful Response

422 Validation Error

Create ACH Customer Profile From Transaction

post /v3/customer/ach/create/by-transaction

Parameters

X-Integrator-Id

Type

string

Maximum Length

X-Permalinks

Type

string

Maximum Length

Request Schema

transaction_id required

Type

string

Example

123456789

billing_address

Type

object

shipping_address

Type

object

Type

string

Maximum Length

Example

email@domain.com

phone

Type

string

Maximum Length

Example

555-555-5555

fax

Type

string

Maximum Length

Example

555-555-5555

discretionary_data

Type

array

customer_label required

Type

string

Maximum Length

Example

customer_label

customer_reference_id

Type

string

Maximum Length

Example

PO123456

Example Request

{
  "transaction_id": "123456789",
  "billing_address": {
    "name": "Steve Smith",
    "street_address": "1 Main St.",
    "street_address2": "Suite 12",
    "city": "Spokane",
    "state": "WA",
    "postal_code": "85284",
    "country": "US"
  },
  "shipping_address": {
    "name": "Steve Smith",
    "street_address": "1 Main St.",
    "street_address2": "Suite 12",
    "city": "Spokane",
    "state": "WA",
    "postal_code": "85284",
    "country": "US",
    "county": "Oakland"
  },
  "email": "email@domain.com",
  "phone": "555-555-5555",
  "fax": "555-555-5555",
  "discretionary_data": {
    "disc_id": "integer",
    "value": "string"
  },
  "customer_label": "customer_label",
  "customer_reference_id": "PO123456"
}

Example Response

200 Successful Response

422 Validation Error

Get Customer List

get /v3/customer

Get a list of customers associated with the account.

This endpoint is useful for a preliminary lookup prior to pulling full details of a single customer. It contains less data and is faster than the Export Customer endpoint.

Parameters

name_filter

Type

string

last_activity_days

Type

integer

include_card_number

Type

integer

limit

Type

integer

offset

Type

integer

X-Integrator-Id

Type

string

Maximum Length

X-Permalinks

Type

string

Maximum Length

Example Response

200 Successful Response

422 Validation Error

Export Customer Profile

post /v3/customer/export

This method can be used to export your existing customer profiles stored in PayTrace's PCI-compliant Customer Database (Vault) for your account.

You can export specific customer profiles by providing optional request parameters.

Parameters

X-Integrator-Id

Type

string

Maximum Length

X-Permalinks

Type

string

Maximum Length

Request Schema

customer_label

Type

string

Example

customer_label

created

Type

object

Type

string

Maximum Length

Example

email@domain.com

include_bin

Type

boolean

Example

false

Example Request

{
  "customer_label": "customer_label",
  "created": {
    "at": "1/25/2024 12:30:22 PM",
    "by": "sandbox_user",
    "from_ip": "11.111.111.11"
  },
  "email": "email@domain.com"
}

Example Response

200 Successful Response

422 Validation Error

Get Customer Detail

get /v3/customer/{customer_id}

Pull details of a single customer based on the passed in customer_id.

Parameters

customer_id required

Type

integer

allow_partial

Type

integer

Default

X-Integrator-Id

Type

string

Maximum Length

X-Permalinks

Type

string

Maximum Length

Example Response

200 Successful Response

422 Validation Error

Delete Customer Profile

delete /v3/customer/{customer_id}

This method can be used to delete any existing customer profile stored in PayTrace's PCI-compliant Customer Database (Vault) for your account.

Parameters

customer_id required

Type

integer

X-Integrator-Id

Type

string

Maximum Length

X-Permalinks

Type

string

Maximum Length

Example Response

200 Successful Response

422 Validation Error

Update Customer Profile

patch /v3/customer/{customer_id}

This method can be used to modify your existing customer profile stored in PayTrace's PCI-compliant Customer Database (Vault) for your account. You can update any data including a new customer label (token) for your customer with this method.

Parameters

customer_id required

Type

integer

X-Integrator-Id

Type

string

Maximum Length

X-Permalinks

Type

string

Maximum Length

Request Schema

card

Type

object

check

Type

object

billing_address

Type

object

shipping_address

Type

object

Type

string

Maximum Length

Example

email@domain.com

phone

Type

string

Maximum Length

Example

555-555-5555

fax

Type

string

Maximum Length

Example

555-555-5555

discretionary_data

Type

array

customer_label

Type

string

Maximum Length

Example

customer_label

merchant_id

Type

integer

Example

246810

Example Request

{
  "card": {
    "number": "htpAmr1TJ2hujwO/ObS8oFG3/AhF3AU0zh4QzgynFJejRxUOoyJ1MTXW54UD6F2cvuDCgLLMjY             u1K8ybAX/Ap4HvsthqdMz5lYhDj1GwcDBUnZQx+upD/8gZNUHnm5S4EZkAXMNT79iwLCd++X97yOatd3             jhjxaC0zdRUABYr6PuVEYa7gXTEO3LIiOuA/noLVhrD7ZPni8dnCluyIk2z2k6OwDdCYFwvgpuuZ/luRb             oG07uYBm1TfHnrLkuCGOxeP7B8Aa0rY1du7GFwXxYadI21AqrgM+DCJLfX156lil0gL4D/ZMQoTIr1hqDr            9WKv92V3M+H6Gsx7z0iCbn+8Ug==",
    "expiration_month": 11,
    "expiration_year": 28
  },
  "check": {
    "account_number": "12345678",
    "routing_number": "325070760",
    "sec_code": "CCD",
    "account_type": "Checking"
  },
  "billing_address": {
    "name": "Steve Smith",
    "street_address": "1 Main St.",
    "street_address2": "Suite 12",
    "city": "Spokane",
    "state": "WA",
    "postal_code": "85284",
    "country": "US"
  },
  "shipping_address": {
    "name": "Steve Smith",
    "street_address": "1 Main St.",
    "street_address2": "Suite 12",
    "city": "Spokane",
    "state": "WA",
    "postal_code": "85284",
    "country": "US",
    "county": "Oakland"
  },
  "email": "email@domain.com",
  "phone": "555-555-5555",
  "fax": "555-555-5555",
  "discretionary_data": {
    "disc_id": "integer",
    "value": "string"
  },
  "customer_label": "customer_label",
  "merchant_id": 246810
}

Example Response

200 Successful Response

422 Validation Error

Create Customer Profile

post /v3/customer/create

This method can be used to store your customer's billing and payment information in PayTrace's PCI-compliant Customer Database (Vault) for your account. You can assign a customer label (token) with this method.

Parameters

X-Integrator-Id

Type

string

Maximum Length

X-Permalinks

Type

string

Maximum Length

Request Schema

card

Type

object

check

Type

object

billing_address

Type

object

shipping_address

Type

object

Type

string

Maximum Length

Example

email@domain.com

phone

Type

string

Maximum Length

Example

555-555-5555

fax

Type

string

Maximum Length

Example

555-555-5555

discretionary_data

Type

array

customer_label required

Type

string

Maximum Length

Example

customer_label

merchant_id

Type

integer

Example

246810

Example Request

{
  "card": {
    "number": "htpAmr1TJ2hujwO/ObS8oFG3/AhF3AU0zh4QzgynFJejRxUOoyJ1MTXW54UD6F2cvuDCgLLMjY             u1K8ybAX/Ap4HvsthqdMz5lYhDj1GwcDBUnZQx+upD/8gZNUHnm5S4EZkAXMNT79iwLCd++X97yOatd3             jhjxaC0zdRUABYr6PuVEYa7gXTEO3LIiOuA/noLVhrD7ZPni8dnCluyIk2z2k6OwDdCYFwvgpuuZ/luRb             oG07uYBm1TfHnrLkuCGOxeP7B8Aa0rY1du7GFwXxYadI21AqrgM+DCJLfX156lil0gL4D/ZMQoTIr1hqDr            9WKv92V3M+H6Gsx7z0iCbn+8Ug==",
    "expiration_month": 11,
    "expiration_year": 28
  },
  "check": {
    "account_number": "htpAmr1TJ2hujwO/ObS8oFG3/AhF3AU0zh4QzgynFJejRxUOoyJ1MTXW54UD6F2cvuDCgLLMjY                     u1K8ybAX/Ap4HvsthqdMz5lYhDj1GwcDBUnZQx+upD/8gZNUHnm5S4EZkAXMNT79iwLCd++X97yOatd3                     jhjxaC0zdRUABYr6PuVEYa7gXTEO3LIiOuA/noLVhrD7ZPni8dnCluyIk2z2k6OwDdCYFwvgpuuZ/luRb                     oG07uYBm1TfHnrLkuCGOxeP7B8Aa0rY1du7GFwXxYadI21AqrgM+DCJLfX156lil0gL4D/ZMQoTIr1hqDr                    9WKv92V3M+H6Gsx7z0iCbn+8Ug==",
    "routing_number": "325070760",
    "sec_code": "CCD",
    "account_type": "Checking"
  },
  "billing_address": {
    "name": "Steve Smith",
    "street_address": "1 Main St.",
    "street_address2": "Suite 12",
    "city": "Spokane",
    "state": "WA",
    "postal_code": "85284",
    "country": "US"
  },
  "shipping_address": {
    "name": "Steve Smith",
    "street_address": "1 Main St.",
    "street_address2": "Suite 12",
    "city": "Spokane",
    "state": "WA",
    "postal_code": "85284",
    "country": "US",
    "county": "Oakland"
  },
  "email": "email@domain.com",
  "phone": "555-555-5555",
  "fax": "555-555-5555",
  "discretionary_data": {
    "disc_id": "integer",
    "value": "string"
  },
  "customer_label": "customer_label",
  "merchant_id": 246810
}

Example Response

200 Successful Response

422 Validation Error

Create Customer Profile From Transaction

post /v3/customer/create/by-transaction

This method can be used to store your customer's billing and payment information in PayTrace's PCI-compliant Customer Database (Vault) from a past transaction. You can assign a customer label (token) with this method.

Parameters

X-Integrator-Id

Type

string

Maximum Length

X-Permalinks

Type

string

Maximum Length

Request Schema

transaction_id required

Type

string

Example

123456789

billing_address

Type

object

shipping_address

Type

object

Type

string

Maximum Length

Example

email@domain.com

phone

Type

string

Maximum Length

Example

555-555-5555

fax

Type

string

Maximum Length

Example

555-555-5555

discretionary_data

Type

array

customer_label required

Type

string

Maximum Length

Example

customer_label

customer_reference_id

Type

string

Maximum Length

Example

PO123456

Example Request

{
  "transaction_id": "123456789",
  "billing_address": {
    "name": "Steve Smith",
    "street_address": "1 Main St.",
    "street_address2": "Suite 12",
    "city": "Spokane",
    "state": "WA",
    "postal_code": "85284",
    "country": "US"
  },
  "shipping_address": {
    "name": "Steve Smith",
    "street_address": "1 Main St.",
    "street_address2": "Suite 12",
    "city": "Spokane",
    "state": "WA",
    "postal_code": "85284",
    "country": "US",
    "county": "Oakland"
  },
  "email": "email@domain.com",
  "phone": "555-555-5555",
  "fax": "555-555-5555",
  "discretionary_data": {
    "disc_id": "integer",
    "value": "string"
  },
  "customer_label": "customer_label",
  "customer_reference_id": "PO123456"
}

Example Response

200 Successful Response

422 Validation Error

Create Customer Profile Using Protect.js

post /v3/customer/create/pt-protect

This method can be used to store your customer's billing and payment information in PayTrace's PCI-compliant Customer Database (Vault). Payment info is represented by hpf token and encryption key, created using the Protect.js UI. You can assign a customer label (token) with this method.

Parameters

X-Integrator-Id

Type

string

Maximum Length

X-Permalinks

Type

string

Maximum Length

Request Schema

hpf_token required

Type

string

Example

e369847e-3027-4174-9161-fa0d4e98d318

enc_key required

Type

string

Example

lI785yOBMet4Rt9o4NLXEyV84WBU3tdStExcsfoaOoo=

billing_address

Type

object

shipping_address

Type

object

Type

string

Maximum Length

Example

email@domain.com

phone

Type

string

Maximum Length

Example

555-555-5555

fax

Type

string

Maximum Length

Example

555-555-5555

discretionary_data

Type

array

customer_label required

Type

string

Maximum Length

Example

customer_label

Example Request

{
  "hpf_token": "e369847e-3027-4174-9161-fa0d4e98d318",
  "enc_key": "lI785yOBMet4Rt9o4NLXEyV84WBU3tdStExcsfoaOoo=",
  "billing_address": {
    "name": "Steve Smith",
    "street_address": "1 Main St.",
    "street_address2": "Suite 12",
    "city": "Spokane",
    "state": "WA",
    "postal_code": "85284",
    "country": "US"
  },
  "shipping_address": {
    "name": "Steve Smith",
    "street_address": "1 Main St.",
    "street_address2": "Suite 12",
    "city": "Spokane",
    "state": "WA",
    "postal_code": "85284",
    "country": "US",
    "county": "Oakland"
  },
  "email": "email@domain.com",
  "phone": "555-555-5555",
  "fax": "555-555-5555",
  "discretionary_data": {
    "disc_id": "integer",
    "value": "string"
  },
  "customer_label": "customer_label"
}

Example Response

200 Successful Response

422 Validation Error

Update Customer Profile Using Protect.js

patch /v3/customer/pt-protect/{customer_id}

This method can be used to modify your existing customer profile stored in PayTrace's PCI-compliant Customer Database (Vault) for your account. Payment info is represented by hpf token and encryption key, created using the Protect.js UI. You can update any data including a new customer label (token) for your customer with this method.

Parameters

customer_id required

Type

integer

X-Integrator-Id

Type

string

Maximum Length

X-Permalinks

Type

string

Maximum Length

Request Schema

hpf_token required

Type

string

Example

e369847e-3027-4174-9161-fa0d4e98d318

enc_key required

Type

string

Example

lI785yOBMet4Rt9o4NLXEyV84WBU3tdStExcsfoaOoo=

billing_address

Type

object

shipping_address

Type

object

Type

string

Maximum Length

Example

email@domain.com

phone

Type

string

Maximum Length

Example

555-555-5555

fax

Type

string

Maximum Length

Example

555-555-5555

discretionary_data

Type

array

customer_label

Type

string

Maximum Length

Example

customer_label

Example Request

{
  "hpf_token": "e369847e-3027-4174-9161-fa0d4e98d318",
  "enc_key": "lI785yOBMet4Rt9o4NLXEyV84WBU3tdStExcsfoaOoo=",
  "billing_address": {
    "name": "Steve Smith",
    "street_address": "1 Main St.",
    "street_address2": "Suite 12",
    "city": "Spokane",
    "state": "WA",
    "postal_code": "85284",
    "country": "US"
  },
  "shipping_address": {
    "name": "Steve Smith",
    "street_address": "1 Main St.",
    "street_address2": "Suite 12",
    "city": "Spokane",
    "state": "WA",
    "postal_code": "85284",
    "country": "US",
    "county": "Oakland"
  },
  "email": "email@domain.com",
  "phone": "555-555-5555",
  "fax": "555-555-5555",
  "discretionary_data": {
    "disc_id": "integer",
    "value": "string"
  },
  "customer_label": "customer_label"
}

Example Response

200 Successful Response

422 Validation Error

Customer Profile (Vault)

Get ACH Customer Detail

Create ACH Customer Profile From Transaction

Get Customer List

Export Customer Profile

Get Customer Detail

Delete Customer Profile

Update Customer Profile

Create Customer Profile

Create Customer Profile From Transaction

Create Customer Profile Using Protect.js

Update Customer Profile Using Protect.js

Contact Us