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

Signature 2.1: the body is {"signVersion": "2.1", "payload": "<JSON string>", "signature": "<base64>"}. Verify signature against the payload string with the GLODIPAY RSA Public Key, then parse payload — it contains the fields below. Accounts still on 2.0 receive the fields flat, with signature among them. See Signature.

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: only the statuses listed in Statuses that trigger an IPN.

---

Statuses that trigger an IPN

Payment

status	Sent when
successful	The payment is completed. Sent once per transaction.
under_review	Funds were received but need review — for example the amount paid differs from the order amount, or the processor reports the payment as pending. A later successful IPN may follow; failed will not.
failed	The payment failed. Not sent if the transaction has already been successful or under_review.

Refund and void

status	Sent when
refund_initiated	A refund is created — through the Refund API, by the processor, or as part of a chargeback.
refund_under_review	The processor reports the refund as pending (some processors only).
refund_successful	The refund completed and covers the full paid amount.
refund_partially_successful	The refund completed for part of the paid amount.
refund_failed	The refund failed or was rejected.
refund_partially_failed	A partial refund failed.
void_initiated, void_under_review, void_successful, void_partially_successful, void_failed, void_partially_failed	Same as the refund_* values, when the refund is processed as a void (same-day refund on accounts with void enabled).

Never sent

incomplete, pending, processed, expired, error, canceled, rejected, released, documents_uploaded, chargeback_alert, chargebacked and dispute are never sent as IPNs. Use Query Transaction to read them.

A chargeback is reported through the refund IPNs: refund_initiated (if no refund exists yet), then refund_successful or refund_partially_successful for the charged-back amount.

---

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	2.0 only — on 2.1 the signature is sent next to payload. 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"
}

2.1 accounts receive these fields as a JSON string in payload, alongside signVersion and signature; 2.0 accounts receive them flat with signature. See 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.