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 new plan
HTTPS POST
/plan
Example Request:
Example Response Body:
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}
Example Request:
Example Response Body:
Query a specific plan using the plan lookup_id
HTTPS GET
/plan/{plan_lookup_id}
Example Request:
Example Response Body:
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}
Example Request:
Example Response Body:
Delete a plan using the plan lookup_id. Active subscriptions for the deleted plan will continue.
HTTPS DELETE
/plan
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
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.
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
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.
URI Parameters
plan_lookup_id
A hashed version of the plan_id used to identify the plan in the customer & plan service.
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.
URI Parameters
plan_lookup_id
A hashed version of the plan_id used to identify the plan in the customer & plan service.
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
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.
URI Parameters
plan_lookup_id
A hashed version of the plan_id used to identify the plan in the customer & plan service.
