> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ozura.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Create a Recurring Plan
> Set up an automated billing plan that charges a customer's card on a recurring schedule
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:
```bash theme={null}
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](#transactionchannel) code | `"ecommerce"` |
| `transactionInitiationType` | string | Whether the charge is merchant-initiated or customer-initiated — see [TransactionInitiationType](#transactioninitiationtype) | `"cit"` |
| `interval` | string | How often to charge — see [RecurringInterval](#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](/guides/vault/overview) 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](#initial-pricing-config) | `"9.99"` |
| `initialAmount` | string | — | Override amount for the first N cycles — see [Initial Pricing Config](#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.
```json theme={null}
{
"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`.
```json theme={null}
{
"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
```json theme={null}
{
"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](/guides/payments/payapi/recurring/manage-plans) to learn how to pause, cancel, or update a plan.