Create payment plan | Payroc

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.

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](https://docs.payroc.com/guides/take-payments/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](https://docs.payroc.com/api/schema/repeat-payments/payment-plans/retrieve) - View the details of the payment plan. - [Update Payment Plan](https://docs.payroc.com/api/schema/repeat-payments/payment-plans/partially-update) - Update the details of the payment plan. - [Delete Payment Plan](https://docs.payroc.com/api/schema/repeat-payments/payment-plans/delete) - Delete the payment plan. - [Create Subscription](https://docs.payroc.com/api/schema/repeat-payments/subscriptions/create) - 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](https://docs.payroc.com/api/schema/repeat-payments/subscriptions/pay) 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.

Authentication

AuthorizationBearer

Bearer authentication of the form Bearer <token>, where token is your auth token.

Path parameters

processingTerminalIdstringRequired4-50 characters

Unique identifier that we assigned to the terminal.

Request

This endpoint expects an object.

paymentPlanIdstringRequired1-48 characters

Unique identifier that the merchant assigns to the payment plan.

namestringRequired5-128 characters

Name of the payment plan.

currencyenumRequired

Currency of the transaction. The value for the currency follows the ISO 4217 standard.

typeenumRequiredDefaults to automatic

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.

Allowed values:

frequencyenumRequired

Indicates how often the merchant or the terminal collects a payment from the customer.

Allowed values:

onUpdateenumRequiredDefaults to continue

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.

Allowed values:

onDeleteenumRequiredDefaults to complete

Indicates what happens to existing subscriptions if the merchant deletes the payment plan.

complete - Stops existing subscriptions.
continue - Continues existing subscriptions.

Allowed values:

descriptionstringOptional0-128 characters

Description of the payment plan.

lengthintegerOptional>=0Defaults to 0

Number of payments for the payment plan.

To indicate that the payment plan should run indefinitely, send a value of 0.

customFieldNameslist of stringsOptional

Array of custom fields that you can use in subscriptions linked to the payment plan.

setupOrderobjectOptional

recurringOrderobjectOptional

Response headers

locationstring

URI reference to created resource.

Response

Successful request. We created the payment plan.

paymentPlanIdstring1-48 characters

Unique identifier that the merchant assigns to the payment plan.

namestring5-128 characters

Name of the payment plan.

currencyenum

Currency of the transaction. The value for the currency follows the ISO 4217 standard.

typeenumDefaults to automatic

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.

Allowed values:

frequencyenum

Indicates how often the merchant or the terminal collects a payment from the customer.

Allowed values:

onUpdateenumDefaults to continue

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.

Allowed values:

onDeleteenumDefaults to complete

Indicates what happens to existing subscriptions if the merchant deletes the payment plan.

complete - Stops existing subscriptions.
continue - Continues existing subscriptions.

Allowed values:

processingTerminalIdstringRead-only4-50 characters

Unique identifier of the terminal that the payment plan is assigned to.

descriptionstring0-128 characters

Description of the payment plan.

lengthinteger>=0Defaults to 0

Number of payments for the payment plan.

To indicate that the payment plan should run indefinitely, send a value of 0.

customFieldNameslist of strings

Array of custom fields that you can use in subscriptions linked to the payment plan.

setupOrderobject

recurringOrderobject

Errors

400

Bad Request Error

401

Unauthorized Error

403

Forbidden Error

406

Not Acceptable Error

409

Conflict Error

415

Unsupported Media Type Error

500

Internal Server Error

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.

1	using Payroc;
2	using System.Threading.Tasks;
3	using Payroc.RepeatPayments.PaymentPlans;
4	using System.Collections.Generic;
5
6	namespace Usage;
7
8	public class Example
9	{
10	public async Task Do() {
11	var client = new PayrocClient();
12
13	await client.RepeatPayments.PaymentPlans.CreateAsync(
14	new CreatePaymentPlansRequest {
15	ProcessingTerminalId = "1234001",
16	IdempotencyKey = "8e03978e-40d5-43e8-bc93-6894a57f9324",
17	Body = new PaymentPlan {
18	PaymentPlanId = "PlanRef8765",
19	Name = "Premium Club",
20	Currency = Currency.Usd,
21	Type = PaymentPlanBaseType.Automatic,
22	Frequency = PaymentPlanBaseFrequency.Monthly,
23	OnUpdate = PaymentPlanBaseOnUpdate.Continue,
24	OnDelete = PaymentPlanBaseOnDelete.Complete,
25	Description = "Monthly Premium Club subscription",
26	Length = 12,
27	CustomFieldNames = new List<string>(){
28	"yourCustomField",
29	}
30	,
31	SetupOrder = new PaymentPlanSetupOrder {
32	Amount = 4999L,
33	Breakdown = new PaymentPlanOrderBreakdown {
34	Subtotal = 4347L,
35	Taxes = new List<RetrievedTax>(){
36	new RetrievedTax {
37	Name = "Sales Tax",
38	Rate = 5
39	},
40	}
41
42	},
43	Description = "Initial setup fee for Premium Club subscription"
44	},
45	RecurringOrder = new PaymentPlanRecurringOrder {
46	Amount = 4999L,
47	Breakdown = new PaymentPlanOrderBreakdown {
48	Subtotal = 4347L,
49	Taxes = new List<RetrievedTax>(){
50	new RetrievedTax {
51	Name = "Sales Tax",
52	Rate = 5
53	},
54	}
55
56	},
57	Description = "Monthly Premium Club subscription"
58	}
59	}
60	}
61	);
62	}
63
64	}

1	{
2	"paymentPlanId": "PlanRef8765",
3	"name": "Premium Club",
4	"currency": "USD",
5	"type": "automatic",
6	"frequency": "monthly",
7	"onUpdate": "continue",
8	"onDelete": "complete",
9	"processingTerminalId": "1234001",
10	"description": "Monthly Premium Club subscription",
11	"length": 12,
12	"customFieldNames": [
13	"yourCustomField"
14	],
15	"setupOrder": {
16	"amount": 4999,
17	"breakdown": {
18	"subtotal": 4347,
19	"taxes": [
20	{
21	"name": "Sales Tax",
22	"rate": 5
23	}
24	]
25	},
26	"description": "Initial setup fee for Premium Club subscription"
27	},
28	"recurringOrder": {
29	"amount": 4999,
30	"breakdown": {
31	"subtotal": 4347,
32	"taxes": [
33	{
34	"name": "Sales Tax",
35	"rate": 5
36	}
37	]
38	},
39	"description": "Monthly Premium Club subscription"
40	}
41	}

Authentication

Path parameters

Headers

Request

Response headers

Response

Errors