Create an order

POST /api/integrator/order

This POST method is used to create an individual order in the Keepz system.

Request details

When sending request to Keepz, these four parameters must always be included in the body.

{
  "identifier": "string",
  "encryptedData": "string",
  "encryptedKeys": "string",
  "aes": true
}

identifier

Unique ID of the integrator in the Keepz system.
Provided by Keepz during the integration process.

encryptedData

Contains the actual request payload encrypted using a randomly generated symmetric key and IV (Initialization Vector).

encryptedKeys

Contains the AES key and IV used to encrypt encryptedData.

aes

Boolean flag indicating that the request uses AES-based symmetric encryption (needed for backward compatibility with older encryption methods).

For details on the encryption process, see the Encryption Guide documentation.

Parameters

The following parameters form the actual order payload. They must be included inside the encryptedData parameter, which is encrypted and passed in the request as shown above.

Parameter	Type	Required	Description	Possible values	Note
`amount`	number	✅	Amount of requested funds	Must be >0
`receiverId`	string (UUID v4 format)	✅	Identifier of the money recipient in the Keepz system. Provided to the integrator by a Keepz representative.
`receiverType`	string	✅	Type of the money recipient in the Keepz system.	BRANCH
`integratorId`	string (UUID v4 format)	✅	Unique ID of the integrator in the Keepz system. Provided to the integrator by a Keepz representative.
`integratorOrderId`	string (UUID v4 format)	✅	Unique ID of order in the integrator’s system.
`currency`	string	❌	Currency displayed to the sender. GEL by default.	GEL, USD, EUR
`acquiringCurrency`	string	❌	Currency in which the payment is acquired (i.e., the currency withdrawn from the sender’s card).	GEL, USD, EUR	This field can only be sent by integrators who have been granted explicit permission by Keepz. For all others, it is configured on the Keepz side and not included in the request.
`distributionCurrency`	string	❌	Currency in which funds are transferred to the receiver.	GEL, USD, EUR	This field can only be sent by integrators who have been granted explicit permission by Keepz. For all others, it is configured on the Keepz side and not included in the request.
`tipReceiverId`	string (UUID v4 format)	❌	Identifier of the tip recipient in the Keepz system.		This field can only be sent by integrators who have been granted explicit permission by Keepz, have tipping configured for their integration, and have been provided the tipReceiverId by a Keepz representative.
`tipReceiverType`	string	❌	Type of tip receiver in the Keepz system.	BRANCH,USER	This field can only be sent by integrators who have been granted explicit permission by Keepz, have tipping configured for their integration, and have been provided the tipReceiverId by a Keepz representative.
`successRedirectUri`	string	❌	The web address of the business to redirect the user after successful payment.		This field can only be sent by integrators who want a unique URL for each order and have been granted explicit permission by Keepz. Otherwise, you can provide a single default URL during integration, and Keepz will configure it for your account.
`failRedirectUri`	string	❌	The web address of the business to redirect the user if payment fails.		This field can only be sent by integrators who want a unique URL for each order and have been granted explicit permission by Keepz. Otherwise, you can provide a single default URL during integration, and Keepz will configure it for your account.
`callbackUri`	string	❌	The web address of the business, which will be automatically called by the Keepz upon completion of the payment to provide the business with the payment details.		This field can only be sent by integrators who want a unique URL for each order and have been granted explicit permission by Keepz. Otherwise, you can provide a single default URL during integration, and Keepz will configure it for your account. For details on the callback, see the documentation.
`directLinkProvider`	string	❌	Bank card payment provider.	BOG, TBC, CREDO, DEFAULT	If this parameter is not sent, the checkout page URL will be returned, where the sender can manually choose the payment method.If this parameter is sent, the payment method is pre-selected as bank card, and the user is redirected directly to the bank’s payment page.The integrator can pass the exact provider (e.g., BOG) to select a specific bank card provider. If the integrator only wants to pre-select the payment method without specifying the bank, they can send the value DEFAULT. In this case, the system will use the default bank configured in Keepz for the recipient. This field can only be sent by integrators who have been granted explicit permission by Keepz.
`openBankingLinkProvider`	string	❌	Open banking payment provider.	TBC, BOG, CREDO, LB	If this parameter is not sent, the checkout page URL will be returned, where the sender can manually choose the payment method. If this parameter is sent, it means the payment method is open banking, and the value specifies the provider bank (e.g., TBC). The user will be redirected directly to that bank’s open banking flow. This field can only be sent by integrators who have been granted explicit permission by Keepz.
`cryptoPaymentProvider`	string	❌	Cryptocurrency payment provider.	CITYPAY	If this parameter is not sent, the checkout page URL will be returned, where the sender can manually choose the payment method. If this parameter is sent, it means the payment method is cryptocurrency, processed through CityPay, and the value(e.g.CITYPAT_WALLET) specifies the method. The user will be redirected directly to the selected crypto payment flow. This field can only be sent by integrators who have been granted explicit permission by Keepz.
`installmentPaymentProvider`	string	❌	Installment payment provider.	CREDO	If this parameter is not sent, the checkout page URL will be returned, where the sender can manually choose the payment method.If this parameter is sent, it means the payment method is installment, and the value specifies the provider (e.g., CREDO). The user will be redirected directly to that provider’s installment payment flow. This field can only be sent by integrators who have been granted explicit permission by Keepz.
`personalNumber`	string	❌	Payer’s national identification number (for a physical or legal person).		Mandatory only if installmentPaymentProvider is provided. For Georgian citizens, the value must be either exactly 9 digits or exactly 11 digits.
`isForeign`	boolean	❌	Indicates if the payer is a foreign citizen.	TRUE,FALSE	Mandatory only if installmentPaymentProvider is provided.
`validUntil`	string	❌	Date and time until the order remains valid for payment.		If provided, the order can be retried for successful payment multiple times until the specified expiration date and time. Format: "yyyy-MM-dd HH:mm:ss" (e.g., "2025-08-15 18:30:00"). This field can only be sent by integrators who have been granted explicit permission by Keepz.
`language`	string	❌	Language for payment page.	EN, IT, KA	If not provided, the default language configured in Keepz for the recipient will be used.
`commissionType`	string	❌	Specifies who pays the commission for the transaction.	SENDER, RECEIVER, BOTH
`saveCard`	boolean	❌	Whether to save the payer’s card for future use.	TRUE,FALSE	If set to true, the card will be securely tokenized after a successful payment. The tokenized card identifier (cardToken) will be included in the cardInfo object of the payment callback. This token can later be used in the cardToken field of future orders to charge the saved card without requiring the customer to re-enter card details.This field can only be used if `directLinkProvider` is provided and integrator have been granted explicit permission by Keepz.
`cardToken`	string(UUID v4 format)	❌	Tokenized card identifier for saved payments.		Returned in the cardInfo object of the payment callback when saveCard: true is passed during order creation. The integrator can provide this token in the cardToken field to charge the saved card without requiring the customer to re-enter card details. This field can only be used by integrators who have been granted explicit permission by Keepz.
`subscriptionPlan`	object	❌	Details for creating a recurring payment schedule when saving a card.		This object can only be sent by integrators who have been granted explicit permission by Keepz. When provided, the system automatically charges the saved card according to the defined schedule. saveCard must be set to true, and amount must be 0. Object details are provided in the dedicated section below.
`splitDetails`	array of objects	❌	Defines how the order amount is split between multiple recipients.		Details are provided in the dedicated section below.
orderProperties	object	❌	Additional contextual fields required for specific order payment types.		Details are provided in the dedicated section below.

