List payment plans

Browse API reference

GET/processing-terminals/{processingTerminalId}/payment-planslistPaymentPlans

Use this method to return a paginated list of payment plans for a processing terminal.

Note: If you want to view the details of a specific payment plan and you have its paymentPlanId, use our Retrieve Payment Plan method.

Our gateway returns the following information about each payment plan in the list:

Name, length, and currency of the plan
How often our gateway collects each payment
How much our gateway collects for each payment
What happens if the merchant updates or deletes the plan

For each payment plan, we return the paymentPlanId, which you can use to perform follow-on actions.

Parameters

Name	In	Type	Description
`processingTerminalId`Required	path	`string`	Unique identifier that we assigned to the terminal.
`before`	query	`string`	Return the previous page of results before the value that you specify. You can’t send the before parameter in the same request as the after parameter.
`after`	query	`string`	Return the next page of results after the value that you specify. You can’t send the after parameter in the same request as the before parameter.
`limit`	query	`integer`	Limit the maximum number of results that we return for each page.

Responses

Successful request. Returns a paginated list of payment plans.

200 OK · application/json

{
  "count": 0,
  "data": [],
  "hasMore": false,
  "limit": 10,
  "links": []
}

Response schema · 27 of 37 fields

countintegerrequired
Number of results we returned on this page. Note: This might not be the total number of results that match your query.
hasMorebooleanrequired
Indicates whether there is another page of results available.
limitintegerrequired
Maximum number of results that we return for each page.
linksobject[]
Reference links to navigate to the previous page of results or to the next page of results.
- hrefstringrequired
  URL of the target resource.
- methodstringrequired
  HTTP method that you need to use with the target resource.
- relstringrequired
  Indicates the relationship between the current resource and the target resource.
dataobject[]required
Array of paymentPlan objects.
- currencystringrequired
  Currency of the transaction. The value for the currency follows the ISO 4217 standard.AEDAFNALLAMDANGAOAARSAUD+163 more
- customFieldNamesstring[]
  Array of custom fields that you can use in subscriptions linked to the payment plan.
- descriptionstring
  Description of the payment plan.0–128 chars
- frequencystringrequired
  Indicates how often the merchant or the terminal collects a payment from the customer.weeklyfortnightlymonthlyquarterlyyearly
- lengthintegerint32
  Number of payments for the payment plan. To indicate that the payment plan should run indefinitely, send a value of 0.≥ 0
- namestringrequired
  Name of the payment plan.5–128 chars
- onDeletestringrequired
  Indicates what happens to existing subscriptions if the merchant deletes the payment plan. complete Stops existing subscriptions. continue Continues existing subscriptions.completecontinue
- onUpdatestringrequired
  Indicates whether any changes that the merchant makes to the payment plan apply to existing subscriptions. update Changes apply to existing subscriptions. continue Changes don't apply to existing subscriptions.updatecontinue
- paymentPlanIdstringrequired
  Unique identifier that the merchant assigns to the payment plan.1–48 chars
- processingTerminalIdstring
  Unique identifier of the terminal that the payment plan is assigned to.4–50 chars
- typestringrequired
  Indicates how the merchant takes the payment from the customer's account. manual The merchant manually collects payments from the customer. automatic The terminal automatically collects payments from the customer.manualautomatic
- recurringOrderobject
  Object that contains information about the cost of each payment. Note: Send this object only if the value for type is automatic.
  - amountintegerint64
    Total amount before surcharges. The value is in the currency's lowest denomination, for example, cents.
  - descriptionstring
    Description of the transaction.1–1024 chars
  - breakdownobject
    Object that contains information about the taxes that apply to the transaction.+5 more fields at deeper levels — see the full spec
- setupOrderobject
  Object that contains information about the initial cost that a customer pays to set up the subscription.
  - amountintegerint64
    Total amount before surcharges. The value is in the currency's lowest denomination, for example, cents.≤ 999999999999
  - descriptionstring
    Description of the transaction.1–1024 chars
  - breakdownobject
    Object that contains information about the taxes that apply to the transaction.+5 more fields at deeper levels — see the full spec

Invalid request

400 Bad Request · application/problem+json

{
  "detail": "One or more validation errors occurred, see error section for more info",
  "errors": [
    {
      "detail": "invalid date",
      "message": "Expected time, got '' for start_time",
      "parameter": "start_time"
    }
  ],
  "status": 400,
  "title": "Bad request",
  "type": "https://docs.payroc.com/api/errors#bad-request"
}

Response schema · 8 fields

detailstringrequired
Explanation of the problem
errorsobject[]
- detailstring
  Short detail of the validation errors
- messagestring
  Error message
- parameterstring
  The parameter or field causing the issues
statusintegerrequired
Http status code
titlestringrequired
Short description of the issue.
typestringrequired
URI reference identifying the problem type

Identity could not be verified

401 Unauthorized · application/problem+json

{
  "detail": "Your identity could not be verified",
  "status": 401,
  "title": "Not Authorized",
  "type": "https://docs.payroc.com/api/errors#not-authorized"
}

Response schema · 4 fields

detailstringrequired
Explanation of the problem
statusintegerrequired
Http status code
titlestringrequired
Short description of the issue.
typestringrequired
URI reference identifying the problem type

Do not have permissions to perform this action

403 Forbidden · application/problem+json

{
  "detail": "You do not have the required permissions to perform this action",
  "instance": "https://api.payroc.com/v1/exampleResource/3",
  "resource": "exampleResource",
  "status": 403,
  "title": "Forbidden",
  "type": "https://docs.payroc.com/api/errors#forbidden"
}

Response schema · 6 fields

detailstringrequired
Explanation of the problem
instancestring
Resource path the action was attempted on
resourcestring
Resource the action was attempted on
statusintegerrequired
Http status code
titlestringrequired
Short description of the issue.
typestringrequired
URI reference identifying the problem type

Not acceptable

406 Not Acceptable · application/problem+json

{
  "detail": "Resource does not support the representation requested",
  "status": 406,
  "title": "Not acceptable",
  "type": "https://docs.payroc.com/api/errors#not-acceptable"
}

Response schema · 4 fields

detailstringrequired
Explanation of the problem
statusintegerrequired
Http status code
titlestringrequired
Short description of the issue.
typestringrequired
URI reference identifying the problem type

An error has occured

500 Internal Server Error · application/problem+json

{
  "detail": "We are unable to process your request at this time",
  "errors": [
    {
      "message": "Service offline"
    }
  ],
  "status": 500,
  "title": "Api error",
  "type": "https://docs.payroc.com/api/errors#api-error"
}

Response schema · 6 fields

detailstringrequired
Explanation of the problem
errorsobject[]
- messagestring
  Error message
statusintegerrequired
Http status code
titlestringrequired
Short description of the issue.
typestringrequired
URI reference identifying the problem type

Used in workflows

delete-a-payment-plan manage-payment-plans update-a-payment-plan