Transactions

Endpoints Overview

Endpoint	Method	Description
`/cardSale`	`POST`	Process a card payment transaction using tokenized card data. Supports automatic processor cascading or explicit processor targeting.
`/transQuery`	`GET`	Retrieve transaction records by transaction ID or date range, with support for filtering, pagination, and sorting.
`/cardRefund`	`POST`	Issue a full or partial refund against a previously successful transaction.

Base URLs

Environment	URL
Production	`https://payapi.v2.ozurapay.com`

Authentication

All transaction endpoints require API key authentication via request headers.

Header	Description	Required For
`x-api-key`	Your OzuraPay API key	All transaction endpoints
`Vault-API-key`	Your OzuraPay Vault key for tokenized card data	`/cardSale`

Rate Limits

Rate limits are applied per merchant per endpoint.

Endpoint	Limit
`/cardSale`	100 requests / minute
`/transQuery`	200 requests / minute
`/cardRefund`	20 requests / minute

Endpoints

Process a Card Sale

Processes a card payment transaction for a merchant. Card data is passed via secure Ozura tokenization — you must provide an ozuraVaultToken and ozuraCvcSession rather than raw card details.

Processor Cascading: The processor field is optional. If omitted, OzuraPay will automatically select a processor based on the merchant’s active integrations. To target a specific processor, pass one of the supported values explicitly.

Authentication

Header	Required
`x-api-key`	Yes
`Vault-API-key`	Yes

Request Body

Field	Type	Required	Description
`merchantId`	string	Yes	Your OzuraPay merchant ID (max 30 characters).
`amount`	string	Yes	Transaction amount as a decimal string (e.g. `"1.01"`).
`currency`	string	Yes	ISO 4217 currency code (e.g. `"USD"`).
`ozuraVaultToken`	string	Yes	Tokenized card number obtained from the OzuraPay Vault.
`ozuraCvcSession`	string	Yes	CVC session ID obtained from the OzuraPay Vault.
`merchantReference`	string	No	Your own reference ID for this transaction (max 50 characters). Stored with the transaction, mirrored back in the response, and filterable on `/transQuery`.
`billingFirstName`	string	Yes	Cardholder’s first name.
`billingLastName`	string	Yes	Cardholder’s last name.
`billingEmail`	string	Yes	Cardholder’s email address.
`billingPhone`	string	Yes	Cardholder’s phone number (e.g. `"+1234567890"`).
`billingAddress1`	string	Yes	Billing street address.
`billingCity`	string	Yes	Billing city.
`billingState`	string	Yes	Billing state/province code (e.g. `"FL"`). Required (non-empty) in the US and Canada; elsewhere it may be `""`.
`billingZipcode`	string	Yes	Billing postal/ZIP code. Required (non-empty) in the US and Canada; elsewhere it may be `""` for countries without postal codes.
`billingCountry`	string	Yes	ISO 3166-1 alpha-2 country code (e.g. `"US"`).
`clientIpAddress`	string	Yes	End customer’s IP address.
`salesTaxExempt`	boolean	Yes	Whether the transaction is exempt from sales tax.
`processor`	string	No	Target processor (e.g. `"nuvei"`, `"elavon"`, `"worldpay"`). If omitted, processor cascading is used.
`surchargePercent`	string	No	Surcharge percentage as a decimal string.
`tipAmount`	string	No	Tip amount as a decimal string.
`billingAddress2`	string	No	Additional address line (apartment, suite, etc.).

Sales tax. When salesTaxExempt is false, tax is calculated from the billing address and added to amount: US sales tax, and VAT, GST or sales tax in the other covered countries. For any other billing country no tax is added. Billing addresses in Mexico, China, Paraguay and Costa Rica are refused for now (Sales tax calculation failed, naming the country), and nothing is charged.billingState and billingZipcode must always be sent. Outside the US and Canada they may be empty ("") when the address has no region or postal code.

Example Request

curl -X POST https://payapi.v2.ozurapay.com/api/v1/cardSale \
  -H "Content-Type: application/json" \
  -H "x-api-key: your_pay_api_key" \
  -H "Vault-API-key: your_vault_api_key" \
  -d '{
    "merchantId": "ozu_7bjg497249681346",
    "amount": "1.01",
    "currency": "USD",
    "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
  }'

Query Transactions

Retrieves transaction records for a merchant. You can query by a specific transaction ID or by a date range.

Authentication

Header	Required
`x-api-key`	Yes

Query Parameters

