v1.1API REFERENCE
MultiPrime API
Create a card or wallet payment from your backend and check its final status. Customers enter card and wallet data only on the hosted payment page.
{
"success": true,
"code": "PAYMENT_PAGE_CREATED",
"paymentId": "GATEWAY_PAYMENT_ID",
"redirectUrl": "HOSTED_PAYMENT_PAGE_URL",
"redirectMethod": "POST"
}- Format
- JSON
- Signature
- HMAC-SHA256
- Endpoints
- 2
01 · OVERVIEW
How a payment works
Your backend uses two endpoints: paymentinit.cgi to create a payment and paymentstatuscheck.cgi to check its verified status.
- STEP 01
Create payment
Your backend calls paymentinit.cgi with the order.
- STEP 02
Redirect
Send the customer to the hosted payment page.
- STEP 03
Result URL
The browser returns to your result URL with the verified result.
- STEP 04
Status check
Reconcile with paymentstatuscheck.cgi before fulfilment.
Placeholders used in examples
| Placeholder | Description |
|---|---|
| BASEURL | Gateway base address for the environment, for example BASEURL/cgi-bin/paymentinit.cgi. |
| MERCHANT_ID | Merchant identifier issued by the gateway. |
| API_KEY | Public API key issued to the merchant for the selected environment. |
| API_SECRET | Secret key the merchant backend uses to sign requests. Never expose it in browser JavaScript. |
| MERCHANT_PAYMENT_ID | Your unique payment or order identifier. Must be unique per merchant. |
| MERCHANT_RESULT_URL | Your page or endpoint where the browser returns after verification. |
02 · AUTHENTICATION
Signed requests
Every call from your backend to the gateway includes these headers. The same rules apply to both endpoints.
| Header | Required | Value |
|---|---|---|
| X-Merchant-Id | Yes | MERCHANT_ID |
| X-Api-Key | Yes | API_KEY |
| X-Timestamp | Yes | Unix timestamp in seconds, UTC. |
| X-Nonce | Yes | Unique random value per request. Recommended: at least 16 bytes, hex. |
| X-Signature | Yes | Base64 HMAC-SHA256 signature calculated with API_SECRET. |
| Content-Type | For POST | application/json |
| Accept | Recommended | application/json |
# Canonical string: one value per line, in this order
HTTP_METHOD
REQUEST_PATH_WITH_QUERY
X-Timestamp
X-Nonce
SHA256_HEX(REQUEST_BODY)
# Signature
signature = BASE64( HMAC_SHA256(API_SECRET, canonical_string) )
# GET without a body: SHA-256 of the empty string
e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855API_SECRET only in your backend configuration. Never place it in browser-side JavaScript.03 · CREATE PAYMENT
Create a payment
POSTBASEURL/cgi-bin/paymentinit.cgi
Call this endpoint from your backend before sending the customer to the hosted payment page.
| Field | Description |
|---|---|
| merchantPaymentIdstring · required | Your unique payment ID for reconciliation and status lookup. |
| referencestring · required | Human-readable order reference. Recommended: the order number. |
| amountstring · required | Decimal amount with two digits, for example "1.00". |
| currencystring · required | ISO currency code, for example GEL. |
| resultUrlstring · required | Your return address: MERCHANT_RESULT_URL. |
| descriptionstring · recommended | Text shown on the payment page, if supported. |
| languagestring · recommended | Card: EN or KA. Apple Pay: EN, KA or RU. Google Pay: EN or KA. |
| paymentMethodstring · optional | Payment page mode. CARD if omitted. |
| resultDeliveryMethodstring · optional | POST or GET. Recommended: POST. |
| saveCardboolean · optional | true only with an enabled card-tokenization agreement. |
| bankCodestring · optional | Preferred bank group. If omitted, the gateway routes the payment. |
| bankNodeIdstring · optional | Processing node, if agreed for your merchant. |
| metadataobject · optional | Your non-sensitive values. Never card or wallet data. |
curl -X POST "BASEURL/cgi-bin/paymentinit.cgi" \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-H "X-Merchant-Id: MERCHANT_ID" \
-H "X-Api-Key: API_KEY" \
-H "X-Timestamp: 1780000000" \
-H "X-Nonce: 6b45e1f4c3f64a9a9d3e4219cb7f95c1" \
-H "X-Signature: SIGNATURE" \
-d '{
"merchantPaymentId": "MERCHANT_PAYMENT_ID-100001",
"reference": "ORDER-100001",
"amount": "1.00",
"currency": "GEL",
"description": "Payment for order ORDER-100001",
"language": "EN",
"paymentMethod": "CARD",
"resultUrl": "MERCHANT_RESULT_URL",
"resultDeliveryMethod": "POST",
"saveCard": false,
"metadata": { "cartId": "CART-100001" }
}'04 · PAYMENT METHODS
Payment page modes
The request and authentication stay the same. To open a wallet page, change paymentMethod and keep saveCard=false.
| paymentMethod | Payment page | Languages |
|---|---|---|
| CARD | Standard card payment page | EN, KA |
| APPLE_CARD | Card + Apple Pay | EN, KA, RU |
| APPLE_PAY | Apple Pay only | EN, KA, RU |
| GOOGLE_CARD | Card + Google Pay | EN, KA |
| GOOGLE_PAY | Google Pay only | EN, KA |
{
"paymentMethod": "APPLE_CARD",
"language": "EN",
"saveCard": false
}05 · REDIRECT
Send the customer to the payment page
Always follow redirectUrl, redirectMethod and redirectParams from the response. The response is the same for card, Apple Pay and Google Pay. If redirectMethod is GET, send the browser to redirectUrl with the params in the query string.
{
"success": true,
"code": "PAYMENT_PAGE_CREATED",
"paymentId": "GATEWAY_PAYMENT_ID",
"merchantPaymentId": "MERCHANT_PAYMENT_ID-100001",
"gatewayTransactionId": "GATEWAY_TRANSACTION_ID",
"reference": "ORDER-100001",
"amount": "1.00",
"currency": "GEL",
"redirectUrl": "HOSTED_PAYMENT_PAGE_URL",
"redirectMethod": "POST",
"redirectParams": {
"trans_id": "GATEWAY_TRANSACTION_ID"
},
"resultUrl": "MERCHANT_RESULT_URL",
"resultDeliveryMethod": "POST",
"message": "Payment page created"
}<form id="gatewayRedirect" method="POST"
action="HOSTED_PAYMENT_PAGE_URL">
<input type="hidden" name="trans_id"
value="GATEWAY_TRANSACTION_ID">
</form>
<script>
document.getElementById('gatewayRedirect').submit();
</script>Ready to test your integration?
Use sandbox credentials and synthetic test cards, then pass the mandatory test plan before going live.