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.
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
}'
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.
x-api-key: your_merchant_api_key
vault-api-key: your_vault_api_key
Merchant API Key (x-api-key): Dashboard → Settings → API Keys.Vault API Key (vault-api-key): Provided when you signed up with Ozura. Contact support if you need it reissued.
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 |
|---|
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"
}
$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 |
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 |
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.