Customer

Set up customer profiles. You will need these profiles to store credit cards and use those credit cards for different payment types.

BASE URI

https://apigateway.payfirma.com/customer-service

Create a customer

Create a new customer profile using provided information

HTTPS POST

/customer

Request Arguments

Request Arguments
email REQUIRED	The email address associated with the customer that will receive the receipt, if that attribute is set to true.
first_name	The first name of the customer.
last_name	The customers last name.
company	Business name associated with customer.
bcc_emails	Additional email the receipt should be sent to for expense tracking or accounting needs.
telephone	Customer’s telephone number.
address1	First line of the customer address.
address2	Second line of the customer address.
city	The city where the customer is.
province	The province where Canadian customer reside. For US Customers, this would be the State of residence.
country	The country where the customer is. All country codes should be in ISO 3166 Alpha 2. For Canada, use CA. For United States, use US.
postal_code	The 6 digit address code for Canadian customer. US customers will use a 5-9 digit Zip Code.
custom_id	A description field to record any general customer identifying information.

Response Attributes

Response Attributes
id number	Internal ID representation.
lookup_id string	A hashed identifier used to identify and access saved customers, cards, plans and subscriptions.
email string	The email address associated with the customer that will receive the receipt, if that attribute is set to true.
first_name string	The first name of the customer.
last_name string	The customers last name.
company string	Business name associated with customer.
bcc_emails string	Additional email the receipt should be sent to for expense tracking or accounting needs.
telephone string	Customer’s telephone number.
address1 string	First line of the customer address.
address2 string	Second line of the customer address.
city string	The city where the customer is.
province string	The province where Canadian customer reside. For US Customers, this would be the State of residence.
country string	The country where the customer is. All country codes should be in ISO 3166 Alpha 2. For Canada, use CA. For United States, use US.
postal_code string	The 6 digit address code for Canadian customer. US customers will use a 5-9 digit Zip Code.
custom_id string	A description field to record any general customer identifying information.
cards array	All the non-PCI card details stored with a customer profile.
subscriptions array	All the subscription info for the subscriptions stored with a customer profile.

Example Request:

curl --include \
     --request POST \
     --header "Content-Type: application/json" \
     --header "Authorization: Bearer eyJhbGciOiJIUzI1NiJ9.eyJhY2Nlc3NfdG9rZW4iOiIxM2EyN2ViZS1iZTEwLTQzY2ItYjFmOC1lYjY4ZWEwOGFlNGIiLCJleHAiOjE0NTcwNTU0NjN9._KIfokRmM38MjP-q2pxB6Lk_-dcg2VnLg9QiuwksxKU" \
     --data-binary "{
  \"email\": \"brandon@stark.com\",
  \"first_name\": \"Brandon\",
  \"last_name\": \"Stark\",
  \"company\": \"Payfirma\",
  \"bcc_emails\": \"john.snow@stark.com\",
  \"telephone\": \"1234567891\",
  \"address1\": \"No. 1 Road\",
  \"address2\": \"Street 2\",
  \"city\": \"Vancouver\",
  \"province\": \"BC\",
  \"country\": \"Canada\",
  \"postal_code\": \"V6E 1B2\",
  \"custom_id\": \"Internal456\"
}" \
"https://apigateway.payfirma.com/customer-service/customer"

Example Response Body:

{
  'id': 2992429,
  'lookup_id': 'NV0B6eZB06',
  'email': 'brandon@stark.com',
  'first_name': 'Brandon',
  'last_name': 'Stark',
  'company': 'Payfirma',
  'bcc_emails': 'john.snow@stark.com',
  'telephone': '1234567891',
  'address1': 'No. 1 Road',
  'address2': 'Street 2',
  'city': 'Vancouver',
  'province': 'BC',
  'country': 'Canada',
  'postal_code': 'V6E 1B2',
  'custom_id': 'Internal456',
  'cards':[{"id":123456,"lookup_id":"34cvb54564dfc","card_expiry":"01/20","card_prefix":"4111","card_suffix":"1111","is_default":true,"card_description":"test card"}],
  'subscriptions':[{"id":123456,"lookup_id":"34cvb54564dfc","plan_id":987654,"plan_lookup_id":"98Avb98765dfc","name":"Sample Daily Plan","status":"ACTIVE","amount":10.99,"currency":"CAD","frequency":"DAILY","last_success":1467760023000,"last_run":1467760023000,"next_run":1467760023000,"total_cycles":10,"completed_cycles":3,"remaining_cycles":7,"failed_attempts":1,"delinquent_cycles":0,"delinquent_since":1467760023000}],
}

