Create a Recurring Plan

A recurring plan tells OzuraPay to charge a customer’s card automatically at a fixed interval — weekly, monthly, yearly, or any cadence you choose. Create the plan once; OzuraPay handles every charge after that.

Quick Start

Create a monthly plan and start billing immediately:

curl -X POST https://payapi.v2.ozurapay.com/api/v1/recurring/plans \
  -H "x-api-key: your_merchant_api_key" \
  -H "vault-api-key: your_vault_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "merchantId": "ozu_7bjg497249681346",
    "planName": "Monthly Pro Subscription",
    "amount": "29.99",
    "currency": "USD",
    "interval": "monthly",
    "ozuraVaultToken": "your_card_token",
    "ozuraCvcSession": "your_cvc_session",
    "billingFirstName": "Jane",
    "billingLastName": "Doe",
    "billingEmail": "jane.doe@example.com",
    "billingPhone": "+1234567890",
    "billingAddress1": "123 Main St",
    "billingCity": "Miami",
    "billingState": "FL",
    "billingZipcode": "33101",
    "billingCountry": "US",
    "clientIpAddress": "203.0.113.42",
    "salesTaxExempt": false
  }'

A successful response returns a planId. Save it — you’ll need it to pause, cancel, or query the plan later.

The Basics

What	Value
Method	`POST`
URL	`https://payapi.v2.ozurapay.com/api/v1/recurring/plans`
Content-Type	`application/json`
Called From	Your server (never from browser JavaScript)

Never call this from the browser. Your API keys must stay on the server. Use a backend (Node.js, Python, PHP, etc.) to create plans and store the returned planId in your own database.

Required Headers

Every request needs both headers:

x-api-key: your_merchant_api_key
vault-api-key: your_vault_api_key

Merchant API Key (x-api-key): Developers → API Keys.Vault API Key (vault-api-key): Developers → Vault Key.

Required Fields

Your request body must include all of the following:

Field	Type	Description	Example
`merchantId`	string	Your OzuraPay merchant ID	`"ozu_7bjg497249681346"`
`planName`	string	A label for this plan (shown in your dashboard)	`"Monthly Pro Subscription"`
`amount`	string	The amount charged each billing cycle as a decimal string	`"29.99"`
`currency`	string	ISO 4217 currency code	`"USD"`
`transactionChannel`	string	Payment channel — see TransactionChannel code	`"ecommerce"`
`transactionInitiationType`	string	Whether the charge is merchant-initiated or customer-initiated — see TransactionInitiationType	`"cit"`
`interval`	string	How often to charge — see RecurringInterval	`"monthly"`
`ozuraVaultToken`	string	Tokenized card number from the Ozura Vault	`"tok_xxxxxxxxxxxx"`
`ozuraCvcSession`	string	CVC session ID from the Ozura Vault	`"cvc_xxxxxxxxxxxx"`
`billingFirstName`	string	Cardholder’s first name	`"Jane"`
`billingLastName`	string	Cardholder’s last name	`"Doe"`
`billingEmail`	string	Cardholder’s email address	`"jane.doe@example.com"`
`billingPhone`	string	Cardholder’s phone number	`"+1234567890"`
`billingAddress1`	string	Billing street address	`"123 Main St"`
`billingCity`	string	Billing city	`"Miami"`
`billingState`	string	State or province code	`"FL"`
`billingZipcode`	string	Postal or ZIP code	`"33101"`
`billingCountry`	string	ISO 3166-1 alpha-2 country code	`"US"`
`clientIpAddress`	string	End customer’s IP address	`"203.0.113.42"`
`salesTaxExempt`	boolean	Whether the transaction is exempt from sales tax	`false`

Where do I get ozuraVaultToken and ozuraCvcSession? These come from the Ozura Vault after your customer enters their card details. See the Vault documentation to learn how to tokenize a card before creating a plan.

Optional Fields

Field	Type	Default	Description	Example
`merchantRecurringReference`	string	—	Your own reference ID for this plan (max 50 characters). Mirrored back in plan responses and filterable on the query endpoint.	`"sub_customer_123"`
`surchargePercent`	string	`"0.00"`	Surcharge percentage to apply to each charge. `"3.00"` = 3%. Cannot exceed `"3.00"`.	`"1.50"`
`planDescription`	string	-	Internal note or plan description	`"Pro tier, billed monthly"`
`intervalCount`	number	1	How many intervals between charges. `2` + `"monthly"` = every 2 months	`2`
`endDate`	string	-	ISO 8601 date after which the plan stops billing. null = indefinite	`2027-01-07T00:00:00.000Z`
`maxCycles`	number	-	Maximum number of billing cycles before the plan automatically completes. null = indefinite	`12`
`maxAttempts`	number	3	How many times to charge in case of failed processing.	`2`
`retryIntervalHours`	number	24	Hours between retry attempts after a failed charge	`12`
`processor`	string		Specify a processor (elavon, nuvei, worldpay). If omitted, processor cascading is used	`"elavon"`
`setupFee`	string	—	One-time fee charged on the first billing cycle — see Initial Pricing Config	`"9.99"`
`initialAmount`	string	—	Override amount for the first N cycles — see Initial Pricing Config	`"19.99"`
`initialCycles`	number	—	Number of cycles to use `initialAmount` before switching to the standard `amount`	`3`
`billingAddress2`	string	—	Additional address line (apartment, suite, etc.)	`"Apt 4B"`