Complex Types Description

Subscription plan

Parameter	Type	Required	Description	Possible values	Note
`interval`	string	✅	The unit of time between payments.	MONTHLY, WEEKLY
`intervalCount`	number	✅	Number of intervals between payments.		Example: interval = MONTHLY, intervalCount = 2 → one payment every 2 months. Example: interval = WEEKLY, intervalCount = 1 → one payment every week.
`amount`	number	✅	Price per interval.	Must be greater than 0.
`startDate`	string	❌	First payment date.	Must be today or a future date.	If not provided, the first payment is processed immediately (default behavior).

Split details

Each object in the array represents one recipient and contains:

Parameter	Type	Required	Description	Possible values	Note
`receiverType`	string	✅	Type of recipient in the Keepz system.	BRANCH,USER,IBAN	BRANCH– a registered branch in Keepz. USER – a registered user in Keepz. IBAN – an external IBAN account (not registered in Keepz).
`receiverIdentifier`	string	✅	Unique identifier of the recipient.		For BRANCH and USER, this is a UUID provided by Keepz. For IBAN, this is the IBAN number.
`amount`	number	✅	Amount to send to this recipient.	Must be greater than 0.

Order properties

orderProperties is an optional key–value map used to send extra order-specific information based on the configured order type (DEFAULT, TRAFFIC_FINE, TREASURY).

Structure

Key → An enumerated constant representing a specific additional property for the order. Possible values: PERSONAL_NUMBER, PAYER_NAME, PURPOSE, PERSONAL_NUMBER_OR_PASSPORT, IS_FOREIGN, SERVICE_PROVIDER_CODE, SERVICE_CODE, ENTITY_IDENTIFIER, CAR_IDENTIFIER, INVOICE_NUMBER_LABEL, DESCRIPTION, INTEGRATOR_PRODUCT_NAME, ABONENT_CODE

