APIs
Sub-processorsAbout PismoContact us

Create recurring charge plan

post
https://sandbox.pismolabs.io/recurring-charge/v1/recurring-charge-plans

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

Creating a plan does not activate it. You must link the plan to an account to activate the charge schedule defined in it.

This endpoint generates a Recurring charge plan created event.

NOTES:

  • If an account is canceled while it has an active recurring charge attached to it, you want the recurring charge to be canceled, too, so that charges don't continue to accrue. To ensure this, set the multivalue 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.

Recent Requests
Log in to see full request history
TimeStatusUser Agent
Retrieving recent requests…
LoadingLoading…
Body Params

Body of a request used to create a recurring charge plan

string
required

Processing code for the debit transaction.

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

If split_transaction is true, each recurring payment is recorded as two transactions: a debit transaction for the payment 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.

double
required

installment_amount is the full amount of a recurring charge before any discount is applied.

string

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 recurring charges. 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.

boolean
Defaults to false

Use separate transactions for the amount of the recurring charge and the discount?

Suppose the recurring charge 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.

string

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

string

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.

int32
required

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

int32

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."

double

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

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.

string
enum

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."

Allowed:
string
required

Tracking ID

Headers
string

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.

Responses

400

Bad Request

409

The specified resource status conflicts with the current request.

500

Internal server error

Updated 4 months ago

Did this page help you?
Language
Credentials
Bearer
JWT
LoadingLoading…
Response
Click Try It! to start a request and see the response here! Or choose an example:
application/json

Updated 4 months ago

Did this page help you?