Create payment plan

Browse API reference

POST/processing-terminals/{processingTerminalId}/payment-planscreatePaymentPlan

Use this method to create a payment schedule that you can assign customers to.

Note: This method is part of our Repeat Payments feature. To help you understand how this method works with our Subscriptions endpoints, go to Repeat Payments.

When you create a payment plan you need to provide a unique paymentPlanId that you use to run follow-on actions:

Retrieve Payment Plan - View the details of the payment plan.
Update Payment Plan - Update the details of the payment plan.
Delete Payment Plan - Delete the payment plan.
Create Subscription - Subscribe a customer to the payment plan.

The request includes the following settings:

type - Indicates if our gateway or the merchant collects payments. If the merchant manually collects payments, integrate with the Pay Manual Subscription method.
recurringOrder - Amount of each payment if the gateway automatically collect payments.
setupOrder - Setup fee that our gateway immediately collects from the customer's payment method.
onUpdate and onDelete - Indicates what happens to associated subscriptions if the merchant updates or deletes the payment plan.

Parameters

Name	In	Type	Description
`Idempotency-Key`Required	header	`string`	Unique identifier that you generate for each request. You must use the UUID v4 format for the identifier. For more information about the idempotency key, go to Idempotency.
`processingTerminalId`Required	path	`string`	Unique identifier that we assigned to the terminal.

Request body

application/json · required

Field Edit request inputs →

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
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.
  - subtotalintegerint64required
    Total amount for the transaction before tax. The value is in the currency's lowest denomination, for example, cents.
  - taxesobject[]
    Array of tax objects.+2 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.
  - subtotalintegerint64required
    Total amount for the transaction before tax. The value is in the currency's lowest denomination, for example, cents.
  - taxesobject[]
    Array of tax objects.+2 more fields at deeper levels — see the full spec

Responses

Successful request. We created the payment plan.

201 Created · application/json

{
  "currency": "USD",
  "customFieldNames": [
    "yourCustomField"
  ],
  "description": "Monthly Premium Club subscription",
  "frequency": "monthly",
  "length": 12,
  "name": "Premium Club",
  "onDelete": "complete",
  "onUpdate": "continue",
  "paymentPlanId": "PlanRef8765",
  "processingTerminalId": "1234001",
  "recurringOrder": {
    "amount": 4999,
    "breakdown": {
      "subtotal": 4347,
      "taxes": [
        {
          "name": "Sales Tax",
          "rate": 5
        }
      ]
    },
    "description": "Monthly Premium Club subscription"
  },
  "setupOrder": {
    "amount": 4999,
    "breakdown": {
      "subtotal": 4347,
      "taxes": [
        {
          "name": "Sales Tax",
          "rate": 5
        }
      ]
    },
    "description": "Initial setup fee for Premium Club subscription"
  },
  "type": "automatic"
}

Response schema · 23 of 29 fields

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.
  - subtotalintegerint64required
    Total amount for the transaction before tax. The value is in the currency's lowest denomination, for example, cents.
  - taxesobject[]
    Array of tax objects.+3 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.
  - subtotalintegerint64required
    Total amount for the transaction before tax. The value is in the currency's lowest denomination, for example, cents.
  - taxesobject[]
    Array of tax objects.+3 more fields at deeper levels — see the full spec

Validation error

400 Bad Request · application/problem+json

{
  "detail": "'Idempotency-Key' is already in use against a different request",
  "status": 409,
  "title": "Idempotency-Key in use",
  "type": "https://docs.payroc.com/api/errors#idempotency-key-in-use"
}

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

Conflict

409 Conflict · application/problem+json

{
  "detail": "The resource you attempted to create already exists",
  "instance": "https://api.payroc.com/v1/merchant/12345",
  "status": 409,
  "title": "Resource already exists",
  "type": "https://docs.payroc.com/api/errors#resource-already-exists"
}

Response schema · 13 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
instancestring
Resource path to the existing resource
linkobject
Object that contains HATEOAS links for the resource.
- 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.
statusintegerrequired
Http status code
titlestringrequired
Short description of the issue.
typestringrequired
URI reference identifying the problem type

Unsupported media type

415 Unsupported Media Type · application/problem+json

{
  "detail": "You submitted a payload in an unsupported format",
  "status": 415,
  "title": "Unsupported media type",
  "type": "https://docs.payroc.com/api/errors#unsupported-media-type"
}

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

manage-payment-plans

Create payment plan

Browse API reference

Parameters

Request body

Responses

Used in workflows

Menu

Sign out

Talk to an engineer