### Get Started with Unlimit API

Source: https://integration.unlimit.com/api-reference/index

Information on Unlimit API environments and basic usage.

```APIDOC
## Introduction to Unlimit API

Welcome to the **Unlimit REST API**. The Unlimit API uses **HTTP** verbs and a **REST** resources endpoint structure. Request and response payloads are formatted as JSON. Merchants can use the API to create payments, refunds, payouts, recurring payments, check or update transaction status, and get information about created transactions. The API's authentication process is based on OAuth 2.0 standard.

### Environments

Unlimit provides the following environments for testing and production purposes:

*   **Sandbox:** `https://sandbox.cardpay.com/api`
*   **Production:** `https://cardpay.com/api`
*   **Sandbox India:** `https://sandbox.in.unlimit.com/api`
*   **Production India:** `https://psp.in.unlimit.com/api`

### API Entry Points

The **REST API** is the Payment API which provides complete server-to-server operations. It is used for sending new transactions to the system. It provides a Payment Page Mode when a customer enters payment details in a form located on the Unlimit payment page, or a customer enters payment details on the Merchant's site (Gateway Mode). It also has additional methods to provide information about payments and to change payment status.

The API is available via HTTP protocol using HTTP `POST`, `GET`, `PATCH` or `DELETE` methods.

> According to HTTP standards, all parameter values for `GET` requests must be URL encoded before sending and URL decoded after receiving to escape special characters like `+`, `/`, `&`, `=` used in URLs to separate words, folders and parameters.

### Fields Format

Field and structure names are case-sensitive. The following data types are used:

Data type| Description
---|---
**String**| Any Unicode characters, some validation may be applied though
**Integer**| Only decimal digits
**Decimal**| Decimal digits with dot as a decimal separator
**Boolean**| Boolean flag: `true` / `false`
**Date**| Date type in ISO 8601 format up to seconds (milliseconds are optional and allowable only for requests), example: `2018-10-28T09:10:49Z` (example allowable only for requests: `2018-10-28T09:10:49.324Z`). Must be in UTC time only
**<...> array**| An array of data
```

--------------------------------

### Subscription Updated Response Example

Source: https://integration.unlimit.com/api-reference/023c53937e2a7-update-subscription

Example JSON response received after a successful subscription update operation. It details the status and other relevant information about the subscription.

```json
{
  "subscription_data": {
    "id": "2332332",
    "status_to": "ACTIVE",
    "remaining_amount": 0,
    "is_executed": false,
    "change_status_claim_id": "238332823",
    "updated": "2018-10-28T09:09:53Z",
    "status": "ACTIVE",
    "details": "Operation details",
    "filing": {
      "id": "4373822939"
    },
    "plan": {
      "change_date": "string",
      "id": "gA4091iC"
    },
    "next_payment_date": "2019-08-24",
    "units": 0
  }
}
```

--------------------------------

### Unlimit API cURL Request Example

Source: https://integration.unlimit.com/api-reference/2958e6cd74e5f-create-recurring

This example demonstrates how to send a payment request to the Unlimit API using cURL. It shows how to include the JSON payload in the request body and set the appropriate content type. This is useful for testing API integrations directly from the command line.

```bash
curl -X POST <API_ENDPOINT> \
-H "Content-Type: application/json" \
-d '{
  "request": {
    "id": "1",
    "time": "2022-03-20T09:09:49Z"
  },
  "card_account": {
    "billing_address": {
      "addr_line_1": "450 W.",
      "addr_line_2": "33 Street",
      "city": "New York",
      "country": "USA",
      "state": "NY",
      "zip": "02108"
    },
    "card": {
      "acct_type": "03",
      "expiration": "11/2022",
      "holder": "John Smith",
      "network_token": true,
      "pan": "4000000000000002",
      "pin_code": "1234",
      "security_code": "555",
      "token_cryptogram\t": "string"
    },
    "encrypted_card_data": "U29tZSB0ZXN0IHZhbHV……lIHNvbWUgdGVzdCB2YWx1ZSA=",
    "token": "C526Hg8h0e5BBeD42g7CFhf2"
  },
  "customer": {
    "device": {
      "fingerprint": "Ink1577CAFmczjL1Is4A02"
    },
    "email": "customer@example.com",
    "home_phone": "+1 111111111",
    "id": "44737",
    "identity": "string",
    "ip": "1.1.1.1",
    "locale": "en",
    "phone": "+1 111111111",
    "user_agent": "Mozilla/5.0 (iPhone; CPU iPhone OS 17_1_2 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/17.1.2 Mobile/15E148 Safari/604",
    "work_phone": "+1 111111111"
  },
  "merchant_order": {
    "description": "Example order",
    "id": "order00017",
    "items": [
      {
        "count": 4,
        "description": "Premium Cotton T-Shirt",
        "name": "T-Shirt",
        "price": 60
      }
    ],
    "shipping_address": {
      "addr_line_1": "450 W.",
      "addr_line_2": "33 Street",
      "city": "New York",
      "country": "USA",
      "phone": "+1 111111111",
      "state": "NY",
      "zip": "02108"
    }
  },
  "payment_method": "BANKCARD",
  "recurring_data": {
    "contract_number": "7481592630ARDS",
    "dynamic_descriptor": "DF335TG12GJ",
    "encrypted_data": "string",
    "generate_token": false,
    "initial_amount": 100,
    "initiator": "cit",
    "note": "Recurring payment",
    "plan": {
      "id": "gA4091iC"
    },
    "scheduled_type": "SA",
    "subscription_start": "2019-04-22",
    "three_ds_challenge_indicator": "01",
    "trans_type": "01",
    "units": 1
  },
  "return_urls": {
    "cancel_url": "http://www.example.com/cancel-url",
    "decline_url": "http://www.example.com/decline-url",
    "inprocess_url": "http://www.example.com/in-process-url",
    "return_url": "http://www.example.com/return-url",
    "success_url": "http://www.example.com/success-url"
  }
}'
```

--------------------------------

### Get Subscription Information - Cardpay API

Source: https://context7.com/context7/integration_unlimit_api-reference/llms.txt

GET endpoint for retrieving detailed subscription information. Returns data such as amount due, payment schedule, customer details, and subscription status. Requires the subscription ID.

```bash
curl --request GET \
  --url https://sandbox.cardpay.com/api/recurring_subscriptions/32323223 \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer aGVhZGVyLmFjY2Vzc190b2tlbl9ib2R5LnNpZ25hdHVyZQ=='