Value → An object describing the field content and whether the payer can edit it:

Parameter	Type	Required	Description	Possible values	Note
`value`	string	✅	The actual content or data for the given key.
`isEditable`	boolean	❌	Indicates whether the payer can modify this value during checkout. Defaults to false if not provided.

Field requirements

M – Mandatory: Request will be rejected if missing or invalid.
O – Optional: Can be sent if available.
M (H) – Hidden: Must be sent, not shown to payer.
O (H) – Optional but hidden from payer.
– Not used for this payment type.

Field	DEFAULT	TREASURY	TRAFFIC FINE
PERSONAL_NUMBER	-	M	-
PAYER_NAME	-	M	-
PURPOSE	-	M	-
IS_FOREIGN	-	M	-
SERVICE_PROVIDER_CODE	-	-	M (H)
SERVICE_CODE	-	-	M (H)
ENTITY_IDENTIFIER	-	-	M
CAR_IDENTIFIER	-	-	M
INVOICE_NUMBER_LABEL	O	-	-
DESCRIPTION	O	-	-
INTEGRATOR_PRODUCT_NAME	O (H)	-	-

Notes for developers

You must send only the fields relevant for the given order payment type.
If a field is marked Mandatory (M) and is missing or invalid, the API will reject the request.
Hidden (H) fields are still required in the request but are never displayed to the payer.
The isEditable property only affects what the payer can modify during checkout; it does not bypass server-side validation.

Examples

The following examples demonstrate only the minimum required fields for each use case.

👉 Developers can always include any other supported optional parameters in the same request if needed.

Examples

How to save a card

{
  "amount": 10,
  "receiverId": "90434fa9-46df-4c44-a4d1-da742ac815da",
  "receiverType": "BRANCH",
  "integratorId": "ce3a3476-a542-4e5d-a957-72fcd0e35d2c",
  "integratorOrderId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "saveCard": true,
  "directLinkProvider": "CREDO"
}

How to pay with a saved card

{
  "amount": 10,
  "receiverId": "90434fa9-46df-4c44-a4d1-da742ac815da",
  "receiverType": "BRANCH",
  "integratorId": "ce3a3476-a542-4e5d-a957-72fcd0e35d2c",
  "integratorOrderId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "cardToken": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
}

How to create a subscription plan

{
  "amount": 0,
  "receiverId": "90434fa9-46df-4c44-a4d1-da742ac815da",
  "receiverType": "BRANCH",
  "integratorId": "ce3a3476-a542-4e5d-a957-72fcd0e35d2c",
  "integratorOrderId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "saveCard": true,
  "subscriptionPlan": {
    "interval": "MONTHLY",
    "intervalCount": 1,
    "amount": 10,
    "startDate": "2025-10-18T10:00:00.000Z"
  }
}

How to create split order

{
  "amount": 100,
  "receiverId": "90434fa9-46df-4c44-a4d1-da742ac815da",
  "receiverType": "BRANCH",
  "integratorId": "ce3a3476-a542-4e5d-a957-72fcd0e35d2c",
  "integratorOrderId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "splitDetails": [
    {
      "receiverType": "BRANCH",
      "receiverIdentifier": "90434fa9-46df-4c44-a4d1-da742ac815da",
      "amount": 75
    },
    {
      "receiverType": "IBAN",
      "receiverIdentifier": "GE34BG0000001234567890",
      "amount": 25
    }
  ]
}

How to create order for open w

{
  "amount": 100,
  "receiverId": "90434fa9-46df-4c44-a4d1-da742ac815da",
  "receiverType": "BRANCH",
  "integratorId": "ce3a3476-a542-4e5d-a957-72fcd0e35d2c",
  "integratorOrderId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "openBankingLinkProvider": "CREDO"
}

How to create order for card

{
  "amount": 100,
  "receiverId": "90434fa9-46df-4c44-a4d1-da742ac815da",
  "receiverType": "BRANCH",
  "integratorId": "ce3a3476-a542-4e5d-a957-72fcd0e35d2c",
  "integratorOrderId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "directLinkProvider": "DEFAULT"
}

How to create order for crypto

{
  "amount": 100,
  "receiverId": "90434fa9-46df-4c44-a4d1-da742ac815da",
  "receiverType": "BRANCH",
  "integratorId": "ce3a3476-a542-4e5d-a957-72fcd0e35d2c",
  "integratorOrderId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "cryptoPaymentProvider": "CITYPAY"
}

How to create order for installment

