Sign in

v1

latestOpenAPI 3.1.0Copyright Pismo2026-07-247702,7523.1 MB
Recurring charge plans

Create recurring charge plan

Create a recurring charge plan. A recurring charge is a charge that is applied on a monthly basis for a fixed number of installments. When you create a recurring charge plan, you specify the number of installments (cycles) and the installment amount.

Creating a plan does not activate it. A plan must be linked to an account to activate the charge schedule defined in it.

This endpoint generates a Recurring charge plan created event.

NOTES:

  • To work correctly, you must set the program parameter 504 - RECURRING_CHARGE_FINAL_ACCOUNT_STATUS to the value for an account status. Usually you use CANCELLED for this. When the account enters this status, the system cancels all pending recurring charges. (Note that if you provide more than one value, the system only uses the first one, even though this is a multivalue program parameter.)

  • This endpoint requires an account token — an access token encoded with an account ID. Tokens can expire quickly, which can result in a 401 Unauthorized message.

post/v1/recurring-charge-plans

Headers

x-cidstring

The Correlation IDentifier field is used to link related API requests and events. The x-cid can help the Pismo engineering team track everything related to a call. You can find the x-cid field in the response header from an API endpoint call.

If this field isn't passed, one is automatically generated.

Request body

processing_codestring required

Processing code for the debit transaction.

If split_transaction is false (the default), each installment payment is recorded as one debit transaction equal to the installment amount minus the discount, and processing_code is the processing code for that transaction.

If split_transaction is true, each installment payment is recorded as two transactions: a debit transaction for the installment amount and a credit transaction for the discount. In this case, processing_code is the processsing code for the debit transaction, and second_processing_code is the processing code for the credit transaction.

installment_amountnumber double required

installment_amount is the full amount of an installment before any discount is applied.

descriptionstring

Used if the recurring charge link description is not provided. Use "{counter}" to indicate where the cycle count should be placed. Example: "{counter} Annuity" generates "2/12 Annuity" for the second of twelve installments. If "{counter}" is not present, the counter is placed at the end of the description. If no description is provided, the transaction type's description is used and the counter is not shown.

split_transactionboolean

Use separate transactions for the installment amount and the discount?

Suppose the installment amount for a cycle is $20 and the discount is $2. If split_transaction is false, then one debit transaction for $18 ($20 - $2) is posted to the account for that cycle. It also appears as one debit transaction on the statement. If split_transaction is true, then two transactions are posted to the account — a debit transaction for $20 and a credit transaction for $2 — and those two transactions appear on the statement. When split_transaction is true, secondary_processing_code is used to create the credit transaction.

Note: You aren't forced to specify a debit transaction with processing_code and a credit transaction with secondary_processing_code, but it's highly recommended. It's difficult to think of a scenario where you would want to do something else.

secondary_processing_codestring

Used to create the transaction for secondary_installment_amount. Normally, you should use a processing code for a credit transaction.

secondary_descriptionstring

Used to create a description for the secondary transaction. Use "{counter}" to indicate where the cycle count should be placed. Example: "{counter} Annuity" generates "2/12 Annuity" for the second of twelve installments. If "{counter}" is not present, the counter is be placed at the end of the description. If no description is provided, the transaction type's description is used and the counter is not shown.

number_of_cyclesinteger required

Number of cycles to apply the charge plan. In other words, this is the number of installments. Must be greater than first_cycles_to_discount if used. Otherwise, it must be greater than 0.

first_cycles_to_discountinteger

The number of cycles the discount (defined by discount_percentage) should be applied to before reverting to the full charge. For example, if number_of_cycles is 6 and first_cycles_to_discount is 2, then the discount is applied to cycles 1 and 2. The full charge is applied to cycles 3 through 6. If present, first_cycles_to_discount must be positive and less than number_of_cycles."

discount_percentagenumber double

Percentage value to be discounted if first_cycles_to_discount is configured. Range: 0 to 100.

minimum_spend_to_chargenumber double

Minimum debit amount on statement to enable cycle charging. If minimum_spend_to_charge is not configured, the charge plan does not check the debit statement amount.

renew_method'NO_RENEW' | 'WITHOUT_DISCOUNT' | 'WITH_DISCOUNT'

NO_RENEW: The link does not renew at the end of the cycle. WITHOUT_DISCOUNT: The link is renewed at the end of the cycle, but the discounts registered in the plan are not applied. WITH_DISCOUNT: The link is renewed at the end of the cycle, and the discounts registered in the plan are applied."

tracking_idstring required

Customer created tracking ID. Must consist of alphanumeric characters (a-z, A-Z, 0-9), hyphens (-), and colons (:), with a length from 1 to 128. The Pismo platform uses this field to implement idempotency and prevent duplicates.

Example request