```

--------------------------------

### Get Filing Order Information API

Source: https://integration.unlimit.com/api-reference/2fc1c3c68162a-create-filing

This endpoint retrieves information about a specific filing order.

```APIDOC
## GET /api/recurring_filings/{order_id}

### Description
Retrieves information for a specific filing order.

### Method
GET

### Endpoint
https://sandbox.cardpay.com/api/recurring_filings/{order_id}

### Parameters
#### Path Parameters
- **order_id** (string) - Required - The ID of the filing order to retrieve.

### Request Example
```json
{
  "example": "request body"
}
```

### Response
#### Success Response (200)
- **body** (object) - Description of the success response.

#### Response Example
```json
{
  "example": "response body"
}
```
```

--------------------------------

### Recurring Subscriptions Response Example (JSON)

Source: https://integration.unlimit.com/api-reference/721c84709a57e-get-subscriptions-information

This JSON object represents a successful response from the Unlimit API's recurring subscriptions endpoint. It includes a list of subscription objects, each with detailed information about the subscription.

```json
{
  "data": [
    {
      "amount_due": 100,
      "amount_total": 100,
      "created": "2018-10-28T09:09:53Z",
      "currency": "USD",
      "customer": {
        "email": "customer@example.com",
        "id": "ABCXYZ1234567890"
      },
      "description": "Service subscription",
      "id": "32323223",
      "interval": 1,
      "is_payment_date_shifted": true,
      "next_payment": {
        "date": "2019-04-22"
      },
      "payments_due": 10,
      "pending_plan_update": {
        "date": "2023-04-22",
        "id": "pX1527CS"
      },
      "period": "month",
      "plan": {
        "id": "lj1169BJ"
      },
      "retries": 3,
      "status": "INACTIVE",
      "status_reason": "Common decline",
      "subscription_start": "2019-04-22",
      "type": "ONECLICK",
      "units": 0
    }
  ],
  "has_more": true
}
```

--------------------------------

### Getting Payment Details (Signature Authentication)

Source: https://context7.com/context7/integration_unlimit_api-reference/llms.txt

Retrieves details for a specific payment using signature-based authentication.

```APIDOC
## GET /api/payments/{payment_id} (Signature Auth)

### Description
Retrieves details for a specific payment using signature-based authentication.

### Method
GET