{
  "amount": 100,
  "receiverId": "90434fa9-46df-4c44-a4d1-da742ac815da",
  "receiverType": "BRANCH",
  "integratorId": "ce3a3476-a542-4e5d-a957-72fcd0e35d2c",
  "integratorOrderId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "installmentPaymentProvider": "CREDO",
  "personalNumber": "6100*******",
  "isForeign": false
}

How to create an expiring order

{
  "amount": 100,
  "receiverId": "90434fa9-46df-4c44-a4d1-da742ac815da",
  "receiverType": "BRANCH",
  "integratorId": "ce3a3476-a542-4e5d-a957-72fcd0e35d2c",
  "integratorOrderId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "validUntil": "2026-10-18T09:51:14.387Z"
}

How to create an TREASURY order

{
  "amount": 10,
  "receiverId": "90434fa9-46df-4c44-a4d1-da742ac815da",
  "receiverType": "BRANCH",
  "integratorId": "ce3a3476-a542-4e5d-a957-72fcd0e35d2c",
  "integratorOrderId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "orderProperties": {
    "PURPOSE": {
      "value": "exmaple",
      "isEditable": true
    },
    "IS_FOREIGN": {
      "value": "false",
      "isEditable": false
    },
    "PAYER_NAME": {
      "value": "Giorgi maisuradze",
      "isEditable": false
    },
    "PERSONAL_NUMBER": {
      "value": "6100*******",
      "isEditable": false
    }
  }
}

How to create a TRAFFIC FINE order

{
  "amount": 10,
  "receiverId": "90434fa9-46df-4c44-a4d1-da742ac815da",
  "receiverType": "BRANCH",
  "integratorId": "ce3a3476-a542-4e5d-a957-72fcd0e35d2c",
  "integratorOrderId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "orderProperties": {
    "SERVICE_PROVIDER_CODE": {
      "value": "PATROL",
      "isEditable": false
    },
    "SERVICE_CODE": {
      "value": "PATROL",
      "isEditable": false
    },
    "ENTITY_IDENTIFIER": {
      "value": "TEST123",
      "isEditable": false
    },
    "CAR_IDENTIFIER": {
      "value": "TT000TT",
      "isEditable": false
    }
  }
}

Response details

✅ Success Response

If the request is valid, the API returns an encrypted payload:

{
  "encryptedData": "string",
  "encryptedKeys": "string",
  "aes": true
}

encryptedData

Contains the actual response payload encrypted using a randomly generated symmetric key and IV (Initialization Vector).

encryptedKeys

Contains the AES key and IV used to encrypt encryptedData.

aes

Boolean flag indicating that the request uses AES-based symmetric encryption (needed for backward compatibility with older encryption methods).

For details on the decryption process, see the Encryption Guide documentation.

Inside encryptedData, the following parameters are available after decryption:

Parameter	Type	Description
`integratorOrderId`	string (UUID v4 format)	Unique ID of order in the integrator’s system passed during order creation.
`urlForQR`	string	The checkout page URL where the customer is redirected to select a payment method and complete the transaction. If the integrator specifies a payment method in advance, the customer is taken directly to complete the payment with that method.

❌ Error Response

If an error occurs, the response is returned without encryption (plain JSON):

{
  "message": "You do not have permission to save card!",
  "statusCode": 6031,
  "exceptionGroup": 3
}

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.
`exceptionGroup`	number	Error group. Details are provided in the dedicated section below.

Details can be found at Error Code Description.

Scheme

The diagram below illustrates the complete flow of creating an order in the Keepz system, from initial request to payment completion.

Create an order

Request details​

identifier​

encryptedData​

encryptedKeys​

aes​

Parameters​

Complex Types Description​

Subscription plan​

Split details​

Order properties​

Field requirements​

Notes for developers​

Examples​

Examples​

How to save a card​

How to pay with a saved card​

How to create a subscription plan​

How to create split order​

How to create order for open w​

How to create order for card​

How to create order for crypto​

How to create order for installment​

How to create an expiring order​

How to create an TREASURY order​

How to create a TRAFFIC FINE order​

Response details​

encryptedData​

encryptedKeys​

aes​

Scheme​

Request details

identifier

encryptedData

encryptedKeys

aes

Parameters

Complex Types Description

Subscription plan

Split details

Order properties

Field requirements

Notes for developers

Examples

Examples

How to save a card

How to pay with a saved card

How to create a subscription plan

How to create split order

How to create order for open w

How to create order for card

How to create order for crypto

How to create order for installment

How to create an expiring order

How to create an TREASURY order

How to create a TRAFFIC FINE order

Response details

encryptedData

encryptedKeys

aes

Scheme