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.

POST /cgi-bin/paymentinit.cgi · 200
{
  "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.

  1. STEP 01

    Create payment

    Your backend calls paymentinit.cgi with the order.

  2. STEP 02

    Redirect

    Send the customer to the hosted payment page.

  3. STEP 03

    Result URL

    The browser returns to your result URL with the verified result.

  4. STEP 04

    Status check

    Reconcile with paymentstatuscheck.cgi before fulfilment.

Placeholders used in examples

PlaceholderDescription
BASEURLGateway base address for the environment, for example BASEURL/cgi-bin/paymentinit.cgi.
MERCHANT_IDMerchant identifier issued by the gateway.
API_KEYPublic API key issued to the merchant for the selected environment.
API_SECRETSecret key the merchant backend uses to sign requests. Never expose it in browser JavaScript.
MERCHANT_PAYMENT_IDYour unique payment or order identifier. Must be unique per merchant.
MERCHANT_RESULT_URLYour 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.

HeaderRequiredValue
X-Merchant-IdYesMERCHANT_ID
X-Api-KeyYesAPI_KEY
X-TimestampYesUnix timestamp in seconds, UTC.
X-NonceYesUnique random value per request. Recommended: at least 16 bytes, hex.
X-SignatureYesBase64 HMAC-SHA256 signature calculated with API_SECRET.
Content-TypeFor POSTapplication/json
AcceptRecommendedapplication/json
Canonical string and signature
# 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
e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855
Keep API_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.

FieldDescription
merchantPaymentIdstring · requiredYour unique payment ID for reconciliation and status lookup.
referencestring · requiredHuman-readable order reference. Recommended: the order number.
amountstring · requiredDecimal amount with two digits, for example "1.00".
currencystring · requiredISO currency code, for example GEL.
resultUrlstring · requiredYour return address: MERCHANT_RESULT_URL.
descriptionstring · recommendedText shown on the payment page, if supported.
languagestring · recommendedCard: EN or KA. Apple Pay: EN, KA or RU. Google Pay: EN or KA.
paymentMethodstring · optionalPayment page mode. CARD if omitted.
resultDeliveryMethodstring · optionalPOST or GET. Recommended: POST.
saveCardboolean · optionaltrue only with an enabled card-tokenization agreement.
bankCodestring · optionalPreferred bank group. If omitted, the gateway routes the payment.
bankNodeIdstring · optionalProcessing node, if agreed for your merchant.
metadataobject · optionalYour non-sensitive values. Never card or wallet data.
Request · cURL
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.

paymentMethodPayment pageLanguages
CARDStandard card payment pageEN, KA
APPLE_CARDCard + Apple PayEN, KA, RU
APPLE_PAYApple Pay onlyEN, KA, RU
GOOGLE_CARDCard + Google PayEN, KA
GOOGLE_PAYGoogle Pay onlyEN, KA
Card + Apple Pay · changed fields
{
  "paymentMethod": "APPLE_CARD",
  "language": "EN",
  "saveCard": false
}
You never send Apple Pay or Google Pay tokens, PAN, expiry, CVV or 3DS passwords. The customer authorizes the payment on the hosted page.

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.

Response · 200
{
  "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"
}
redirectMethod = POST · auto-submit form
<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.