Retrieve a specific customer

Get all the attributes of a specific customer profile by using their lookup_id.

HTTPS GET

/customer/{customer_lookup_id}

URI Parameters

URI Parameters
customer_lookup_id	A hashed version of the customer_id used to identify the customer in the customer service.

Response Attributes

Response Attributes
id number	Internal ID representation.
lookup_id string	A hashed identifier used to identify and access saved customers, cards, plans and subscriptions.
email string	The email address associated with the customer that will receive the receipt, if that attribute is set to true.
first_name string	The first name of the customer.
last_name string	The customers last name.
company string	Business name associated with customer.
bcc_emails string	Additional email the receipt should be sent to for expense tracking or accounting needs.
telephone string	Customer’s telephone number.
address1 string	First line of the customer address.
address2 string	Second line of the customer address.
city string	The city where the customer is.
province string	The province where Canadian customer reside. For US Customers, this would be the State of residence.
country string	The country where the customer is. All country codes should be in ISO 3166 Alpha 2. For Canada, use CA. For United States, use US.
postal_code string	The 6 digit address code for Canadian customer. US customers will use a 5-9 digit Zip Code.
custom_id string	A description field to record any general customer identifying information.
cards array	All the non-PCI card details stored with a customer profile.
subscriptions array	All the subscription info for the subscriptions stored with a customer profile.

Example Request:

curl --include \
     --header "Content-Type: application/json" \
     --header "Authorization: Bearer eyJhbGciOiJIUzI1NiJ9.eyJhY2Nlc3NfdG9rZW4iOiIxM2EyN2ViZS1iZTEwLTQzY2ItYjFmOC1lYjY4ZWEwOGFlNGIiLCJleHAiOjE0NTcwNTU0NjN9._KIfokRmM38MjP-q2pxB6Lk_-dcg2VnLg9QiuwksxKU" \
  "https://apigateway.payfirma.com/customer-service/customer/NV0B6eZB06"

Example Response Body:

Retrieve all customers for a specific account

Requests a list of all customers according to the parameters you specify.

HTTPS GET

/customer{?limit,before,after,email_address,first_name,last_name,company,with_subscription}

URI Parameters

URI Parameters
limit	The number of transactions to be displayed within each page.
before	The begginning of the page cursor. One can use this cursor with a query parameter to get the page before this page.
after	The end of the page cursor. One can use this cursor with an after query parameter to get the page after this page.
email_address	The email address associated with the customer that will receive the receipt, if that attribute is set to true.
first_name	The first name of the customer.
last_name	The customers last name.
company	Business name associated with customer.
with_subscription	A boolean identity for whether customers have subscriptions.

Response Attributes

Response Attributes
entities array	The stored customer information that was associated with each transaction.
paging object	Parameter to view multiple pages on large queries.
cursors object	Set the boundaries for displayed results.
before string	The begginning of the page cursor. One can use this cursor with a query parameter to get the page before this page.
after string	The end of the page cursor. One can use this cursor with an after query parameter to get the page after this page.

Example Request:

Example Response Body:

Retrieve plan's customers

Query all customers who subscribed to a given plan lookup Id

HTTPS GET

/customer/plan/{plan_lookup_id}/{?limit,before,after,email_address,first_name,last_name,company}

URI Parameters

URI Parameters
limit	The number of transactions to be displayed within each page.
before	The begginning of the page cursor. One can use this cursor with a query parameter to get the page before this page.
after	The end of the page cursor. One can use this cursor with an after query parameter to get the page after this page.
email_address	The email address associated with the customer that will receive the receipt, if that attribute is set to true.
first_name	The first name of the customer.
last_name	The customers last name.
company	Business name associated with customer.
with_subscription	A boolean identity for whether customers have subscriptions.

Response Attributes

Response Attributes
entities array	The stored customer information that was associated with each transaction.
paging object	Parameter to view multiple pages on large queries.
cursors object	Set the boundaries for displayed results.
before string	The begginning of the page cursor. One can use this cursor with a query parameter to get the page before this page.
after string	The end of the page cursor. One can use this cursor with an after query parameter to get the page after this page.

Example Request:

Example Response Body:

Update a customer

Change the attributes of a customer profile using their customer lookup_id.

HTTPS PUT

/customer/{customer_lookup_id}

URI Parameters

URI Parameters

customer_lookup_id

REQUIRED

A hashed version of the customer_id used to identify the customer in the customer service.

Request Arguments

