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:

{
  '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 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:

curl --include \
     --header "Content-Type: application/json" \
     --header "Authorization: Bearer eyJhbGciOiJIUzI1NiJ9.eyJhY2Nlc3NfdG9rZW4iOiIxM2EyN2ViZS1iZTEwLTQzY2ItYjFmOC1lYjY4ZWEwOGFlNGIiLCJleHAiOjE0NTcwNTU0NjN9._KIfokRmM38MjP-q2pxB6Lk_-dcg2VnLg9QiuwksxKU" \
  "https://apigateway.payfirma.com/customer-service/customer?limit=100&before=%273X67XWEE%27&after=%27XWERE836%27&email_address=%27brandon%40stark.com%27&first_name=%27Brandon%27&last_name=%27Stark%27&company=Payfirma&with_subscription=true"

Example Response Body:

{
  'entities':[{"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}]}],
  'paging': {"cursors":{"before":"51pmdq8z5rdbRWoKYrje","after":"xv9Aq54WEy3RyWEBXypK"}},
}

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:

curl --include \
     --header "Content-Type: application/json" \
     --header "Authorization: Bearer eyJhbGciOiJIUzI1NiJ9.eyJhY2Nlc3NfdG9rZW4iOiIxM2EyN2ViZS1iZTEwLTQzY2ItYjFmOC1lYjY4ZWEwOGFlNGIiLCJleHAiOjE0NTcwNTU0NjN9._KIfokRmM38MjP-q2pxB6Lk_-dcg2VnLg9QiuwksxKU" \
  "https://apigateway.payfirma.com/customer-service/customer/plan/99ffb59876mnb?limit=100&before="3X67XWEE"&after="XWERE836"&email_address="brandon@stark.com"&first_name="Brandon"&last_name="Stark"&company=Payfirma"

Example Response Body:

{
  'entities':[{"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}]}],
  'paging': {"cursors":{"before":"51pmdq8z5rdbRWoKYrje","after":"xv9Aq54WEy3RyWEBXypK"}},
}

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

API: Customer

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