> ## Documentation Index
> Fetch the complete documentation index at: https://docs.spotflow.one/llms.txt
> Use this file to discover all available pages before exploring further.

# Introduction

> Spotflow is your global Merchant of Record (MoR) that simplifies payment processing for businesses worldwide. We handle everything from global payment acceptance to compliance and settlement — empowering merchants to go global effortlessly. Learn how to easily integrate our APIs to streamline your in-app payments.

To learn on payment states, go to [this page](/developer-resources/payment-states)
To know more about our rate limiting, go [to](/api-reference/rate-limits)

## Which Payment Endpoint Should I Use?

<CardGroup cols={2}>
  <Card title="Initialize Payment (Redirect)" icon="arrow-up-right-from-square" href="/api-reference/payments/initialize-collection">
    **Recommended for most integrations.**
    No PCI-DSS certification required. Spotflow hosts the checkout
    page. Customer is redirected to complete payment.
  </Card>

  <Card title="Create Payment (Direct)" icon="code" href="/api-reference/payments/create-collection">
    **Requires PCI-DSS certification.**
    You collect card details directly and pass them encrypted to
    our API. Only use this if you are PCI-DSS certified.
  </Card>
</CardGroup>

Spotflow API helps global merchant collect payments in local currency. Learn how to easily integrate our APIs to streamline your in-app payments.

Spotflow API is designed to be <span style={{color: "red"}}>`RESTful`</span>, utilizing familiar resource structures for most interactions. However, there might be a few exceptions from the strict REST principles for specific functionalities. These exceptions will be clearly documented within the API reference. This means you can expect:

* **Predictable Resource-Oriented URLs**: URLs are designed to be clear and intuitive, reflecting the resources you're interacting with (e.g., /payments, /plans).
* **Form-Encoded Request Bodies**: Data sent to the API uses a simple, well-understood format called form-encoded data.
* **JSON-Encoded Responses**: Our API returns data in JSON response format, providing structured and easy-to-parse data.
* **Standard HTTP Methods and Response Codes**: Our API utilizes standard HTTP verbs for different actions like GET for retrieving data, POST for creating new resources, PUT for updating existing ones and DEL for trashing existing ones. It also returns standard HTTP response codes to indicate success or failure (e.g., 200 for success, 400 for bad request).
* **Content-Type**: When sending request to the API, you should ensure your request includes a Content-Type header set to application/JSON. This informs the API about the format of the data you are sending.

### API Keys and Authentication:

To ensure secure communication with Spotflow APIs, you'll need to authenticate your requests using an API key. All endpoints access requires authentication with your API Keys. Your API key acts as a unique identifier for your application and allows us to differentiate between test and live mode usage. Specific instructions for including your API key within your requests will be provided in the documentation for each API endpoint. Your API Keys can be found on the API Keys and webhooks section of your dashboard.

## Idempotency

All POST requests that create or initiate transactions accept an idempotency
key via the `reference` field in the request body. If you send two requests
with the same `reference`, Spotflow will process it once and return the same
response for subsequent requests.

### Rules

* The `reference` field on Create Payment and Create Disbursement is your
  idempotency key
* References must be unique per transaction type (payment references are
  separate from disbursement references)
* Deduplication window: 24 hours
* If the first request failed with a 5xx error, it is safe to retry with
  the same reference
* If the first request succeeded, retrying with the same reference returns
  the original response without creating a duplicate

### For AI Agents

Before retrying any failed POST request, check whether the original request
may have succeeded. Call the corresponding GET endpoint with your reference
to check status. If the resource exists, do not retry.

## Pagination

All list endpoints return paginated results.

### Request Parameters

| Parameter | Type    | Default | Description                          |
| --------- | ------- | ------- | ------------------------------------ |
| `page`    | integer | 1       | Page number to retrieve              |
| `limit`   | integer | 20      | Number of results per page. Max: 100 |

### Response Shape

All list endpoints return a consistent envelope:

```json theme={null}
{
  "data": [...],
  "meta": {
    "total": 150,
    "page": 1,
    "limit": 20,
    "totalPages": 8,
    "hasNextPage": true,
    "hasPrevPage": false
  }
}
```

### For AI Agents

To retrieve all records, loop through pages until `hasNextPage` is `false`.
Do not assume all records are returned in a single response.