Request Arguments
email	The email address associated with the customer that will receive the receipt, if that attribute is set to true.
first_name	The first name of the customer.
last_name	The customers last name.
company	Business name associated with customer.
bcc_emails	Additional email the receipt should be sent to for expense tracking or accounting needs.
telephone	Customer’s telephone number.
address1	First line of the customer address.
address2	Second line of the customer address.
city	The city where the customer is.
province	The province where Canadian customer reside. For US Customers, this would be the State of residence.
country	The country where the customer is. All country codes should be in ISO 3166 Alpha 2. For Canada, use CA. For United States, use US.
postal_code	The 6 digit address code for Canadian customer. US customers will use a 5-9 digit Zip Code.
custom_id	A description field to record any general customer identifying information.

Response Attributes

Response Attributes
id number	Internal ID representation.
lookup_id string	A hashed identifier used to identify and access saved customers, cards, plans and subscriptions.
email string	The email address associated with the customer that will receive the receipt, if that attribute is set to true.
first_name string	The first name of the customer.
last_name string	The customers last name.
company string	Business name associated with customer.
bcc_emails string	Additional email the receipt should be sent to for expense tracking or accounting needs.
telephone string	Customer’s telephone number.
address1 string	First line of the customer address.
address2 string	Second line of the customer address.
city string	The city where the customer is.
province string	The province where Canadian customer reside. For US Customers, this would be the State of residence.
country string	The country where the customer is. All country codes should be in ISO 3166 Alpha 2. For Canada, use CA. For United States, use US.
postal_code string	The 6 digit address code for Canadian customer. US customers will use a 5-9 digit Zip Code.
custom_id string	A description field to record any general customer identifying information.
cards array	All the non-PCI card details stored with a customer profile.
subscriptions array	All the subscription info for the subscriptions stored with a customer profile.

Example Request:

Example Request Body:

Example Response Body:

Card

Store a credit card with a customer profile and update the card object as needed.

BASE URI

https://apigateway.payfirma.com/customer-service

Add a new card

Store a new credit card to a customer profile.

HTTPS POST

/customer/{customer_lookup_id}/card

URI Parameters

URI Parameters

customer_lookup_id

REQUIRED

A hashed version of the customer_id used to identify the customer in the customer service.

Request Arguments

Request Arguments
card_expiry_month REQUIRED	The double-digit month the card expires, e.g. for August, use 08.
card_expiry_year REQUIRED	Expiry year - in double digits - of the associated credit card number, e.g. for 2017, use 17.
card_number REQUIRED	The credit card number (16 digits for most card brands and 15 digits for American Express).
cvv2 REQUIRED	A credit card’s verification code, otherwise known as CVC or CVV; the three or four-digit number on the back of most major cards, and the four digit number found on the front of American Express cards. We strongly recommend that you utilize the cvv2 field to help protect against fraud and charge-backs.
currency	DEFAULT is true for first card and false for the rest.

Response Attributes

Response Attributes
id number	Internal ID representation.
lookup_id string	A hashed identifier used to identify and access saved customers, cards, plans and subscriptions.
email string	The email address associated with the customer that will receive the receipt, if that attribute is set to true.
first_name string	The first name of the customer.
last_name string	The customers last name.
company string	Business name associated with customer.
bcc_emails string	Additional email the receipt should be sent to for expense tracking or accounting needs.
telephone string	Customer’s telephone number.
address1 string	First line of the customer address.
address2 string	Second line of the customer address.
city string	The city where the customer is.
province string	The province where Canadian customer reside. For US Customers, this would be the State of residence.
country string	The country where the customer is. All country codes should be in ISO 3166 Alpha 2. For Canada, use CA. For United States, use US.
postal_code string	The 6 digit address code for Canadian customer. US customers will use a 5-9 digit Zip Code.
custom_id string	A description field to record any general customer identifying information.
cards array	All the non-PCI card details stored with a customer profile.
subscriptions array	All the subscription info for the subscriptions stored with a customer profile.

Example Request:

Example Request Body:

Example Response Body:

Update a card

Update an existing credit card object.

HTTPS PATCH

/customer/{customer_lookup_id}/card/{card_lookup_id}

URI Parameters

URI Parameters

customer_lookup_id

REQUIRED

A hashed version of the customer_id used to identify the customer in the customer service.

card_lookup_id

REQUIRED

Credit card Lookup ID from Customer Vault.

Request Arguments

Request Arguments
is_default	DEFAULT is true for first card and false for the rest.
card_description	A description you can define for each card to help with card management and tracking.

Response Attributes

