Partner Balance Payment Methods

Since PARTNER_BALANCE payment method usage involves partner accounts balance and partner-aware calculations, all endpoints on this integration are prefixed with /private and require authentication.

0. Authentication

First of all, you should do API key generation via the Forimex Backoffice: it will bring the private key to you, and will register the key pair in the system.

To pass the authentication you should provide headers such as:

• date – request date-time in format described in RFC9110
• x-sig-alg – signature algorithm, for now, only ED25519 is acceptable;
• x-sig-key-id – keyid collected from the Backoffice while API key generation;
• x-sig-hash – resulting base64-encoded signature.

Prepare message bytes

0. Prepare the request, that is going to be send: set the endpoint, headers (w/o x-sig-hash), body;
1. Take the request method verb in upper case, e.g. POST (verb);
2. Take the Keccak256 hash of the body bytes and encode it to string using base64 standard (content_hash);
3. Prepare the Date in appropriate format (RFC9110) (date);
4. Take the request path with query params in lower case (path_with_query);
5. Join all x-sig-* headers with \n as separator (headers);
6. Join all prepared above strings with \n as separator: {verb}\n{content_hash}\n{date}\n{path_with_query}\n{headers} and decode resulting string to bytes (suppose utf8 encoding) (bytes);
7. Sign the resulting bytes by private key generated in Backoffice using ED25519 algorithm, encode resulting bytes to base64-encoded string (standard) (sig-hash).
8. Attach resuling sig-hash to the request on header (x-sig-hash)

Test vector

Data:

method: GET
path: /v1/private/accounts
date: Sat, 27 Dec 2025 23:43:25 GMT
key_id: 2c717ce1-841d-4f70-8a05-e35f9c73896b
body: empty

Message bytes (base64-encoded):

R0VUCnhkSkdBWWIzSXp5U2ZuMnkzTWNEd09VQXRsUEtnaWM3ZS9yWUJGMkZwSEE9ClNhdCwgMjcgRGVjIDIwMjUgMjM6NDM6MjUgR01UCi92MS9wcml2YXRlL2FjY291bnRzCkVEMjU1MTkKMmM3MTdjZTEtODQxZC00ZjcwLThhMDUtZTM1ZjljNzM4OTZi

Private key (hex-encoded):

957d29f8830b091d12c262888facea269946ffae762b47369006d04b42a17a80

Resulting signature (base64-encoded):

vOKYI0N97JA+HE0NCOcID5ShZMfM901cX6UidaealfpaizANXnqH4b7sNPQ4SJxKAmDbDz3hiRuZuSIN6qOfAQ==

To create money-transfer service order, it requires to pass additional external_kyc field beside the service, payment and tags with customer KYC data such as his last and first name, date of birth, document data (passport) etc.

Example:

Create money-transfer via SBP

Country = RUS

Receiving method = phone_number

1. Do payment amount calculation

Endpoint POST /v1/private/transfers/countries/RUS/methods/phone_number/calculation API Reference

Request headers:

Request body:

{
  "receive_amount": "100",
  "receive_currency": "RUB",
  "payment_currency": "RUB",
  "payment_method": "PARTNER_BALANCE"
}

Response:

{
  "payment_amount": "101.3",
  "service_fee": "1.3"
}

2. Create the order

Endpoint: POST /v1/private/orders API Reference

Request headers:

Request:

{
  "service": {
    "slug": "phone_number",
    "region": "ISO-3166-1:A2:RU",
    "funding_method": "MONEY_TRANSFER",
    "funding_details": {
      "receive_amount": "100",
      "receive_currency": "RUB"
    },
    "extras": {
      "recipient_phone_number": "79998887766",
      "recipient_bank": "alfa_bank",
      "sender_phone_number": "79998887766"
    }
  },
  "payment": {
    "amount": "101.3",
    "currency": "RUB",
    "method": "PARTNER_BALANCE"
  },
  "external_kyc": {
    "first_name": "Тест",
    "last_name": "Тестовый",
    "gender": "M",
    "passport_series": "1234",
    "passport_number": "567890",
    "passport_issue_date": "2018-01-02",
    "issuer_department_code": "770-077",
    "birth_place": "г. Москва",
    "birth_date": "1991-01-03"
  }
}