IPN Notifications

GLODIPAY delivers real-time payment results to your server via Instant Payment Notification (IPN) — an HTTP POST to the notificationUrl you provided when creating the transaction.

Method: POST
Content-Type: application/json

Retry policy: If your server does not respond with {"returnCode":"100"} within 30 seconds, GLODIPAY will retry delivery. Your handler should be idempotent — the same notification may be delivered more than once.

What triggers an IPN: Any transition to a terminal or significant state: successful, failed, error, refund_successful, refund_failed, void_successful, etc.

---

Payload Fields

Field	Type	Required	Description
merchantId	String	M	Merchant's ID
transactionId	String	M	GLODIPAY transaction ID (ULID)
transactionNumber	String	M	GLODIPAY human-readable transaction number
ref	String	M	Merchant's orderRef
currency	String	M	ISO 4217 currency code
amount	Float	M	Invoice amount
paidAmount	Float	O	Amount actually charged to the buyer (including buyer fees)
settlementAmount	Float	O	Amount to be settled to the merchant
estimationSettlementAt	ISO 8601 datetime	O	Estimated settlement datetime
fees	JSON	O	Fee breakdown. See fees object below
status	String	M	Transaction status. See Status Values
statusCode	Number	M	Numeric status code. See Status Codes
metadata	JSON	O	Key-value pairs from the original checkout session
transactionDocuments	JSON	O	Supporting documents from the original session
paymentMethodDetails	JSON	O	Payment method used. See paymentMethodDetails object below
message	String	O	Human-readable status message
descriptor	String	O	Transaction descriptor
transactionCreatedAt	ISO 8601 datetime	M	Transaction creation time in GLODIPAY system
originalTransactionCreatedAt	ISO 8601 datetime	M	Transaction creation time at the PSP
signature	String	M	RSA-MD5 signature — verify with RSA Public Key. See Signature

---

fees Object

Field	Type	Description
buyer	Float	Buyer-facing fee amount
seller	Float	Merchant fee amount
rolling	Float	Rolling reserve amount
operate	Float	Total operating fees (processor + GLODIPAY + partner)
estimationRollingReleaseAt	ISO 8601 datetime	Estimated rolling reserve release datetime

---

paymentMethodDetails Object

Field	Type	Description
displayName	String	Payment method label shown to the buyer
group	String	Payment method group type
family	String	Payment method family type
type	String	Payment method type (e.g. card, wallet)
{type}	JSON	Optional. Payment method-specific details. The key equals the type value. Currently only present for card payments when card details are available. See card object below

card Object (paymentMethodDetails.card)

Field	Description
name	Cardholder name
firstSixDigits	First 6 digits of the card number (BIN)
lastFourDigits	Last 4 digits of the card number
expiryMonth	Expiry month (MM)
expiryYear	Expiry year (YY)
type	Card brand (visa, mastercard, amex, jcb, etc.)
issuer	Issuing bank name (provider-dependent)
issuerCountryCode	ISO 3166-1 alpha-2 country code of the issuing bank (provider-dependent)
funding	Card funding type: credit, debit, or prepaid (provider-dependent)
authorizationCode	Authorization code from the issuer (provider-dependent)
clientIP	Customer IP address at the time of payment (provider-dependent)
checks	AVS/CVC verification results object (provider-dependent)
threeDSecure	3D Secure authentication details object (provider-dependent)

checks object fields (when present):

Field	Description
addressLine1Check	AVS address line 1 check result
addressPostalCodeCheck	AVS postal code check result
cvcCheck	CVC/CVV check result

threeDSecure object fields (when present):

Field	Description
authFlow	Authentication flow used
eci	Electronic Commerce Indicator
result	3DS authentication result
version	3DS protocol version

---

Example IPN Payload (Successful Card Payment)

{
  "merchantId": "1100000123",
  "transactionId": "01jza90dy6w82dfrrqvadn5vs4",
  "transactionNumber": "2604-1713100800",
  "ref": "ORDER-001",
  "currency": "USD",
  "amount": 100.00,
  "paidAmount": 105.00,
  "settlementAmount": 95.00,
  "estimationSettlementAt": "2026-04-16T00:00:00+00:00",
  "fees": {
    "buyer": 5.00,
    "seller": 5.00,
    "rolling": 2.00,
    "operate": 3.00,
    "estimationRollingReleaseAt": "2026-05-14T00:00:00+00:00"
  },
  "status": "successful",
  "statusCode": 6,
  "paymentMethodDetails": {
    "displayName": "Credit / Debit Card",
    "group": "card",
    "family": "card",
    "type": "card",
    "card": {
      "name": "John Doe",
      "firstSixDigits": "411111",
      "lastFourDigits": "1111",
      "expiryMonth": "01",
      "expiryYear": "30",
      "type": "visa",
      "issuer": "Example Bank",
      "issuerCountryCode": "US",
      "funding": "credit",
      "authorizationCode": "ABC123"
    }
  },
  "metadata": { "orderId": "12345" },
  "message": null,
  "descriptor": "GLODIPAY*ORDER-001",
  "transactionCreatedAt": "2026-04-14T10:00:00+00:00",
  "originalTransactionCreatedAt": "2026-04-14T10:00:01+00:00",
  "signature": "base64-encoded-rsa-signature"
}

---

Acknowledgement Response

Your server must respond with the following JSON within 30 seconds. Any other response or a timeout is treated as a delivery failure and GLODIPAY will retry.

{
  "returnCode": "100",
  "description": "Received"
}

Field	Type	Required	Description
returnCode	String	M	Must be "100" to acknowledge receipt
description	String(max:1500)	O	Optional description

---

Refund IPN

Refund notifications use the same notificationUrl as the original transaction. The payload format differs — see Refund API for the refund-specific IPN payload fields.