Response Attributes
id number	Internal ID representation.
lookup_id string	A hashed identifier used to identify and access saved customers, cards, plans and subscriptions.
email string	The email address associated with the customer that will receive the receipt, if that attribute is set to true.
first_name string	The first name of the customer.
last_name string	The customers last name.
company string	Business name associated with customer.
bcc_emails string	Additional email the receipt should be sent to for expense tracking or accounting needs.
telephone string	Customer’s telephone number.
address1 string	First line of the customer address.
address2 string	Second line of the customer address.
city string	The city where the customer is.
province string	The province where Canadian customer reside. For US Customers, this would be the State of residence.
country string	The country where the customer is. All country codes should be in ISO 3166 Alpha 2. For Canada, use CA. For United States, use US.
postal_code string	The 6 digit address code for Canadian customer. US customers will use a 5-9 digit Zip Code.
custom_id string	A description field to record any general customer identifying information.
cards array	All the non-PCI card details stored with a customer profile.
subscriptions array	All the subscription info for the subscriptions stored with a customer profile.

Example Request:

Example Request Body:

Example Response Body:

Remove a card

Remove a credit card from a customer’s profile.

HTTPS DELETE

/customer/{customer_lookup_id}/card/{card_lookup_id}

URI Parameters

URI Parameters

customer_lookup_id

REQUIRED

A hashed version of the customer_id used to identify the customer in the customer service.

card_lookup_id

REQUIRED

Credit card Lookup ID from Customer Vault.

Response Attributes

Response Attributes
id number	Internal ID representation.
lookup_id string	A hashed identifier used to identify and access saved customers, cards, plans and subscriptions.
email string	The email address associated with the customer that will receive the receipt, if that attribute is set to true.
first_name string	The first name of the customer.
last_name string	The customers last name.
company string	Business name associated with customer.
bcc_emails string	Additional email the receipt should be sent to for expense tracking or accounting needs.
telephone string	Customer’s telephone number.
address1 string	First line of the customer address.
address2 string	Second line of the customer address.
city string	The city where the customer is.
province string	The province where Canadian customer reside. For US Customers, this would be the State of residence.
country string	The country where the customer is. All country codes should be in ISO 3166 Alpha 2. For Canada, use CA. For United States, use US.
postal_code string	The 6 digit address code for Canadian customer. US customers will use a 5-9 digit Zip Code.
custom_id string	A description field to record any general customer identifying information.
cards array	All the non-PCI card details stored with a customer profile.
subscriptions array	All the subscription info for the subscriptions stored with a customer profile.

Example Request:

Example Response Body:

Subscription

Use stored customer profiles and cards to set up subscription payments based off your recurring plans

BASE URI

https://apigateway.payfirma.com/customer-service

Add a new subscription

Subscribe a given customer to a plan

HTTPS POST

/customer/subscription

Request Arguments

Request Arguments
plan_lookup_id REQUIRED	A hashed version of the plan_id used to identify the plan in the customer & plan service.
card_lookup_id REQUIRED	Credit card Lookup ID from Customer Vault.
amount	Transaction amount, in dollars, e.g. 10.99 = 10 dollars and 99 cents.
start_date REQUIRED	UNIX time representation of the start date for a subscription, represented in milliseconds. It should be in future.
email	The email address associated with the customer that will receive the receipt, if that attribute is set to true.
bcc_emails	Additional email the receipt should be sent to for expense tracking or accounting needs.
description	An open field to record any information about the payment you want to appear in the customer’s receipt.

Response Attributes

Response Attributes
id number	Internal ID representation.
lookup_id string	A hashed identifier used to identify and access saved customers, cards, plans and subscriptions.
email string	The email address associated with the customer that will receive the receipt, if that attribute is set to true.
first_name string	The first name of the customer.
last_name string	The customers last name.
company string	Business name associated with customer.
bcc_emails string	Additional email the receipt should be sent to for expense tracking or accounting needs.
telephone string	Customer’s telephone number.
address1 string	First line of the customer address.
address2 string	Second line of the customer address.
city string	The city where the customer is.
province string	The province where Canadian customer reside. For US Customers, this would be the State of residence.
country string	The country where the customer is. All country codes should be in ISO 3166 Alpha 2. For Canada, use CA. For United States, use US.
postal_code string	The 6 digit address code for Canadian customer. US customers will use a 5-9 digit Zip Code.
custom_id string	A description field to record any general customer identifying information.
cards array	All the non-PCI card details stored with a customer profile.
subscriptions array	All the subscription info for the subscriptions stored with a customer profile.

Example Request:

Example Request Body:

Example Response Body:

Update a subscription

Update a subscription: Update the details of a subscription for a given customer lookup_id and a subscription lookup_id.

