> ## 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.

# Transactions

> The OzuraPay OzuraPay API is a unified payment integration layer that allows merchants to process card transactions through a single API interface.

## 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

<api-endpoint method="POST" path="/cardSale" />

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.

<Info>
  **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.
</Info>

#### 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

```bash theme={null}
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

<api-endpoint method="GET" path="/transQuery" />

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"`.                                                              |

<Note>
  `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.
</Note>

<Warning>
  You must provide either `transactionId` or both `dateFrom` and `dateTo`.
</Warning>

#### Example Requests

<CodeGroup>
  ```bash Query by Transaction ID theme={null}
  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"
  ```

  ```bash Query by Date Range theme={null}
  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"
  ```
</CodeGroup>

#### Response

```json theme={null}
{
  "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

<api-endpoint method="POST" path="/cardRefund" />

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

<Info>
  **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.
</Info>

#### 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

<CodeGroup>
  ```bash Full Refund theme={null}
  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"
    }'
  ```

  ```bash Partial Refund theme={null}
  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"
    }'
  ```
</CodeGroup>

#### Response

```json theme={null}
{
  "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"
}
```