### Endpoint
https://sandbox.cardpay.com/api/payments/{payment_id}?queryString

### Parameters
#### Path Parameters
- **payment_id** (string) - Required - The unique identifier of the payment.

#### Query Parameters
- **queryString** (string) - Optional - Any query parameters for the request.

#### Headers
- **Authorization** (string) - Required - Signature in the format `Signature 13123,c8033ff0-7ea4-4cad-90e6-17c69b67a851,f23bf4b2-4887-4160-95b6-a4024761683c,d028c0b0c54b28af4e4fa6f65ce03a28621da70d5ece99f8832d6953f9f0af78`.
- **Accept** (string) - Optional - `application/json`.

### Request Example
```bash
# X-Sign = sha256('API-client-Id' + 'url' + 'body' + 'queryString' + 'API key')
# Example: X-Sign = sha256('f23bf4b2-4887-4160-95b6-a4024761683c' + '/api/payments/29574221' + '' + 'queryString' + '5d69de1e-f433-4561-a3e4-0b6bdbf51ca1')
# Result: d028c0b0c54b28af4e4fa6f65ce03a28621da70d5ece99f8832d6953f9f0af78

curl --request GET \
  --url https://sandbox.cardpay.com/api/payments/29574221?queryString \
  --header 'Authorization: Signature 13123,c8033ff0-7ea4-4cad-90e6-17c69b67a851,f23bf4b2-4887-4160-95b6-a4024761683c,d028c0b0c54b28af4e4fa6f65ce03a28621da70d5ece99f8832d6953f9f0af78' \
  --header 'Accept: application/json'
```
```

--------------------------------

### Get Recurring Subscriptions (cURL)

Source: https://integration.unlimit.com/api-reference/721c84709a57e-get-subscriptions-information

This snippet shows how to make a GET request to the Unlimit API to retrieve a list of recurring subscriptions. It includes the necessary URL and headers for the request.

```Shell
curl --request GET \
  --url https://sandbox.cardpay.com/api/recurring_subscriptions \
  --header 'Accept: application/json'
```

--------------------------------

### Return URLs Configuration

Source: https://integration.unlimit.com/api-reference/2fc1c3c68162a-create-filing

This section describes how to configure return URLs for redirecting users after a transaction.

```APIDOC
## Return URLs Configuration

### Description
This section describes how to configure return URLs for redirecting users after a transaction, allowing customization of where users are sent upon completion, cancellation, or decline.

### Parameters

#### Request Body Parameters

- **return_urls** (object) - Optional - Contains various URL configurations for post-transaction redirects.
  - **cancel_url** (string) - Optional - Overrides the default cancel URL. Maximum length: 512 characters.
  - **decline_url** (string) - Optional - Overrides the default decline URL. Maximum length: 512 characters.
  - **inprocess_url** (string) - Optional - Special URL for handling the 'In process' transaction status. Maximum length: 512 characters.
  - **return_url** (string) - Optional - Overrides default success, decline, cancel, and in-process URLs. Can be used alone or with other URL parameters. Maximum length: 512 characters.
  - **success_url** (string) - Optional - Overrides the default success URL. Maximum length: 512 characters.

### Request Body Example
```json
{
  "return_urls": {
    "success_url": "http://www.example.com/success-url",
    "cancel_url": "http://www.example.com/cancel-url",
    "decline_url": "http://www.example.com/decline-url"
  }
}
```

### Response

#### Success Response (200)

- **Fields**: Response fields depend on the specific API endpoint and transaction details.

#### Response Example
```json
{
  "status": "success",
  "message": "Return URLs updated successfully."
}
```
```

--------------------------------

### GET Recurring Payments API Request (cURL)

Source: https://integration.unlimit.com/api-reference/aa73c324e7ccd-get-recurring-list-information

This snippet demonstrates how to make a GET request to the Unlimit API to retrieve recurring payment information. It utilizes cURL for the request and specifies the necessary headers.

```shell
curl --request GET \
  --url https://sandbox.cardpay.com/api/recurrings \
  --header 'Accept: application/json'
```

--------------------------------

### Return URLs Configuration

Source: https://integration.unlimit.com/api-reference/trb25vpp9rxum-url-placeholders

Information regarding the different types of return URLs supported by the Unlimit API and how they function.

```APIDOC
## Return URLs

### Description
Return URLs are the destinations where a customer is redirected after interacting with the payment page. This includes actions like pressing a 'Back to the shop' or 'Cancel' button, or automatic redirection in Gateway mode.