HTTPS PATCH

/customer/customerLookupId/subscription/subscriptionLookupId

Request Arguments

Request Arguments
status	ACTIVE, CANCELED, PAUSED
card_lookup_id	Credit card Lookup ID from Customer Vault.
amount	Transaction amount, in dollars, e.g. 10.99 = 10 dollars and 99 cents.
email	The email address associated with the customer that will receive the receipt, if that attribute is set to true.
bcc_emails	Additional email the receipt should be sent to for expense tracking or accounting needs.
description	An open field to record any information about the payment you want to appear in the customer’s receipt.

Response Attributes

Response Attributes
id number	Internal ID representation.
lookup_id string	A hashed identifier used to identify and access saved customers, cards, plans and subscriptions.
email string	The email address associated with the customer that will receive the receipt, if that attribute is set to true.
first_name string	The first name of the customer.
last_name string	The customers last name.
company string	Business name associated with customer.
bcc_emails string	Additional email the receipt should be sent to for expense tracking or accounting needs.
telephone string	Customer’s telephone number.
address1 string	First line of the customer address.
address2 string	Second line of the customer address.
city string	The city where the customer is.
province string	The province where Canadian customer reside. For US Customers, this would be the State of residence.
country string	The country where the customer is. All country codes should be in ISO 3166 Alpha 2. For Canada, use CA. For United States, use US.
postal_code string	The 6 digit address code for Canadian customer. US customers will use a 5-9 digit Zip Code.
custom_id string	A description field to record any general customer identifying information.
cards array	All the non-PCI card details stored with a customer profile.
subscriptions array	All the subscription info for the subscriptions stored with a customer profile.

Example Request:

Example Request Body:

Example Response Body:

Cancel a subscription

Cancel a subscription: Cancel all future payments scheduled on a subscription plan by changing the status of the subscription

HTTPS PATCH

/customer/customerLookupId/subscription/subscriptionLookupId

Request Arguments

Request Arguments
status	CANCELLED

Response Attributes

Response Attributes
id number	Internal ID representation.
lookup_id string	A hashed identifier used to identify and access saved customers, cards, plans and subscriptions.
email string	The email address associated with the customer that will receive the receipt, if that attribute is set to true.
first_name string	The first name of the customer.
last_name string	The customers last name.
company string	Business name associated with customer.
bcc_emails string	Additional email the receipt should be sent to for expense tracking or accounting needs.
telephone string	Customer’s telephone number.
address1 string	First line of the customer address.
address2 string	Second line of the customer address.
city string	The city where the customer is.
province string	The province where Canadian customer reside. For US Customers, this would be the State of residence.
country string	The country where the customer is. All country codes should be in ISO 3166 Alpha 2. For Canada, use CA. For United States, use US.
postal_code string	The 6 digit address code for Canadian customer. US customers will use a 5-9 digit Zip Code.
custom_id string	A description field to record any general customer identifying information.
cards array	All the non-PCI card details stored with a customer profile.
subscriptions array	All the subscription info for the subscriptions stored with a customer profile.

Example Request:

Example Request Body:

Example Response Body:

Customer

BASE URI

Create a customer

HTTPS POST

Request Arguments

Request Arguments

Response Attributes

Response Attributes

Retrieve a specific customer

HTTPS GET

URI Parameters

URI Parameters

Response Attributes

Response Attributes

Retrieve all customers for a specific account

HTTPS GET

URI Parameters

URI Parameters

Response Attributes

Response Attributes

Retrieve plan's customers

HTTPS GET

URI Parameters

URI Parameters

Response Attributes

Response Attributes

Update a customer

HTTPS PUT

URI Parameters

URI Parameters

Request Arguments

Request Arguments

Response Attributes

Response Attributes

Card

BASE URI

Add a new card

HTTPS POST

URI Parameters

URI Parameters

Request Arguments

Request Arguments

Response Attributes

Response Attributes

Update a card

HTTPS PATCH

URI Parameters

URI Parameters

Request Arguments

Request Arguments

Response Attributes

Response Attributes

Remove a card

HTTPS DELETE

URI Parameters

URI Parameters

Response Attributes

Response Attributes

Subscription

BASE URI

Add a new subscription

HTTPS POST

Request Arguments

Request Arguments

Response Attributes

Response Attributes

Example Request:

Update a subscription

HTTPS PATCH

Request Arguments

Request Arguments

Response Attributes

Response Attributes

Cancel a subscription

HTTPS PATCH

Request Arguments

Request Arguments

Response Attributes

Response Attributes