Skip to main content
To learn on payment states, go to this page To know more about our rate limiting, go to

​
Which Payment Endpoint Should I Use?

Initialize Payment (Redirect)

Recommended for most integrations. No PCI-DSS certification required. Spotflow hosts the checkout page. Customer is redirected to complete payment.

Create Payment (Direct)

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.
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 RESTful, 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

​
Response Shape

All list endpoints return a consistent envelope:

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