Initial Pricing Config

Three optional fields let you offer introductory pricing before the standard rate kicks in.

`setupFee`

A one-time fee charged alongside the first billing cycle payment. It does not repeat.

{
  "amount": "29.99",
  "setupFee": "9.99"
}

On the first cycle the customer is charged $9.99 + $29.99 = $39.98. Every cycle after that is just $29.99.

`initialAmount` + `initialCycles`

Override the charge amount for the first N cycles. After initialCycles is exhausted, billing automatically switches to the standard amount.

{
  "amount": "29.99",
  "initialAmount": "9.99",
  "initialCycles": 3
}

Cycle	Charged
Cycle 1	`$9.99`
Cycle 2	`$9.99`
Cycle 3	`$9.99`
Cycle 4+	`$29.99`

You can combine all three. For example, a setupFee of "4.99", an initialAmount of "9.99" for 2 cycles, and a standard amount of "29.99" would charge $14.98 on the first cycle, $9.99 on the second, and $29.99 every cycle after that.

initialCycles has no effect if initialAmount is not set.

Enums

RecurringInterval

Controls how frequently the plan bills.

Value	Description
`daily`	Charge every day
`weekly`	Charge every week
`monthly`	Charge every month
`yearly`	Charge every year

Use intervalCount together with interval to express non-standard cadences — for example, interval: "weekly" + intervalCount: 2 means every two weeks.

RecurringPlanStatus

The lifecycle state of a plan, returned in all plan responses.

Value	Meaning
`active`	Plan is running and will bill on schedule
`paused`	Billing is temporarily halted; can be resumed
`cancelled`	Plan has been permanently stopped
`completed`	All scheduled cycles have been charged, or maxCycles was reached
`failed`	Exhausted all retries on a cycle. Needs merchant attention

TransactionChannel

Value	Description
`cardPresent`	POS / in-person
`ecommerce`	Online, customer self-serve
`moto`	Mail order / telephone order
`recurring`	Scheduled MIT charge, never the initial CIT

TransactionInitiationType

Value	Description
`cit`	Customer Initiated Transaction — customer was present and authorized the charge
`mit`	Merchant Initiated Transaction — merchant charges the stored card without the customer present (standard for recurring billing)
`ucof`	Unscheduled Credential-on-File — merchant-initiated but not on a fixed schedule (ex: account updater charges, threshold billing, balance top-ups)
`refund`	Not a stored credential use — voids, returns, reversals

All plans must use "cit"

Response

{
  "success": true,
  "data": {
    "ozuraMerchantId": "ozu_7bjg497249681346",
    "planId": "RP250107000014F3B2A",
    "planName": "Monthly Pro Subscription",
    "planDescription": "Access to all Pro features",
    "merchantRecurringReference": "sub_customer_123",
    "amount": "29.99",
    "currency": "USD",
    "surchargeAmount": "0.00",
    "citTransactionId": "250107000019C4E1B",
    "citTransactionAmount": "39.98",
    "citTransactionSalesTaxAmount": "0.00",
    "citTransactionSurchargeAmount": "0.00",
    "nextCycleAt": "2025-02-07T00:00:00.000Z",
    "endDate": null,
    "billingFirstName": "Joe",
    "billingLastName": "Doe",
    "billingEmail": "jdoe@example.com",
    "billingPhone": "+15551234567",
    "billingAddress1": "123 Main St",
    "billingAddress2": "",
    "billingCity": "Boston",
    "billingState": "MA",
    "billingZipcode": "02108",
    "billingCountry": "US",
    "isCreditCard": true,
    "cardLastFour": "4242",
    "cardExpMonth": "03",
    "cardExpYear": "30",
    "cardBrand": "VISA",
    "cardBin": "424242",
    "clientIpAddress": "203.0.113.1",
    "transDate": "2025-01-07T12:00:00.000Z"
  }
}

Field	What It Is
`planId`	Save this. Use it to pause, cancel, or query the plan later.
`citTransactionId`	The transaction ID of the initial charge — save for your records
`citTransactionAmount`	What was actually charged on signup (includes setup fee if applicable)
`nextCycleAt`	When the next automatic charge will run
`transDate`	ISO 8601 timestamp of the initial charge

What’s Next?

You have a live planId. Head to Manage Recurring Plans to learn how to pause, cancel, or update a plan.

Getting Started

Vault

Payments

Create a Recurring Plan

Quick Start

The Basics

Required Headers

Required Fields

Optional Fields

Initial Pricing Config

`setupFee`

`initialAmount` + `initialCycles`

Enums

RecurringInterval

RecurringPlanStatus

TransactionChannel

TransactionInitiationType

Response

What’s Next?

​Quick Start

​The Basics

​Required Headers

​Required Fields

​Optional Fields

​Initial Pricing Config

​setupFee

​initialAmount + initialCycles

​Enums

​RecurringInterval

​RecurringPlanStatus

​TransactionChannel

​TransactionInitiationType

​Response

​What’s Next?

Quick Start

The Basics

Required Headers

Required Fields

Optional Fields

Initial Pricing Config

`setupFee`

`initialAmount` + `initialCycles`

Enums

RecurringInterval

RecurringPlanStatus

TransactionChannel

TransactionInitiationType

Response

What’s Next?