Basics of using the API

The Forimex API is based on RESTful principles, processing real objects with predictable behavior. Using the API, you can fetch services data, send payment amount calculation requests, make orders and more.

The API uses HTTP as the main protocol, making it suitable for development in any programming language that can work with HTTP libraries (cURL and others).

The API supports POST, GET, and DELETE requests.

• POST requests use JSON arguments,
• GET and DELETE requests use query strings.

The API always returns the response in JSON format, regardless of the type of request.

Authentication

All partner requests to Forimex has to have x-partner-slug header to be set with value, as it was provided to get an access to Backoffice.

In case of using PARTNER_BALANCE payment methods, requests requires additional headers, as it's explained in Partner Balance Payment Method

Idempotence

In the context of API, idempotence is the concept of multiple requests having the same effect as a single request. Upon receiving a new request with identical parameters, Forimex will respond with results of the original request. Such behavior helps prevent unwanted repetition of transactions: for example, if during the payment process the Internet connection was interrupted due to network problems, you’ll be able to safely repeat the request for an unlimited number of times.

To ensure the idempotency of requests, the x-idempotence-key header is used. The maximum length is 64 characters. We recommend using V4 UUID.

Example of a request with idempotence key

curl https://demo-api.forimex.tech/v1/orders \
  -X POST \
  -H 'Content-Type: application/json' \
  -H 'x-idempotence-key: <idempotence-key>' \
  -H 'x-partner-slug: <your-partner-slug>' \
  -d '{
    "service": {
      "slug": "steam",
      "region": "CUSTOM:GLOBAL", 
      "extras": {
        "account": "testing"
      },
      "funding_method": "TOPUP",
      "funding_details": {
        "topup_amount": "1",
        "topup_currency": "USD"
      }
    },
    "payment": {
      "amount": "79.84",
      "currency": "RUB",
      "method": "SBP"
    },
    "tags":{}
  }'

const idempotenceKey = window.crypto.randomUUID();
const partnerSlug = '<your-partner-slug>';
const baseUrl = 'https://demo-api.forimex.tech/v1';
const ordersEndpoint = `${baseUrl}/orders`;

const payload = {
  service: {
    slug: "steam",
    region: "CUSTOM:GLOBAL", 
    extras: {
      account: "testing"
    },
    funding_method: "TOPUP",
    funding_details: {
      topup_amount: "1",
      topup_currency: "USD"
    }
  },
  payment: {
    amount: "79.84",
    currency: "RUB",
    method: "SBP"
  },
  tags:{}
};

fetch(ordersEndpoint, {
  method: 'POST',
  headers: {
    'content-type': 'application/json',
    'x-idempotence-key': idempotenceKey,
    'x-partner-slug': partnerSlug
  },
  body: JSON.stringify(payload)
})

If you repeat the request with the same data and the same key, the API processes it as a duplicate. If the data in the request is the same, but the idempotence key is different, the request is processed as a new one.

The idempotency key must be specified for POST and DELETE requests. GET requests are idempotent by default, as they do not result in undesirable consequences.

Response format

The response to a request contains an HTTP response (status) code, standard headers, and if neccessary a response body.

Upon successful processing of a request (HTTP 200), Forimex returns the created, modified, or requested object or list of objects in the response body. The response body format is JSON. The response body parameters depend on the request.

Example of response body

{
  "data": {
    "id": "ef8f434e-3a25-439e-b4af-800ce83a6a2b",
    "state": "CREATED",
    "created_at": "2025-10-24T14:15:16Z",
    "info": {
      "service_slug": "steam",
      "service_region": "ISO-3166-1:A2:US",
      "funding_method": "TOPUP",
      "funding_details": {
        "topup_amount": "100",
        "topup_currency": "USD"
      },
      "payment_details": {
        "amount": "765.43",
        "currency": "RUB"
      },
      "extras": {}
    },
    "external_id": null
  }
}

If something is wrong with the request (HTTP response code other than 200), then HTTP response codes 400, 401, 403, 404, 422, and 500 will return a response body in JSON format with a description of the error.

Response Error Codes