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"`).
`billingZipcode`	string	Yes	Billing postal/ZIP code.
`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.).

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