{
  "processing_code": "99066",
  "installment_amount": 10.9,
  "secondary_processing_code": "99067",
  "number_of_cycles": 12,
  "first_cycles_to_discount": 3,
  "discount_percentage": 50,
  "minimum_spend_to_charge": 100,
  "renew_method": "WITH_DISCOUNT",
  "tracking_id": "3368328d-e4c6-4c75-99a9-9d59f3501d8c"
}

Response

OK - The recurring charge plan was created.

recurring_charge_plan_idinteger

ID of recurring charge plan

org_idstring

Organization ID

processing_codestring

Processing code for the debit transaction.

If split_transaction is false (the default), each installment payment is recorded as one debit transaction equal to the installment amount minus the discount, and processing_code is the processing code for that transaction.

If split_transaction is true, each installment payment is recorded as two transactions: a debit transaction for the installment amount and a credit transaction for the discount. In this case, processing_code is the processsing code for the debit transaction, and second_processing_code is the processing code for the credit transaction.

installment_amountnumber double

installment_amount is the full amount of an installment before any discount is applied.

descriptionstring

Used if the recurring charge link description is not provided. Use "{counter}" to indicate where the cycle count should be placed. Example: "{counter} Annuity" generates "2/12 Annuity" for the second of twelve installments. If "{counter}" is not present, the counter is placed at the end of the description. If no description is provided, the transaction type's description is used and the counter is not shown.

split_transactionboolean

Use separate transactions for the installment amount and the discount?

Suppose the installment amount for a cycle is $20 and the discount is $2. If split_transaction is false, then one debit transaction for $18 ($20 - $2) is posted to the account for that cycle. It also appears as one debit transaction on the statement. If split_transaction is true, then two transactions are posted to the account — a debit transaction for $20 and a credit transaction for $2 — and those two transactions appear on the statement. When split_transaction is true, secondary_processing_code is used to create the credit transaction.

Note: You aren't forced to specify a debit transaction with processing_code and a credit transaction with secondary_processing_code, but it's highly recommended. It's difficult to think of a scenario where you would want to do something else.

secondary_processing_codestring

Used to create the transaction for secondary_installment_amount. Normally, you should use a processing code for a credit transaction.

secondary_descriptionstring

Used to create a description for the secondary transaction. Use "{counter}" to indicate where the cycle count should be placed. Example: "{counter} Annuity" generates "2/12 Annuity" for the second of twelve installments. If "{counter}" is not present, the counter is placed at the end of the description. If no description is provided, the transaction type's description is used and the counter is not shown.

number_of_cyclesinteger

Number of cycles to apply the charge plan. In other words, this is the number of installments. Must be greater than first_cycles_to_discount if used. Otherwise, it must be greater than 0.

first_cycles_to_discountinteger

The number of cycles the discount (defined by discount_percentage) should be applied to before reverting to the full charge. For example, if number_of_cycles is 6 and first_cycles_to_discount is 2, then the discount is applied to cycles 1 and 2. The full charge is applied to cycles 3 through 6. If present, first_cycles_to_discount must be positive and less than number_of_cycles."

discount_percentagenumber double

Percentage value to be discounted if first_cycles_to_discount is configured. Range: 0 to 100.

minimum_spend_to_chargenumber double

Minimum debit amount on statement to enable cycle charging. If minimum_spend_to_charge is not configured, the charge plan does not check the debit statement amount.

renew_method'NO_RENEW' | 'WITHOUT_DISCOUNT' | 'WITH_DISCOUNT'

NO_RENEW: The link does not renew at the end of the cycle. WITHOUT_DISCOUNT: The link is renewed at the end of the cycle, but the discounts registered in the plan are not applied. WITH_DISCOUNT: The link is renewed at the end of the cycle, and the discounts registered in the plan are applied."

tracking_idstring

Customer created tracking ID. Must consist of alphanumeric characters (a-z, A-Z, 0-9), hyphens (-), and colons (:), with a length from 1 to 128. The Pismo platform uses this field to implement idempotency and prevent duplicates.

cidstring

The Correlation IDentifier field is used to link related API requests and events. The x-cid can help the Pismo engineering team track everything related to a call.

created_atstring date-time

Datetime program calendar strategy was created. Format = YYYY-MM-DDTHH:MM:SS:MM.

Example response

{
  "recurring_charge_plan_id": 115563,
  "org_id": "TN-cc8f8b89-233a-4582-9f36-63ee85278d6d",
  "processing_code": "99066",
  "installment_amount": 10.9,
  "secondary_processing_code": "99067",
  "number_of_cycles": 12,
  "first_cycles_to_discount": 3,
  "discount_percentage": 50,
  "minimum_spend_to_charge": 100,
  "renew_method": "WITH_DISCOUNT",
  "tracking_id": "3368328d-e4c6-4c75-99a9-9d59f3501d8c",
  "cid": "3ea22692-a209-11eb-89a2-f73e179dcbc2",
  "created_at": "2024-09-12T16:46:16.43663522"
}