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. | 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** | | | ------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- | | **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. | 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: ``` { 'plans':[{"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}], 'paging': {"cursors":{"before":"51pmdq8z5rdbRWoKYrje","after":"xv9Aq54WEy3RyWEBXypK"}}, } ``` ### Retrieve a plan Query a specific plan using the plan lookup\_id **HTTPS GET** `/plan/{plan_lookup_id}` | **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. | Example Request: ``` curl --include \ --header "Content-Type: application/json" \ --header "Authorization: Bearer eyJhbGciOiJIUzI1NiJ9.eyJhY2Nlc3NfdG9rZW4iOiIxM2EyN2ViZS1iZTEwLTQzY2ItYjFmOC1lYjY4ZWEwOGFlNGIiLCJleHAiOjE0NTcwNTU0NjN9._KIfokRmM38MjP-q2pxB6Lk_-dcg2VnLg9QiuwksxKU" \ "https://apigateway.payfirma.com/plan-service/plan/99ffb59876mnb" ``` 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, } ``` ### 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** | | | ------------------ | ------------------------------------------------------------------------------------------ | | 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. | Example Request: ``` curl --include \ --request PUT \ --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/99ffb59876mnb" ``` 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, } ``` ### Remove a plan Delete a plan using the plan lookup\_id. Active subscriptions for the deleted plan will continue. **HTTPS DELETE** `/plan` | **URI Parameters** | | | ------------------ | ------------------------------------------------------------------------------------------ | | plan\_lookup\_id | A hashed version of the plan\_id used to identify the plan in the customer & plan service. | ``` curl --include \ --request DELETE \ --header "Content-Type: application/json" \ --header "Authorization: Bearer eyJhbGciOiJIUzI1NiJ9.eyJhY2Nlc3NfdG9rZW4iOiIxM2EyN2ViZS1iZTEwLTQzY2ItYjFmOC1lYjY4ZWEwOGFlNGIiLCJleHAiOjE0NTcwNTU0NjN9._KIfokRmM38MjP-q2pxB6Lk_-dcg2VnLg9QiuwksxKU" \ "https://apigateway.payfirma.com/plan-service/plan/99ffb59876mnb" ```