There are four types of return URLs:
*   **Success URL**: Where the customer is redirected after a successful transaction.
*   **Decline URL**: Where the customer is redirected after a failed transaction.
*   **Cancel URL**: Where the customer is redirected when no transaction was made (only applicable in Payment Page mode).
*   **In Process URL**: Where the customer is redirected when the transaction status is 'in progress'.

By default, these URLs point to the shop's home page. Customization by a Unlimit manager is possible, but these URLs can also be provided on a per-request basis. See transaction element attributes for details.

### URL Placeholders
Return URLs can include placeholders that are dynamically replaced with actual values. These include:

*   `{id}`: Replaced with the Unlimit transaction ID (payment, refund, payout, recurring).
*   `{merchant_order_id}`: Replaced with the Shop's order ID.
*   `{status}`: Replaced with the transaction status. Possible values: `NEW`, `IN_PROGRESS`, `DECLINED`, `AUTHORIZED`, `COMPLETED`, `CANCELLED`, `REFUNDED`, `VOIDED`, `CHARGED_BACK`, `CHARGEBACK_RESOLVED`.
*   `{locale}`: Replaced with the locale received with the order, or the default locale if none is provided.
*   `{terminal_code}`: Replaced with the 'terminal_code' used for the API operation.
*   `{customer_id}`: Replaced with the 'customer_id' provided by the Merchant in the JSON request.
*   `{note}`: Replaced with the 'note' parameter provided by the Merchant in the JSON request.
*   `{transaction_type}`: Replaced with the type of transaction for which the callback will be sent (only applicable for Callback URLs). Possible values: `payment`, `refund`, `payout`, `recurring`.
```

--------------------------------

### Send GET API Request for Recurring ID

Source: https://integration.unlimit.com/api-reference/d32cfbbd90466-get-recurring-information

This snippet demonstrates how to send a GET request to retrieve recurring payment information using a specific recurring ID. It includes the necessary cURL command, endpoint URL, and headers.

```shell
curl --request GET \
  --url https://sandbox.cardpay.com/api/recurrings/recurring_id \
  --header 'Accept: application/json'
```

--------------------------------

### Make Authenticated Unlimit API Call

Source: https://context7.com/context7/integration_unlimit_api-reference/llms.txt

Demonstrates how to make an authenticated API call to retrieve payment details. It requires an 'Authorization' header with a Bearer token and an 'Accept' header for JSON response.

```bash
curl --request GET \
  --url https://sandbox.cardpay.com/api/payments/{payment_id} \
  --header 'Authorization: Bearer aGVhZGVyLmFjY2Vzc190b2tlbl9ib2R5LnNpZ25hdHVyZQ==' \
  --header 'Accept: application/json'
```

--------------------------------

### Environments

Source: https://integration.unlimit.com/api-reference/6nk7rnnwnafo0-environments

Unlimit provides different environments for testing and production, including specific endpoints for India.

```APIDOC
## Environments

Unlimit offers the following environments for API interactions:

### Sandbox
*   URL: `https://sandbox.cardpay.com/api`

### Production
*   URL: `https://cardpay.com/api`

### Sandbox India
*   URL: `https://sandbox.in.unlimit.com/api`

### Production India
*   URL: `https://psp.in.unlimit.com/api`
```

--------------------------------

### Send GET Request for Recurring Filings

Source: https://integration.unlimit.com/api-reference/3f5ea18d06692-get-filing-order-information

This snippet demonstrates how to send a GET request to the Unlimit API to retrieve recurring filings. It uses cURL and requires an authorization header. The response is a JSON object containing details about the recurring payment.

```shell
curl --request GET \
  --url https://sandbox.cardpay.com/api/recurring_filings/recurring_id \
  --header 'Accept: application/json'
```

--------------------------------

### API Authentication

Source: https://integration.unlimit.com/api-reference/6nk7rnnwnafo0-environments

Explains the OAuth2-based authentication process, including obtaining and refreshing access tokens.

```APIDOC
## Authentication

The Unlimit API utilizes the **OAuth2** authorization protocol.

### Access Token

Every API service call, for both sandbox and production environments, must include an **access token**. This token is obtained as a result of a successful authentication process.

### Token Lifetime and Refresh