Parameter	Type	Required	Description
`merchantId`	string	Yes	Your OzuraPay merchant ID (max 30 characters).
`transactionId`	string	Conditional	A specific transaction ID to look up. Required if `dateFrom`/`dateTo` are not provided.
`dateFrom`	string	Conditional	Start of date range. Format: `YYYY-MM-DD HH:MM:SS`. Required with `dateTo` if no `transactionId`.
`dateTo`	string	Conditional	End of date range. Format: `YYYY-MM-DD HH:MM:SS`. Required with `dateFrom` if no `transactionId`.
`transactionType`	string	No	Filter by transaction type.
`transactionInitiationType`	string	No	Filter by initiation type (`cit`, `mit`, `ucof`, `refund`).
`transactionChannel`	string	No	Filter by payment channel (`cardPresent`, `ecommerce`, `moto`, `recurring`).
`recurringPlanId`	string	No	Filter by the recurring plan the transaction belongs to.
`recurringAttemptId`	string	No	Filter by a specific recurring charge attempt.
`recurringCycleNumber`	number	No	Filter by billing cycle number within a recurring plan.
`recurringAttemptNumber`	number	No	Filter by attempt number within a billing cycle.
`merchantReference`	string	No	Filter by the `merchantReference` passed at sale time (max 50 characters).
`merchantRecurringReference`	string	No	Filter by the recurring plan reference attached to the transaction (max 50 characters).
`merchantPayLinkReference`	string	No	Filter by the payment link reference attached to the transaction (max 50 characters).
`paymentLinkId`	string	No	Filter by the Ozura payment link ID the transaction was created through (max 50 characters).
`page`	string	No	Page number for pagination.
`limit`	string	No	Number of results per page.
`fields`	string	No	Comma-separated list of fields to include in the response.
`sortBy`	string	No	Field name to sort results by.
`sortOrder`	string	No	Sort direction: `"asc"` or `"desc"`.

merchantReference, merchantRecurringReference, merchantPayLinkReference, and paymentLinkId are only present on a transaction if they were provided when it was created. Transactions without them omit the fields entirely.

You must provide either transactionId or both dateFrom and dateTo.

Example Requests

curl -X GET "https://payapi.v2.ozurapay.com/api/v1/transQuery?merchantId=ozu_7bjg497249681346&transactionId=txn_abc123" \
  -H "x-api-key: your_pay_api_key"

curl -X GET "https://payapi.v2.ozurapay.com/api/v1/transQuery?merchantId=ozu_7bjg497249681346&dateFrom=2025-01-01%2000:00:00&dateTo=2025-01-31%2023:59:59&page=1&limit=50&sortBy=createdAt&sortOrder=desc" \
  -H "x-api-key: your_pay_api_key"

Response

{
  "success": true,
  "data": [
    /* one or more transaction objects */
  ],
  "pagination": {
    "currentPage": 1,
    "totalPages": 3,
    "totalCount": 127,
    "limit": 50,
    "hasNextPage": true,
    "hasPrevPage": false,
    "nextPage": 2,
    "prevPage": null
  }
}

Process a Card Refund

Processes a full or partial refund against a previously successful transaction.

Partial vs. Full Refunds: The amount field is optional. If omitted, the full remaining refundable amount (currentAmount) of the original transaction will be refunded. To issue a partial refund, specify the desired refund amount as a decimal string.

Authentication

Header	Required
`x-api-key`	Yes

Request Body

Field	Type	Required	Description
`transactionId`	string	Yes	The ID of the original transaction to refund.
`merchantId`	string	Yes	Your OzuraPay merchant ID.
`amount`	string	No	Refund amount as a decimal string. If omitted, the full remaining amount is refunded.

Example Requests

curl -X POST https://payapi.v2.ozurapay.com/api/v1/cardRefund \
  -H "Content-Type: application/json" \
  -H "x-api-key: your_pay_api_key" \
  -d '{
    "transactionId": "txn_abc123",
    "merchantId": "ozu_7bjg497249681346"
  }'

curl -X POST https://payapi.v2.ozurapay.com/api/v1/cardRefund \
  -H "Content-Type: application/json" \
  -H "x-api-key: your_pay_api_key" \
  -d '{
    "transactionId": "txn_abc123",
    "merchantId": "ozu_7bjg497249681346",
    "amount": "5.00"
  }'

Response

{
  "success": true,
  "data": {
    "transactionId": "260602000019C4E1B",
    "amount": "5.00",
    "currency": "USD",
    "billingFirstName": "Jane",
    "billingLastName": "Doe",
    "billingEmail": "jane.doe@example.com",
    "billingPhone": "+15551234567",
    "billingAddress1": "123 Main St",
    "billingAddress2": "Apt 4B",
    "billingCity": "Miami",
    "billingState": "FL",
    "billingZipcode": "33101",
    "billingCountry": "US",
    "isCreditCard": true,
    "cardLastFour": "4242",
    "cardExpMonth": "03",
    "cardExpYear": "30",
    "cardBrand": "VISA",
    "cardBin": "424242",
    "clientIpAddress": "203.0.113.42",
    "transDate": "2026-06-02T12:00:00.000Z"
  },
  "message": "Card refund successfully processed"
}

Getting Started

Vault

Payments

Transactions

Endpoints Overview

Base URLs

Authentication

Rate Limits

Endpoints

Process a Card Sale

Authentication

Request Body

Example Request

Query Transactions

Authentication

Query Parameters

Example Requests

Response

Process a Card Refund

Authentication

Request Body

Example Requests

Response

​Endpoints Overview

​Base URLs

​Authentication

​Rate Limits

​Endpoints

​Process a Card Sale

​Authentication

​Request Body

​Example Request

​Query Transactions

​Authentication

​Query Parameters

​Example Requests

​Response

​Process a Card Refund

​Authentication

​Request Body

​Example Requests

​Response

Endpoints Overview

Base URLs

Authentication

Rate Limits

Endpoints

Process a Card Sale

Authentication

Request Body

Example Request

Query Transactions

Authentication

Query Parameters

Example Requests

Response

Process a Card Refund

Authentication

Request Body

Example Requests

Response