Create a recurring profile

post

https://test-api.payology.io/customer-vault/api/v1/recurring

Create an ACH or CC recurring. Use exactly one destination: org_bank_account_token for ACH, or terminal_token for CC. X9 profiles are not supported. Example dates must be replaced with dates in the future when executed. The implementation sets HTTP 201.

Result codes in the response examples

HTTP status and result code are operation-specific. Field-validation messages can include the affected field name.

HTTP	Code	Result	Meaning
201	R0000	Ok	The request was processed successfully
400	R0002	Error	Field is not properly formatted
400	R0101	Error	Organization Bank Account token is inactive
400	R0103	Error	Payment Profile token is inactive
400	R0112	Error	Amount must be greater than $0
400	R0241	Error	A recurring first bill date with today's date or a past date is not accepted
400	R0504	Error	Terminal token is inactive
401	R0003	Error	Authentication token is invalid
403	R0003	Error	Access not allowed
404	R0005	Error	Payment Profile token is invalid
404	R0102	Error	Organization Bank Account token is invalid
404	R0502	Error	Terminal not found
500	R0999	Error	Something went wrong

Recent Requests

Time	Status	User Agent
Retrieving recent requests…

Loading…

Body Params

JSON request body. Required and conditional fields are defined by the schema. Named examples show supported request variants.

org_bank_account_token

required

[0-9A-Fa-f]{8}-[0-9A-Fa-f]{4}-4[0-9A-Fa-f]{3}-[89ABab][0-9A-Fa-f]{3}-[0-9A-Fa-f]{12}

UUID of the accessible organization bank account used for this operation.

Stringified UUIDv4.
See RFC 4112

payment_profile_token

string

required

[0-9A-Fa-f]{8}-[0-9A-Fa-f]{4}-4[0-9A-Fa-f]{3}-[89ABab][0-9A-Fa-f]{3}-[0-9A-Fa-f]{12}

UUID identifying the ACH or CC payment profile.

credit

boolean

required

Payment direction: true for credit, false for debit. The payment method and destination must support the selected direction.

recurring_type

string

enum

required

Schedule cadence. x_day_of_month requires x_day_of_month; every_x_days requires every_x_days.

Allowed:

first_bill_date

date

required

First recurring-payment date in YYYY-MM-DD format; creation requires a date later than today.

first_bill_amount

double

required

≤ 99999999.99

Initial recurring-payment amount in decimal currency units.

x_day_of_month

integer | null

≥ 1

Positive day-of-month setting. Required when recurring_type is x_day_of_month.

every_x_days

integer | null

≥ 1

Positive interval in days. Required when recurring_type is every_x_days.

recur_amount

double

required

≤ 99999999.99

Amount of recurring payments after the first payment, in decimal currency units.

recur_frequency

integer

≥ 1

Configured number of recurring occurrences; a positive integer when supplied.

start_this_month

boolean

required

Whether the recurring calculation should consider the current month; the first bill date must still be in the future.

reference_id

string

required

length between 1 and 50

\S

Partner-assigned reference used for reconciliation and supported reference lookups. Resource creation can enforce uniqueness within its scope.

reference_id_2

string | null

Optional second partner-assigned reference.

team_member_id

string | null

Optional partner team-member reference.

customer_ip

string | null

Originating customer IP address, when supplied by the integration.

bypass_webhook

boolean | null

When true, suppress the webhook associated with this operation where supported. This does not change the payment processing outcome.

terminal_token

[0-9A-Fa-f]{8}-[0-9A-Fa-f]{4}-4[0-9A-Fa-f]{3}-[89ABab][0-9A-Fa-f]{3}-[0-9A-Fa-f]{12}

UUID of the accessible CC processing terminal. Schedules use this instead of org_bank_account_token.

Stringified UUIDv4.
See RFC 4112

source

string | null

Origin recorded for the resource, using the documented API/Portal/mobile source vocabulary.

Responses

default

Other infrastructure or forwarded downstream response. HTTP status and body must be preserved; do not assume every error has a Payology R-code. No fixed payload is guaranteed.

201Recurring created.

400Invalid fields, selector, or business rule. Consult the individual example code.

401Authentication failed. Some services also use 401 for organization access denial. Gateway bodies can differ.

403Permission or organization access denied; the gateway can reject the request before it reaches the service.

404Requested resource or lookup reference was not found.

413Possible gateway request size rejection. Service-specific limits and response templates require environment verification.

429Gateway throttling or quota. Exact quota, retry headers and deployed body were not verified. This is a platform possibility, not an observed Payology response.

500Unhandled service failure. Gateway configuration/authorizer failures can also return 500.

504Gateway integration timeout or failure. The service may still have committed a create request. This is a platform possibility, not an observed Payology response.