Create transaction

---

POST /api/distributor

This POST method enables integrators to create payment transactions for distributing funds to designated recipients.

Authentication

This endpoint requires an OAuth 2.0 Bearer Token. Pass the access_token obtained from the authentication flow in the Authorization header:

Authorization: Bearer <access_token>

Request details

Body parameters

Parameter	Type	Required	Description	Possible Values	Note
amount	number	✅	Total payment amount to be transferred.	Positive decimal, max 10 digits with up to 2 decimals (e.g., 1000.50)	Must be greater than 0.
currency	string	✅	Currency in which the transaction will be processed.	GEL, USD, EUR
description	string	✅	Narrative text describing the purpose of the payment. This will appear in the beneficiary's bank statement.	Alphanumeric + Georgian characters + symbols /\-?:().,'+
beneficiaryIdentityNumber	string	❌	Official identity number of the beneficiary (individual or company).
beneficiaryName	string	✅	Full legal name of the beneficiary.		Should match recipient's bank records.
beneficiaryAddress	string	❌	Physical or registered address of the beneficiary.
toIban	string	❌	International Bank Account Number (IBAN) of the beneficiary.		Must be a valid Georgian IBAN if provided.
receiverId	string (UUID v4 format)	❌	Unique identifier of the receiver within the Keepz system.	Example: 123e4567-e89b-12d3-a456-426614174000
receiverType	string	❌	Specifies whether the beneficiary is an individual or a business.	BRANCH, USER
birthDate	string	❌	Date of birth of the beneficiary.	Format: dd.MM.yyyy
uniqueId	string (UUID v4 format)	✅	Unique identifier of the transaction provided by the client.		Ensures idempotency (prevents duplicate payment execution).
debtorName	string	❌	Full legal name of the payer. Must match regex: ^[a-zA-Z0-9/\\-?:().,'+აბგდევზთიკლმნოპჟრსტუფქღყშჩცძწჭხჯჰ ]+$. Appears in the bank description only.		This field can only be sent by integrators who have been granted explicit permission by Keepz.
debtorIban	string	❌	IBAN of the payer. Appears only in the bank description; funds are not debited from this account. Must match regex: ^GE\\d{2}[A-Z]{2}\\d{16}$.		This field can only be sent by integrators who have been granted explicit permission by Keepz.
debtorIdentityNumber	string	❌	Identity number of the payer. Appears in the bank description only.	9 or 11 digits	This field can only be sent by integrators who have been granted explicit permission by Keepz.
fromIban	string	❌	IBAN from which the payment amount will actually be debited. Must match regex: ^GE\\d{2}[A-Z]{2}\\d{16}$.		This field can only be sent by integrators who have been granted explicit permission by Keepz.

Note on Recipient Identification

The fields receiverId, receiverType, and toIban are mutually exclusive, depending on the distributor configuration:

To-IBAN transfers: Use toIban to specify the beneficiary's bank account directly.

To-Receiver transfers: Use receiverId together with receiverType if the integrator is configured to send funds to a registered Keepz receiver.

If the integrator provides receiverId and receiverType, the system will resolve the recipient internally and the toIban field is not required. Conversely, if toIban is provided, receiverId and receiverType should be omitted.

This flexibility allows integrators to either reference a known Keepz receiver or specify an IBAN directly, depending on their integration setup.

Example:

{
  "amount": 1000,
  "currency": "GEL",
  "description": "Test payment",
  "toIban": "GE34TB0000000000000000",
  "beneficiaryName": "Giorgi Giorgadze",
  "uniqueId": "123e4567-e89b-12d3-a456-426614174000"
}

Response details

✅ Success Response

If the request is valid, the API returns next payload:

Parameter	Type	Description	Possible Values	Note
transactionId	number	Unique identifier of the transaction in the system.		Returned by the server after transaction creation.
status	string	Current status of the transaction.		Current status of the transaction. See Transaction Status Codes.
statusDescription	string	Human-readable description of the transaction status.		Provides more context for the status.
uniqueId	string (UUID v4)	Unique identifier of the transaction provided by the client.		Matches uniqueId from request to ensure idempotency.
createdAt	string (ISO 8601 datetime)	Timestamp when the transaction was created.	Example: 2025-08-25T12:34:56.789Z

❌ Error Response

If an error occurs, the API returns next payload:

{
  "message": "Transaction with such unique ID already exists",
  "statusCode": 5017
}

Parameter	Type	Description
message	string	Error message. Details are provided in the dedicated section below.
statusCode	number	Error status code. Details are provided in the dedicated section below.

⚠️ Important: Make sure to include the Bearer token in the Authorization header for all requests. The uniqueId must be unique to ensure idempotency and prevent duplicate transactions.

Details can be found at Error Code Description.