B2B API Specification | North Developer

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).


Encrypted values by the PayTrace End-to-end encryption (e2ee) Library
must be used with all customer Profile methods.

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

string

last_activity_days

integer

include_card_number

integer

limit

integer

offset

integer

X-Integrator-Id

string

Maximum:

X-Permalinks

string

Maximum:

Example Response

200 Successful Response

422 Validation Error

Export Customer Profile

get /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

string

Maximum:

X-Permalinks

string

Maximum:

Request Schema

customer_label

string

Example:

customer_label

created

object

string

Maximum:

Example:

email@domain.com

include_bin

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

integer

allow_partial

integer

Default:

X-Integrator-Id

string

Maximum:

X-Permalinks

string

Maximum:

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

integer

X-Integrator-Id

string

Maximum:

X-Permalinks

string

Maximum:

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.


Encrypted values must be used with this request.

Parameters

customer_id required

integer

X-Integrator-Id

string

Maximum:

X-Permalinks

string

Maximum:

Request Schema

credit_card

object

check

object

billing_address

object

shipping_address

object

string

Maximum:

Example:

email@domain.com

phone

string

Maximum:

Example:

555-555-5555

fax

string

Maximum:

Example:

555-555-5555

discretionary_data

array

customer_label

string

Maximum:

Example:

customer_label

merchant_id

integer

Example:

246810

Example Request

{
  "credit_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": "USA"
  },
  "shipping_address": {
    "name": "Steve Smith",
    "street_address": "1 Main St.",
    "street_address2": "Suite 12",
    "city": "Spokane",
    "state": "WA",
    "postal_code": "85284",
    "country": "USA",
    "county": "Oakland"
  },
  "email": "email@domain.com",
  "phone": "555-555-5555",
  "fax": "555-555-5555",
  "discretionary_data": {
    "disc_id": 9501,
    "value": "Field value 1"
  },
  "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

string

Maximum:

X-Permalinks

string

Maximum:

Request Schema

credit_card

object

check

object

billing_address

object

shipping_address

object

string

Maximum:

Example:

email@domain.com

phone

string

Maximum:

Example:

555-555-5555

fax

string

Maximum:

Example:

555-555-5555

discretionary_data

array

customer_label required

string

Maximum:

Example:

customer_label

merchant_id

integer

Example:

246810

Example Request

{
  "credit_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": "USA"
  },
  "shipping_address": {
    "name": "Steve Smith",
    "street_address": "1 Main St.",
    "street_address2": "Suite 12",
    "city": "Spokane",
    "state": "WA",
    "postal_code": "85284",
    "country": "USA",
    "county": "Oakland"
  },
  "email": "email@domain.com",
  "phone": "555-555-5555",
  "fax": "555-555-5555",
  "discretionary_data": {
    "disc_id": 9501,
    "value": "Field value 1"
  },
  "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.


Encrypted values by the PayTrace Client-Side Encryption JavaScript
Library must be used with this request.

Parameters

X-Integrator-Id

string

Maximum:

X-Permalinks

string

Maximum:

Request Schema

transaction_id required

string

Example:

123456789

billing_address

object

shipping_address

object

string

Maximum:

Example:

email@domain.com

phone

string

Maximum:

Example:

555-555-5555

fax

string

Maximum:

Example:

555-555-5555

discretionary_data

array

customer_label required

string

Maximum:

Example:

customer_label

customer_reference_id

string

Maximum:

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": "USA"
  },
  "shipping_address": {
    "name": "Steve Smith",
    "street_address": "1 Main St.",
    "street_address2": "Suite 12",
    "city": "Spokane",
    "state": "WA",
    "postal_code": "85284",
    "country": "USA",
    "county": "Oakland"
  },
  "email": "email@domain.com",
  "phone": "555-555-5555",
  "fax": "555-555-5555",
  "discretionary_data": {
    "disc_id": 9501,
    "value": "Field value 1"
  },
  "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

string

Maximum:

X-Permalinks

string

Maximum:

Request Schema

hpf_token required

string

Example:

e369847e-3027-4174-9161-fa0d4e98d318

enc_key required

string

Example:

lI785yOBMet4Rt9o4NLXEyV84WBU3tdStExcsfoaOoo=

billing_address

object

shipping_address

object

string

Maximum:

Example:

email@domain.com

phone

string

Maximum:

Example:

555-555-5555

fax

string

Maximum:

Example:

555-555-5555

discretionary_data

array

customer_label required

string

Maximum:

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": "USA"
  },
  "shipping_address": {
    "name": "Steve Smith",
    "street_address": "1 Main St.",
    "street_address2": "Suite 12",
    "city": "Spokane",
    "state": "WA",
    "postal_code": "85284",
    "country": "USA",
    "county": "Oakland"
  },
  "email": "email@domain.com",
  "phone": "555-555-5555",
  "fax": "555-555-5555",
  "discretionary_data": {
    "disc_id": 9501,
    "value": "Field value 1"
  },
  "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

integer

X-Integrator-Id

string

Maximum:

X-Permalinks

string

Maximum:

Request Schema

hpf_token required

string

Example:

e369847e-3027-4174-9161-fa0d4e98d318

enc_key required

string

Example:

lI785yOBMet4Rt9o4NLXEyV84WBU3tdStExcsfoaOoo=

billing_address

object

shipping_address

object

string

Maximum:

Example:

email@domain.com

phone

string

Maximum:

Example:

555-555-5555

fax

string

Maximum:

Example:

555-555-5555

discretionary_data

array

customer_label

string

Maximum:

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": "USA"
  },
  "shipping_address": {
    "name": "Steve Smith",
    "street_address": "1 Main St.",
    "street_address2": "Suite 12",
    "city": "Spokane",
    "state": "WA",
    "postal_code": "85284",
    "country": "USA",
    "county": "Oakland"
  },
  "email": "email@domain.com",
  "phone": "555-555-5555",
  "fax": "555-555-5555",
  "discretionary_data": {
    "disc_id": 9501,
    "value": "Field value 1"
  },
  "customer_label": "customer_label"
}

Example Response

200 Successful Response

422 Validation Error