Plan

Create and manage the plans that you will need to set up your customers on subscription payments.

BASE URI

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

Create a plan

Create a new plan

HTTPS POST

/plan

Request Arguments

Request Arguments
name REQUIRED	The title you give to each plan, which should be unique for each plan.
amount REQUIRED	Transaction amount, in dollars, e.g. 10.99 = 10 dollars and 99 cents.
currency REQUIRED	Transaction currency, in currency type, e.g. USD, CAD.
frequency REQUIRED	The cycle of how often the card will be charged on the subscription or plan. Choices are: DAILY, WEEKLY, MOTHLY, QUARTERLY, or ANNUALLY.
number_of_payments	The total number of payments within this plan.
send_receipt	Sets whether receipt should be sent after transaction. Default is false.

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.
name string	The title you give to each plan, which should be unique for each plan.
amount number	Transaction amount, in dollars, e.g. 10.99 = 10 dollars and 99 cents.
currency string	Transaction currency, in currency type, e.g. USD, CAD.
frequency string	The cycle of how often the card will be charged on the subscription or plan. Choices are: DAILY, WEEKLY, MOTHLY, QUARTERLY, or ANNUALLY.
number_of_payments number	The total number of payments within this plan.
send_receipt boolean	Sets whether receipt should be sent after transaction. Default is false.
total_subscriptions number	Total number of subscriptions under this plan.
current_subscriptions number	Current number of subscriptions as ACTIVE, RETRY, SUSPENDED and PAUSED.

Example Request:

curl --include \
     --request POST \
     --header "Content-Type: application/json" \
     --header "Authorization: Bearer eyJhbGciOiJIUzI1NiJ9.eyJhY2Nlc3NfdG9rZW4iOiIxM2EyN2ViZS1iZTEwLTQzY2ItYjFmOC1lYjY4ZWEwOGFlNGIiLCJleHAiOjE0NTcwNTU0NjN9._KIfokRmM38MjP-q2pxB6Lk_-dcg2VnLg9QiuwksxKU" \
     --data-binary "{
  \"name\": \"Sample Daily Plan\",
  \"amount\": 10.99,
  \"currency\": \"CAD\",
  \"frequency\": \"DAILY\",
  \"number_of_payments\": 10,
  \"send_receipt\": false
}" \
"https://apigateway.payfirma.com/plan-service/plan"

Example Response Body:

{
  'id': 2992429,
  'lookup_id': '99ffb59876mnb',
  'name': 'Sample Daily Plan',
  'amount': 10.99,
  'currency': 'CAD',
  'frequency': 'DAILY',
  'number_of_payments': 10,
  'send_receipt': false,
  'total_subscriptions': 10,
  'current_subscriptions': 2,
}

Retrieve all plans

Request the list of all plans that are active

HTTPS GET

/plan{?limit,before,after,plan_name,min_amount,max_amount,frequency,min_number_of_total_subscriptions,max_number_of_total_subscriptions,min_number_of_current_subscriptions,max_number_of_current_subscriptions}

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.
plan_name	The name established for the plan.
min_amount	Filter all transactions below the given amount from the result set.
max_amount	Filter all transactions above the given amount from the result set.
frequency	The cycle of how often the card will be charged on the subscription or plan. Choices are: DAILY, WEEKLY, MOTHLY, QUARTERLY, or ANNUALLY.
min_number_of_total_subscriptions	Returns all plans with total number of subscriptions less or equal than the given minimum number.
max_number_of_total_subscriptions	Returns all plans with total number of subscriptions greater or equal than the given maximum number.
min_number_of_current_subscriptions	Returns all plans with current number of subscriptions less or equal than the given minimum number.
max_number_of_current_subscriptions	Returns all plans with current number of subscriptions greater or equal than the given maximum number.

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 beginning 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/plan-service/plan?limit=100&before=%273X67XWEE%27&after=%27XWERE836%27&plan_name=%27Sample%20Daily%20Plan%27&min_amount=7.89&max_amount=799.89&frequency=frequency&min_number_of_total_subscriptions=7&max_number_of_total_subscriptions=70&min_number_of_current_subscriptions=2&max_number_of_current_subscriptions=20"

