v1.1API REFERENCE

Results and status

Receive the verified result on your site, check the final status and handle every outcome before you fulfil an order.

GET /cgi-bin/paymentstatuscheck.cgi · 200
{
  "success": true,
  "code": "PAYMENT_STATUS_CHECKED",
  "final": true,
  "paymentApproved": true,
  "status": "APPROVED",
  "merchantPaymentId": "MERCHANT_PAYMENT_ID-100001",
  "resultCode": "000",
  "resultCodeType": "APPROVAL",
  "maskedCardNumber": "411111******1111"
}

06 · RESULT URL

Result delivery to your site

After the hosted page, the gateway verifies the real status with the acquirer and returns the browser to your resultUrl. With POST, accept application/x-www-form-urlencoded fields; with GET, the same fields arrive as query parameters.

FieldMeaning
successtrue if the status is approved.
finaltrue if the acquirer status is final.
paymentApprovedtrue only for approved payments.
statusAPPROVED, DECLINED, PENDING, FAILED or UNKNOWN.
paymentIdGateway payment ID.
merchantPaymentIdYour payment ID from paymentinit.
gatewayTransactionIdAcquirer or gateway transaction ID.
referenceYour order reference.
amount · currencyPayment amount and currency.
resultCodeRaw acquirer or gateway result code.
resultCodeTypeAPPROVAL, DECLINE, ERROR or PENDING.
resultCodeDescriptionLocalized explanation for display or support.
rrn · approvalCodeBank references when supplied. Trust only with APPROVED.
maskedCardNumberMasked card number, if supplied.
messageCustomer or support message.
POST payload · approved
success=true
final=true
paymentApproved=true
status=APPROVED
paymentId=GATEWAY_PAYMENT_ID
merchantPaymentId=MERCHANT_PAYMENT_ID-100001
gatewayTransactionId=GATEWAY_TRANSACTION_ID
reference=ORDER-100001
amount=1.00
currency=GEL
gatewayResult=OK
resultCode=000
resultCodeType=APPROVAL
resultCodeDescription=Approved
rrn=618207038139
approvalCode=247651
maskedCardNumber=411111******1111
message=Approved
Do not treat the first browser return as final unless final=true. Use the status check for anything uncertain.

07 · PAYMENT STATUS

Check the payment status

GETBASEURL/cgi-bin/paymentstatuscheck.cgi

Use it whenever you need the current verified status. Query by one of: paymentId, merchantPaymentId or trans_id (gateway transaction ID).

Request · cURL
curl -X GET "BASEURL/cgi-bin/paymentstatuscheck.cgi?merchantPaymentId=MERCHANT_PAYMENT_ID-100001" \
  -H "Accept: application/json" \
  -H "X-Merchant-Id: MERCHANT_ID" \
  -H "X-Api-Key: API_KEY" \
  -H "X-Timestamp: 1780000011" \
  -H "X-Nonce: 413685e8fa6d4a0b9f9af7a4a602b0fb" \
  -H "X-Signature: SIGNATURE"
Response · APPROVED
{
  "success": true,
  "code": "PAYMENT_STATUS_CHECKED",
  "final": true,
  "paymentApproved": true,
  "status": "APPROVED",
  "merchantPaymentId": "MERCHANT_PAYMENT_ID-100001",
  "amount": "1.00",
  "currency": "GEL",
  "resultCode": "000",
  "resultCodeType": "APPROVAL",
  "requiresManualReview": false,
  "rrn": "618207038139",
  "approvalCode": "247651",
  "maskedCardNumber": "411111******1111"
}
Response · DECLINED
{
  "success": true,
  "final": true,
  "paymentApproved": false,
  "status": "DECLINED",
  "resultCode": "116",
  "resultCodeType": "DECLINE",
  "resultCodeDescription":
    "Decline, not sufficient funds",
  "maskedCardNumber": "400000******1166"
}
Response · PENDING
{
  "success": true,
  "final": false,
  "paymentApproved": false,
  "status": "PENDING",
  "resultCode": "PENDING",
  "resultCodeType": "PENDING",
  "resultCodeDescription":
    "Payment is not final yet"
}

08 · ERRORS

Error responses

HTTPCodeMeaningWhat to do
400BAD_REQUESTA required field is missing, or the paymentMethod or language is invalid.Fix the request. Use a supported method and language.
401AUTH_FAILEDMerchant authentication failed.Check MERCHANT_ID, API_KEY, timestamp, nonce and signature.
403SIGNATURE_INVALIDThe signature does not match the request.Recalculate the canonical string and HMAC.
404PAYMENT_NOT_FOUNDThe payment does not exist for this merchant.Check paymentId, merchantPaymentId or trans_id.
409DUPLICATE_MERCHANT_PAYMENT_IDmerchantPaymentId already exists.Do not reuse merchantPaymentId for a new order.
422AMOUNT_INVALIDThe amount or currency is invalid.Send a decimal string amount and a supported currency.
503STATUS_UNAVAILABLEThe acquirer status could not be verified for now.Retry the status check later.

09 · ORDER HANDLING

When to mark an order paid

Gateway statusYour order action
APPROVEDMark the order paid and continue fulfilment.
DECLINEDDo not fulfil. Show the decline message and allow another payment attempt.
PENDINGDo not fulfil. Poll the status check or wait for the result URL delivery.
FAILED UNKNOWNDo not fulfil. Show a support message and reconcile manually if needed.

Implementation rules

  • Generate a unique merchantPaymentId before paymentinit and store it with the order.
  • Store paymentId and gatewayTransactionId from the paymentinit response.
  • Send saveCard=false for APPLE_CARD, APPLE_PAY, GOOGLE_CARD and GOOGLE_PAY.
  • Use EN, KA or RU for Apple Pay modes and EN or KA for Google Pay modes.
  • Accept POST form fields or GET query parameters on your result URL.
  • Reconcile pending, interrupted or browser-closed payments with the status check.
  • Verify amount, currency, merchantPaymentId, reference and status before marking an order paid.
  • Never send card or wallet authorization data to paymentinit.cgi.

Ready to test your integration?

Use sandbox credentials and synthetic test cards, then pass the mandatory test plan before going live.