Skip to content
payrocdevelopers

Create subscription

Browse API reference

POST/processing-terminals/{processingTerminalId}/subscriptionscreateSubscription

Use this method to assign a customer to a payment plan.

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

When you create a subscription you need to provide a unique subscriptionId that you use to run follow-on actions:

The request includes the following settings:

  • paymentPlanId - Unique identifier of the payment plan that the merchant wants to use. If you don't have the paymentPlanId, use our List Payment Plans method to search for the payment plan.
  • paymentMethod - Object that contains information about the secure token, which represents the customer's card details or bank account details.
  • startDate - Date that you want to start to take payments.

You can also update the settings that the subscription inherited from the payment plan, for example, you can change the amount for each payment. If you change the settings for the subscription, it doesn't change the settings in the payment plan that it's linked to.

Parameters

NameInTypeDescription
Idempotency-KeyRequiredheaderstring

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.

processingTerminalIdRequiredpathstring

Unique identifier that we assigned to the terminal.

Request body

application/json · required
Field Edit request inputs →
  • customFieldsobject[]
    Array of customField objects.
    • namestringrequired
      Name of the custom field.1–56 chars
    • valuestringrequired
      Value for the custom field.1–100 chars
  • descriptionstring
    Description of the subscription. This value replaces the description inherited from the payment plan.1–128 chars
  • endDatestringdate
    Format: YYYY-MM-DD Subscription's end date. Note: If you provide values for both length and endDate, our gateway uses the value for endDate to determine when the subscription should end.
  • lengthintegerint32
    Total number of billing cycles. To indicate that the subscription should run indefinitely, send a value of 0. This value replaces the length inherited from the payment plan. Note: If you provide values for both length and endDate, our gateway uses the value for endDate to determine when the subscription should end.≥ 0
  • namestring
    Name of the subscription. This value replaces the name inherited from the payment plan.5–128 chars
  • pauseCollectionForintegerint32
    Number of billing cycles that the merchant wants to pause payments for. For example, if the merchant wants to offer a free trial period.
  • paymentMethodobjectrequired
    Polymorphic object that contains information about the secure token.
    • secureTokenobject
      Object that contains information about the secure token that represents the customer’s payment details.
      • accountTypestring
        Indicates the customer’s account type. Note: Send a value for accountType only if the secure token represents bank account details.checkingsavings
      • secCodestring
        Indicates how the customer authorized the ACH transaction. Send one of the following values: web – Online transaction. tel – Telephone transaction. ccd – Corporate credit or debit entry for a business bank account. ppd – Pre-arranged transaction. Note: This field is mandatory when the secure token represents ACH bank account details.webtelccdppd
      • tokenstringrequired
        Unique token that the gateway assigned to the payment details.12–19 chars
      • typestringrequired
        Method that the terminal used to take the payment.secureToken
  • paymentPlanIdstringrequired
    Unique identifier that the merchant assigned to the payment plan.1–48 chars
  • 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 for the transaction. The value is in the currency's lowest denomination, for example, cents.<br/> <br/>Important: Do not add the surcharge to the amount parameter in the request. If the transaction is eligible for surcharging, our gateway adds the surcharge to the amount in the request, and then returns the updated amount in the response.
    • descriptionstring
      Description of the transaction.1–1024 chars
    • breakdownobject
      Object that contains information about the taxes to 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 for the transaction. The value is in the currency's lowest denomination, for example, cents.<br/> <br/>Important: Do not add the surcharge to the amount parameter in the request. If the transaction is eligible for surcharging, our gateway adds the surcharge to the amount in the request, and then returns the updated amount in the response.≤ 999999999999
    • descriptionstring
      Description of the transaction.1–1024 chars
    • orderIdstring
      Unique identifier that the merchant assigns to the transaction.1–24 chars
    • breakdownobject
      Object that contains information about the taxes to 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
  • startDatestringdaterequired
    Format: YYYY-MM-DD Subscription's start date.
  • subscriptionIdstringrequired
    Unique identifier that the merchant assigns to the subscription.1–48 chars