Example Response Body:

Retrieve a plan

Query a specific plan using the plan lookup_id

HTTPS GET

/plan/{plan_lookup_id}

URI Parameters

URI Parameters
plan_lookup_id	A hashed version of the plan_id used to identify the plan in the customer & plan 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.
name string	The title you give to each plan, which should be unique for each plan.
amount number	Transaction amount, in dollars, e.g. 10.99 = 10 dollars and 99 cents.
currency string	Transaction currency, in currency type, e.g. USD, CAD.
frequency string	The cycle of how often the card will be charged on the subscription or plan. Choices are: DAILY, WEEKLY, MOTHLY, QUARTERLY, or ANNUALLY.
number_of_payments number	The total number of payments within this plan.
send_receipt boolean	Sets whether receipt should be sent after transaction. Default is false.
total_subscriptions number	Total number of subscriptions under this plan.
current_subscriptions number	Current number of subscriptions as ACTIVE, RETRY, SUSPENDED and PAUSED.

Example Request:

Example Response Body:

Update a plan

Update plan attributes using the plan lookup_id. Active subscriptions for this plan will continue with the previous attributes and net new subscriptions will use the new attributes.

HTTPS PUT

/plan/{plan_lookup_id}

URI Parameters

URI Parameters
plan_lookup_id	A hashed version of the plan_id used to identify the plan in the customer & plan service.

Request Arguments

Request Arguments
name REQUIRED	The title you give to each plan, which should be unique for each plan.
amount REQUIRED	Transaction amount, in dollars, e.g. 10.99 = 10 dollars and 99 cents.
currency REQUIRED	Transaction currency, in currency type, e.g. USD, CAD.
frequency REQUIRED	The cycle of how often the card will be charged on the subscription or plan. Choices are: DAILY, WEEKLY, MOTHLY, QUARTERLY, or ANNUALLY.
number_of_payments	The total number of payments within this plan.
send_receipt	Sets whether receipt should be sent after transaction. Default is false.

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.
name string	The title you give to each plan, which should be unique for each plan.
amount number	Transaction amount, in dollars, e.g. 10.99 = 10 dollars and 99 cents.
currency string	Transaction currency, in currency type, e.g. USD, CAD.
frequency string	The cycle of how often the card will be charged on the subscription or plan. Choices are: DAILY, WEEKLY, MOTHLY, QUARTERLY, or ANNUALLY.
number_of_payments number	The total number of payments within this plan.
send_receipt boolean	Sets whether receipt should be sent after transaction. Default is false.
total_subscriptions number	Total number of subscriptions under this plan.
current_subscriptions number	Current number of subscriptions as ACTIVE, RETRY, SUSPENDED and PAUSED.

Example Request:

Example Response Body:

Remove a plan

Delete a plan using the plan lookup_id. Active subscriptions for the deleted plan will continue.

HTTPS DELETE

/plan

URI Parameters

URI Parameters
plan_lookup_id	A hashed version of the plan_id used to identify the plan in the customer & plan service.

public

API: Plan

Plan

BASE URI

Create a plan

HTTPS POST

Request Arguments

Request Arguments

Response Attributes

Response Attributes

Retrieve all plans

HTTPS GET

URI Parameters

URI Parameters

Response Attributes

Response Attributes

Retrieve a plan

HTTPS GET

URI Parameters

URI Parameters

Response Attributes

Response Attributes

Update a plan

HTTPS PUT

URI Parameters

URI Parameters

Request Arguments

Request Arguments

Response Attributes

Response Attributes

Remove a plan

HTTPS DELETE

URI Parameters

URI Parameters