Access tokens have a limited lifetime. To maintain API access, you should implement **access token refresh**. Merchants receive a **refresh token** alongside the access token, which has a longer validity period and can be used to obtain new access tokens.
```

--------------------------------

### Get Subscription Information using cURL

Source: https://integration.unlimit.com/api-reference/9249a3c5b53d8-get-subscription-information

This snippet demonstrates how to retrieve details of a specific recurring subscription using a GET request with cURL. It requires the subscription ID as a path parameter and expects a JSON response.

```shell
curl --request GET \
  --url https://sandbox.cardpay.com/api/recurring_subscriptions/subscription_id \
  --header 'Accept: application/json'
```

--------------------------------

### Create Recurring Filing - Cardpay API

Source: https://context7.com/context7/integration_unlimit_api-reference/llms.txt

POST endpoint for creating a card binding for future recurring transactions or subscription usage. Requires customer and card details, along with recurring and subscription data. Returns a redirect URL for further processing.

```bash
curl --request POST \
  --url https://sandbox.cardpay.com/api/recurring_filings \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer aGVhZGVyLmFjY2Vzc190b2tlbl9ib2R5LnNpZ25hdHVyZQ==' \
  --header 'Content-Type: application/json' \
  --data '{
  "request": {
    "id": "1",
    "time": "2022-03-20T09:09:49Z"
  },
  "card_account": {
    "card": {
      "expiration": "11/2022",
      "holder": "John Smith",
      "pan": "4000000000000002",
      "security_code": "555"
    }
  },
  "customer": {
    "email": "customer@example.com",
    "id": "44737",
    "ip": "1.1.1.1"
  },
  "merchant_order": {
    "description": "Example order",
    "id": "4437343"
  },
  "payment_method": "BANKCARD",
  "recurring_data": {
    "currency": "USD",
    "initiator": "cit",
    "three_ds_challenge_indicator": "01"
  },
  "subscription_data": {
    "id": "433823446"
  }
}'
```

--------------------------------

### Creating Recurring Payment

Source: https://context7.com/context7/integration_unlimit_api-reference/llms.txt

Creates a scheduled recurring payment with card tokenization and subscription management.

```APIDOC
## POST /api/recurrings

### Description
Endpoint for creating scheduled recurring payments with card tokenization and subscription management.

### Method
POST

### Endpoint
https://sandbox.cardpay.com/api/recurrings

### Parameters
#### Headers
- **Accept** (string) - Optional - `application/json`.
- **Authorization** (string) - Required - Bearer token in the format `Bearer <access_token>`.
- **Content-Type** (string) - Required - `application/json`.

#### Request Body
- **request** (object) - Required - General request parameters.
  - **id** (string) - Required - Unique identifier for the request.
  - **time** (string) - Required - Timestamp of the request in ISO 8601 format.
- **card_account** (object) - Required - Card account details.
  - **billing_address** (object) - Optional - Billing address information.
    - **addr_line_1** (string) - Required - Address line 1.
    - **addr_line_2** (string) - Optional - Address line 2.
    - **city** (string) - Required - City.
    - **country** (string) - Required - Country code (ISO 3166-1 alpha-2).
    - **state** (string) - Required - State or province.
    - **zip** (string) - Required - Postal code.
  - **card** (object) - Required - Card details.
    - **acct_type** (string) - Required - Account type (e.g., `03` for credit card).
    - **expiration** (string) - Required - Card expiration date (MM/YYYY).
    - **holder** (string) - Required - Cardholder name.
    - **pan** (string) - Required - Primary Account Number (PAN) of the card.
    - **security_code** (string) - Required - Security code (CVV/CVC).
- **customer** (object) - Required - Customer details.
  - **email** (string) - Required - Customer's email address.
  - **id** (string) - Required - Customer's unique identifier.
  - **ip** (string) - Required - Customer's IP address.
  - **phone** (string) - Optional - Customer's phone number.
- **merchant_order** (object) - Required - Merchant order details.
  - **description** (string) - Optional - Order description.
  - **id** (string) - Required - Merchant's order identifier.
  - **items** (array) - Optional - List of items in the order.
    - **count** (integer) - Required - Number of items.
    - **description** (string) - Optional - Item description.
    - **name** (string) - Required - Item name.
    - **price** (number) - Required - Price per item.