Responses

Successful request. We created the subscription.

201 Created · application/json
{
  "currency": "USD",
  "currentState": {
    "nextDueDate": "2024-08-02",
    "outstandingInvoices": 3,
    "paidInvoices": 0,
    "status": "active"
  },
  "customFields": [
    {
      "name": "yourCustomField",
      "value": "abc123"
    }
  ],
  "description": "Premium Club subscription",
  "endDate": "2025-07-01",
  "frequency": "monthly",
  "length": 12,
  "name": "Premium Club",
  "pauseCollectionFor": 0,
  "paymentPlan": {
    "link": {
      "href": "https://api.payroc.com/v1/processing-terminals/1234001/payment-plans/PlanRef8765",
      "method": "GET",
      "rel": "self"
    },
    "name": "Monthly Premium Club subscription",
    "paymentPlanId": "PlanRef8765"
  },
  "processingTerminalId": "1234001",
  "recurringOrder": {
    "amount": 4999,
    "breakdown": {
      "subtotal": 4347,
      "surcharge": {
        "amount": 217,
        "percentage": 5
      },
      "taxes": [
        {
          "name": "Sales Tax",
          "rate": 5
        }
      ]
    },
    "description": "Premium Club subscription"
  },
  "secureToken": {
    "customerName": "Sarah Hazel Hopper",
    "link": {
      "href": "https://api.payroc.com/v1/processing-terminals/1234001/secure-tokens/MREF_abc1de23-f4a5-6789-bcd0-12e345678901fa",
      "method": "GET",
      "rel": "self"
    },
    "secureTokenId": "MREF_abc1de23-f4a5-6789-bcd0-12e345678901fa",
    "status": "notValidated",
    "token": "296753123456"
  },
  "setupOrder": {
    "amount": 4999,
    "breakdown": {
      "subtotal": 4347,
      "surcharge": {
        "amount": 217,
        "percentage": 5
      },
      "taxes": [
        {
          "name": "Sales Tax",
          "rate": 5
        }
      ]
    },
    "description": "Initial setup fee for Premium Club subscription",
    "orderId": "OrderRef6543"
  },
  "startDate": "2024-07-02",
  "subscriptionId": "SubRef7654",
  "type": "automatic"
}
Response schema · 52 of 66 fields
  • currencystringrequired
    Currency of the transaction. The value for the currency follows the ISO 4217 standard.AEDAFNALLAMDANGAOAARSAUD+163 more
  • currentStateobjectrequired
    A snapshot of the subscription's current state.
    • nextDueDatestringdate
      Date that the merchant collects the next payment.
    • outstandingInvoicesintegerint32
      Number of payments until the end of the subscription. Our gateway returns a value for outstandingInvoices only if the subscription has an end date or a fixed number of billing cycles.≥ 0
    • paidInvoicesintegerint32required
      Number of payments that the merchant has collected.≥ 0
    • statusstringrequired
      Status of the Subscription. 'active' - Subscription is active. 'completed' - Subscription has reached the end date or the total number of billing cycles. 'cancelled' - Merchant deactivated the subscription. 'suspended' - Subscription is suspended. For example, if the customer misses payments.activecompletedsuspendedcancelled
  • customFieldsobject[]
    Array of customField objects.
    • namestringrequired
      Name of the custom field.1–56 chars
    • valuestringrequired
      Value for the custom field.1–100 chars
  • descriptionstring
    Description of the subscription.1–128 chars
  • endDatestringdate
    Format: YYYY-MM-DD Subscription's end date. Note: If you provide values for both length and endDate, our gateway uses the value for endDate to determine when the subscription should end.
  • frequencystringrequired
    Indicates how often the merchant or the terminal collects a payment from the customer.weeklyfortnightlymonthlyquarterlyyearly
  • lengthintegerint32
    Total number of billing cycles. To indicate that the subscription should run indefinitely, send a value of 0. This value replaces the length inherited from the payment plan. Note: If you provide values for both length and endDate, our gateway uses the value for endDate to determine when the subscription should end.≥ 0
  • namestringrequired
    Name of the subscription.5–128 chars
  • pauseCollectionForintegerint32
    Number of billing cycles that the merchant wants to pause payments for. For example, if the merchant wants to offer a free trial period.≥ 0
  • paymentPlanobjectrequired
    • 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.
    • namestringrequired
      Name of the payment plan.5–128 chars
    • paymentPlanIdstringrequired
      Unique identifier that the merchant assigns to the payment plan.1–48 chars
  • processingTerminalIdstringrequired
    Unique identifier of the terminal that the subscription is linked to.4–50 chars
  • recurringOrderobject
    Object that contains information about the cost of each payment.
    • amountintegerint64
      Total amount for the transaction. The value is in the currency's lowest denomination, for example, cents.<br/> <br/>Important: Do not add the surcharge to the amount parameter in the request. If the transaction is eligible for surcharging, our gateway adds the surcharge to the amount in the request, and then returns the updated amount in the response.
    • descriptionstring
      Description of the transaction.1–1024 chars
    • breakdownobject
      Object that contains information about the surcharge and taxes that apply to the transaction.
      • convenienceFeeobject
        Object that contains information about the convenience fee for the transaction.+1 more fields at deeper levels — see the full spec
      • subtotalintegerint64required
        Total amount for the transaction before tax. The value is in the currency's lowest denomination, for example, cents.
      • surchargeobject
        Object that contains information about the surcharge that we applied to the transaction.+3 more fields at deeper levels — see the full spec
      • taxesobject[]
        Array of tax objects.+3 more fields at deeper levels — see the full spec
  • secureTokenobjectrequired
    Object that contains information about the secure token.
    • customerNamestringrequired
      Customer's name.1–50 chars
    • 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.
    • secureTokenIdstringrequired
      Unique identifier that the merchant assigned to the secure token.1–200 chars
    • statusstringrequired
      Status of the customer's bank account. The processor performs a security check on the customer's bank account and returns the status of the account. Note: Depending on the merchant's account settings, this feature may be unavailable.notValidatedcvvValidatedvalidationFailedissueNumberValidatedcardNumberValidatedbankAccountValidated
    • tokenstringrequired
      Token that the merchant can use in future transactions to represent the customer's payment details. The token: Begins with the six-digit identification number 296753. Contains up to 12 digits. Contains a single check digit that we calculate using the Luhn algorithm.12–19 chars
  • setupOrderobject
    Object that contains information about the initial cost that a customer pays to set up the subscription.
    • amountintegerint64
      Total amount for the transaction. The value is in the currency's lowest denomination, for example, cents.<br/> <br/>Important: Do not add the surcharge to the amount parameter in the request. If the transaction is eligible for surcharging, our gateway adds the surcharge to the amount in the request, and then returns the updated amount in the response.≤ 999999999999
    • descriptionstring
      Description of the transaction.1–1024 chars
    • orderIdstring
      Unique identifier that the merchant assigns to the transaction.1–24 chars
    • breakdownobject
      Object that contains information about the surcharge and taxes that apply to the transaction.
      • convenienceFeeobject
        Object that contains information about the convenience fee for the transaction.+1 more fields at deeper levels — see the full spec
      • subtotalintegerint64required
        Total amount for the transaction before tax. The value is in the currency's lowest denomination, for example, cents.
      • surchargeobject
        Object that contains information about the surcharge that we applied to the transaction.+3 more fields at deeper levels — see the full spec
      • taxesobject[]
        Array of tax objects.+3 more fields at deeper levels — see the full spec
  • startDatestringdaterequired
    Format: YYYY-MM-DD Subscription's start date.
  • subscriptionIdstringrequired
    Unique identifier that the merchant assigned to the subscription.1–48 chars
  • typestringrequired
    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

Used in workflows

manage-subscriptions

Search documentation

API reference169
Guides118
Knowledge38
legal1
Solutions32
Workflows74
↑↓highlight↵openView all search results

Menu

Theme

Sign out

Your saved plans remain in your organization. This browser’s private draft and account view will be cleared.

Talk to an engineer