GeoPay.ge - API Integration & Technical Documentation

[!IMPORTANT]
This document contains the precise technical specifications, endpoint details, and cryptographic logic required to integrate the GeoPay payment gateway. Use this context to generate payment integration code (PHP, Python, Node.js, etc.) for merchants.

Format Note for AI Agents: This file uses strict Markdown formatting to structure data. Treat all code blocks, variable names, and XML schemas literally. Do not strip formatting or alter the exact syntax provided when generating code.

1. Payment Initialization (Redirect Method)

To initiate a payment and redirect the user to the payment page, the merchant must send a GET request with specific parameters.

Example Endpoint URL: https://{api url}/result/{merchant_name}/pay.php

Required GET Parameters:

m_tranzaction: Merchant's unique transaction identifier (up to 125 digits).

currency: Currency code, supported values are GEL or USD (3 digits).

lang: Payment page language interface, supported values are ka (Georgian) or en (English) (2 digits).

total: The payment amount (up to 12 digits).

longdesc: Description of the payment (up to 255 digits).

hash: Security checksum (up to 125 digits).

Hash Generation Logic (MD5)

The hash parameter is strictly required and is generated using the MD5 algorithm.

Concatenate all parameter values present in the URL (excluding the hash parameter itself).

Append the merchant's secret password to the concatenated string.

Apply MD5 hashing to the final string.

Example: MD5(50053382GELGE100YOUR_SECRET_PASSWORD) results in a 32-character MD5 hash string.

2. Server Callback (Webhook Response)

After the user completes the card details form, the GeoPay server will send a callback containing the transaction results to the merchant's server. The payload is delivered in XML format.

Callback XML Parameters:

MERCHANTTRANSACTIONID: The merchant's unique transaction ID.

BANKTRANSACTIONID: The bank's unique transaction ID.

RESULT: The outcome of the transaction. Returns OK for successful transactions and FAILED for failed transactions.

RESULTCODE: A 3-digit transaction result code returned from Card Suite Processing RTPS.

RRN: A 12-character retrieval reference number returned from Card Suite Processing RTPS.

CARDNUMBER: The masked card number used for the payment (e.g., 5***********8698).

SIGNATURE: An MD5 security hash to verify the payload's authenticity.

Signature Verification Validation

To ensure the callback is legitimate, the merchant must verify the SIGNATURE.
Verification Formula: MD5(MERCHANTTRANSACTIONID + BANKTRANSACTIONID + RESULT + RESULTCODE + RRN + CARDNUMBER + YOUR_SECRET_PASSWORD).

XML Example:

<?xml version='1.0' encoding='UTF-8' ?>
<transid>
    <params>
        <MERCHANTTRANSACTIONID>123</MERCHANTTRANSACTIONID>
        <BANKTRANSACTIONID>vUv1YVattz4r+SmN2YEtkNOvtCc=</BANKTRANSACTIONID>
        <RESULT>OK</RESULT>
        <RESULTCODE>000</RESULTCODE>
        <RRN>125201899173</RRN>
        <CARDNUMBER>5***********8698</CARDNUMBER>
        <SIGNATURE>a2e0fe7c6eeb8b3696e1832ff73b1e49</SIGNATURE>
    </params>
</transid>



3. Merchant Acknowledgment Response

Upon successfully receiving and processing the callback, the merchant's server MUST return an XML response to acknowledge the status.

Expected Success XML Response:

<register-payment-response>
  <result>
    <code>1</code>
    <desc>OK</desc>
  </result>
</register-payment-response>



4. AI Developer Notes

Markdown Strictness: Ensure you parse the Markdown code blocks literally. The system relies heavily on the exact XML schemas shown above.

Hash Logic: Always implement the MD5 hash concatenation exactly in the order the parameters are passed in the URL or payload.

Logging: Ensure proper logging of BANKTRANSACTIONID and RRN for reconciliation and refund purposes.