- **payment_method** (string) - Required - The payment method, e.g., `BANKCARD`.
- **recurring_data** (object) - Required - Recurring payment specific data.
  - **initiator** (string) - Required - Initiator of the recurring transaction (e.g., `cit` for Cardholder Initiated Transaction).
  - **note** (string) - Optional - A note for the recurring payment.
  - **plan** (object) - Required - Recurring plan details.
    - **id** (string) - Required - The identifier of the recurring plan.
  - **scheduled_type** (string) - Required - Type of scheduled payment (e.g., `SA` for Scheduled).
  - **subscription_start** (string) - Required - The start date of the subscription in YYYY-MM-DD format.
  - **initial_amount** (integer) - Optional - The amount for the initial payment.
- **return_urls** (object) - Optional - URLs for redirecting the customer after payment.
  - **success_url** (string) - Required - URL to redirect to on success.
  - **decline_url** (string) - Required - URL to redirect to on decline.

### Request Example
```bash
curl --request POST \
  --url https://sandbox.cardpay.com/api/recurrings \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer aGVhZGVyLmFjY2Vzc190b2tlbl9ib2R5LnNpZ25hdHVyZQ==' \
  --header 'Content-Type: application/json' \
  --data 
'{
  "request": {
    "id": "1",
    "time": "2022-03-20T09:09:49Z"
  },
  "card_account": {
    "billing_address": {
      "addr_line_1": "450 W.",
      "addr_line_2": "33 Street",
      "city": "New York",
      "country": "USA",
      "state": "NY",
      "zip": "02108"
    },
    "card": {
      "acct_type": "03",
      "expiration": "11/2022",
      "holder": "John Smith",
      "pan": "4000000000000002",
      "security_code": "555"
    }
  },
  "customer": {
    "email": "customer@example.com",
    "id": "44737",
    "ip": "1.1.1.1",
    "phone": "+1 111111111"
  },
  "merchant_order": {
    "description": "Example order",
    "id": "order00017",
    "items": [
      {
        "count": 4,
        "description": "Premium Cotton T-Shirt",
        "name": "T-Shirt",
        "price": 60
      }
    ]
  },
  "payment_method": "BANKCARD",
  "recurring_data": {
    "initiator": "cit",
    "note": "Recurring payment",
    "plan": {
      "id": "gA4091iC"
    },
    "scheduled_type": "SA",
    "subscription_start": "2019-04-22",
    "initial_amount": 100
  },
  "return_urls": {
    "success_url": "http://www.example.com/success-url",
    "decline_url": "http://www.example.com/decline-url"
  }
}'
```
```

--------------------------------

### Get Recurring List

Source: https://integration.unlimit.com/api-reference/2958e6cd74e5f-create-recurring

Retrieves a list of recurring payment information.

```APIDOC
## GET /api/recurrings

### Description
Get recurring list information.

### Method
GET

### Endpoint
https://sandbox.cardpay.com/api/recurrings

### Parameters
#### Path Parameters
None

#### Query Parameters
* **project_id** (string) - Required - The ID of the project.
* **limit** (integer) - Optional - The maximum number of items to return.
* **offset** (integer) - Optional - The number of items to skip.

### Request Example
(No request body for GET requests)

### Response
#### Success Response (200)
* **recurrings** (array) - An array of recurring payment objects.
  * **recurring_id** (string) - The unique identifier for the recurring payment.
  * **status** (string) - The status of the recurring payment.

#### Response Example
```json
{
  "recurrings": [
    {
      "recurring_id": "rec_abcdef123456",
      "status": "active"
    },
    {
      "recurring_id": "rec_ghijkl789012",
      "status": "inactive"
    }
  ]
}
```
```

--------------------------------

### Unlimit API Signature Authentication

Source: https://context7.com/context7/integration_unlimit_api-reference/llms.txt

Shows how to use signature-based authorization for Unlimit API calls, which involves generating a SHA256 hash of specific request components and including it in the Authorization header.

```bash
# X-Sign = sha256('API-client-Id' + 'url' + 'body' + 'queryString' + 'API key')
# Example: X-Sign = sha256('f23bf4b2-4887-4160-95b6-a4024761683c' + '/api/payments/29574221' + '' + 'queryString' + '5d69de1e-f433-4561-a3e4-0b6bdbf51ca1')
# Result: d028c0b0c54b28af4e4fa6f65ce03a28621da70d5ece99f8832d6953f9f0af78

curl --request GET \
  --url https://sandbox.cardpay.com/api/payments/29574221?queryString \
  --header 'Authorization: Signature 13123,c8033ff0-7ea4-4cad-90e6-17c69b67a851,f23bf4b2-4887-4160-95b6-a4024761683c,d028c0b0c54b28af4e4fa6f65ce03a28621da70d5ece99f8832d6953f9f0af78' \
  --header 'Accept: application/json'
```

--------------------------------

### Get Recurring Information

Source: https://integration.unlimit.com/api-reference/2958e6cd74e5f-create-recurring

Retrieves detailed information for a specific recurring payment.

```APIDOC
## GET /api/recurrings/{recurring_id}

### Description
Get recurring information.

### Method
GET

### Endpoint
https://sandbox.cardpay.com/api/recurrings/{recurring_id}

### Parameters
#### Path Parameters
* **recurring_id** (string) - Required - The unique identifier of the recurring payment.

#### Query Parameters
* **project_id** (string) - Required - The ID of the project.

### Request Example
(No request body for GET requests)

### Response
#### Success Response (200)
* **recurring_id** (string) - The unique identifier for the recurring payment.
* **status** (string) - The status of the recurring payment.
* **details** (object) - Additional details about the recurring payment.

#### Response Example
```json
{
  "recurring_id": "rec_abcdef123456",
  "status": "active",
  "details": {
    "amount": 1000,
    "currency": "USD",
    "interval": "monthly"
  }
}
```
```

--------------------------------

### Get Recurring Information

Source: https://integration.unlimit.com/api-reference/d32cfbbd90466-get-recurring-information

Retrieves detailed information about a specific recurring payment by its ID.

```APIDOC
## GET /api/recurrings/{recurring_id}

### Description
Retrieves detailed information about a specific recurring payment by its ID.

### Method
GET

### Endpoint
https://sandbox.cardpay.com/api/recurrings/{recurring_id}

### Parameters
#### Path Parameters
- **recurring_id** (string) - Required - Recurring ID

### Responses
#### Success Response (200)
OK

#### Error Responses
- **401** Unauthorized
- **403** Forbidden
- **404** Not Found
- **500** Internal Server Error
```

--------------------------------

### Obtaining API Access Tokens

Source: https://context7.com/context7/integration_unlimit_api-reference/llms.txt

Endpoint for obtaining OAuth 2.0 access and refresh tokens.

```APIDOC
## POST /api/auth/token

### Description
Endpoint for obtaining OAuth 2.0 access and refresh tokens required for all API operations.

### Method
POST

### Endpoint
https://sandbox.cardpay.com/api/auth/token

### Parameters
#### Query Parameters
- **grant_type** (string) - Required - Specifies the grant type, e.g., `password` or `refresh_token`.
- **password** (string) - Required if `grant_type` is `password` - The user's password.
- **terminal_code** (string) - Required if `grant_type` is `password` - The terminal code.
- **refresh_token** (string) - Required if `grant_type` is `refresh_token` - The refresh token to use.

### Request Example
```bash
curl --request POST \
  --url https://sandbox.cardpay.com/api/auth/token \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data grant_type=password \
  --data password=123456 \
  --data terminal_code=654321
```

### Response
#### Success Response (200)
- **access_token** (string) - The access token.
- **expires_in** (integer) - The expiration time of the access token in seconds.
- **refresh_expires_in** (integer) - The expiration time of the refresh token in seconds.
- **refresh_token** (string) - The refresh token.
- **token_type** (string) - The type of token, usually `bearer`.

#### Response Example
```json
{
  "access_token": "aGVhZGVyLmFjY2Vzc190b2tlbl9ib2R5LnNpZ25hdHVyZQ==",
  "expires_in": 300,
  "refresh_expires_in": 900,
  "refresh_token": "aGVhZGVyLnJlZnJlc2hfdG9rZW5fYm9keS5zaWduYXR1cmU=",
  "token_type": "bearer"
}
```
```

--------------------------------

### Recurring Transaction Details

Source: https://integration.unlimit.com/api-reference/2958e6cd74e5f-create-recurring

This section details the parameters required for setting up recurring transactions, including subscription details, payment methods, and optional data.

```APIDOC
## POST /api/recurring/transactions

### Description
This endpoint is used to create or manage recurring transactions, including setting up new subscriptions and handling subsequent payments.

### Method
POST

### Endpoint
/api/recurring/transactions

### Parameters
#### Request Body
- **order** (object) - Required - Order details including items and shipping address.
  - **id** (string) - Required - Order ID used by Merchant's shopping cart. (>= 1 characters, <= 200 characters)
  - **items** (array[Item]) - Array of items (in the shopping cart).
  - **shipping_address** (ShippingAddress) - Shipping address details.
- **payment_method** (string) - Required - Payment method type name. Example: `BANKCARD` (>= 1 characters, <= 50 characters)
- **recurring_data** (ScheduledData) - Required - Data for recurring payments. (For BANKCARD payment method only).
  - **contract_number** (string) - Optional - Contract number between customer and merchant. Required for Mexican merchants for scheduled payments. Example: `7481592630ARDS`
  - **dynamic_descriptor** (string) - Optional - Short description of the service or product. Maximum length: 25 symbols for Visa, 22 for MasterCard. (>= 0 characters, <= 25 characters)
  - **encrypted_data** (string) - Optional - Encrypted payment credentials encoded in base64. Only for `scheduled_type = SA` and APPLEPAY. (>= 0 characters, <= 10000 characters)
  - **generate_token** (boolean) - Optional - If set to 'true', a Card token will be generated and returned in GET response. Applicable only for the first recurring request. Example: `false`
  - **initial_amount** (number) - Optional - The amount charged for the initial period. Example: `100`
  - **initiator** (string) - Required - Use `cit` for cardholder initiated transaction. Example: `cit`. Match pattern: `cit`
  - **note** (string) - Optional - Note about the recurring payment, not displayed to customer. (>= 0 characters, <= 100 characters)
  - **plan** (Plan) - Required - Plan details for the recurring payment.
  - **scheduled_type** (string) - Required - Scheduled payment type. For Unlimit scheduled payments, use `SA`. Example: `SA`. Match pattern: `SA`
  - **subscription_start** (string<date-time>) - Optional - The date (yyyy-MM-dd) when the subscription becomes active. Leave empty or specify current date to activate immediately. Example: `2019-04-22`
  - **three_ds_challenge_indicator** (string) - Optional - Indicates whether a 3-D Secure 2 challenge is requested. Values: `01` (No preference), `04` (Challenge requested). Example: `01`. Match pattern: `01|04`
  - **trans_type** (string) - Optional - Identifies the type of transaction. Length: 2 characters. Values: `01`, `03`, `10`, `11`, `28`. Ignored if 'filing.id' is present. Example: `01`. Allowed values: `0103101128`
  - **units** (integer<int32>) - Optional - Units quantity for the subscription. (>= 1)
- **return_urls** (ReturnUrls) - Optional - URLs for redirection after payment.
  - **cancel_url** (string) - Overrides default cancel URL. (>= 0 characters, <= 512 characters)
  - **decline_url** (string) - Overrides default decline URL. (>= 0 characters, <= 512 characters)
  - **inprocess_url** (string) - Special URL for In process status. (>= 0 characters, <= 512 characters)
  - **return_url** (string) - Overrides default success, decline, cancel, and in process URLs. (>= 0 characters, <= 512 characters)
  - **success_url** (string) - Overrides default success URL. (>= 0 characters, <= 512 characters)

### Request Example
```json
{
  "order": {
    "id": "order00017",
    "items": [
      {
        "name": "Product A",
        "price": 100,
        "quantity": 1
      }
    ],
    "shipping_address": {
      "street": "123 Main St",
      "city": "Anytown",
      "state": "CA",
      "zip": "12345",
      "country": "US"
    }
  },
  "payment_method": "BANKCARD",
  "recurring_data": {
    "contract_number": "7481592630ARDS",
    "generate_token": false,
    "initiator": "cit",
    "scheduled_type": "SA",
    "subscription_start": "2023-01-01",
    "trans_type": "01"
  },
  "return_urls": {
    "success_url": "http://www.example.com/success",
    "decline_url": "http://www.example.com/decline"
  }
}
```

### Response
#### Success Response (200)
- **transaction_id** (string) - The unique identifier for the transaction.
- **status** (string) - The status of the transaction (e.g., `APPROVED`, `DECLINED`).
- **recurring_id** (string) - The identifier for the recurring payment setup.

#### Response Example
```json
{
  "transaction_id": "txn_12345abcde",
  "status": "APPROVED",
  "recurring_id": "rec_67890fghij"
}
```

### Error Handling
- **400 Bad Request**: Invalid input parameters.
- **401 Unauthorized**: Authentication failed.
- **403 Forbidden**: Insufficient permissions.
- **404 Not Found**: Resource not found.
- **409 Conflict**: A conflict occurred (e.g., duplicate entry).
- **500 Internal Server Error**: Server error.
```