Refund API

Ask AI

Initiate refunds for completed transactions and query their status.

---

Initiate Refund

Endpoint: POST /v2/refund
Content-Type: application/json

Refunds can be full or partial (subject to per-provider constraints — some providers only support full-amount refunds). Refunds may be auto-processed immediately or held for manual approval, depending on merchant configuration.

The maximum refundable amount per refund is: paidAmount minus the total already refunded for the transaction.

Request

Field	Type	Required	Description
transactionId	String (ULID)	M	The transactionId from the IPN or transaction query. E.g. 01jza90dy6w82dfrrqvadn5vs4
amount	Float	M	Refund amount. Minimum: 0.10. Maximum: remaining refundable amount. E.g. 50.00
reason	String(max:1000)	O	Short description of the refund reason. Default when omitted: empty — no reason is stored. E.g. Customer request
signVersion	String	O	2.1: send the other fields as a JSON string in payload (see Signature). Omit to use the 2.0 rules.
signature	String(max:750)	M	RSA-MD5 signature. See Signature

Certain providers (PayAgency, SmartPay, ClisaPay, FinvyPay, WPay) only support full-amount refunds.

Response

All responses are wrapped:

Field	Type	Description
status	String	success or error
message	String	Human-readable message
data	JSON	Refund details. See data object below

data object:

Field	Type	Description
refundId	String (ULID)	GLODIPAY refund ID
refundNumber	String	GLODIPAY human-readable refund number

Auto-processed immediately:

{
  "status": "success",
  "message": null,
  "data": {
    "refundId": "01jzabk09xc4pbgwe8hyg4cwbf",
    "refundNumber": "2507-1751420414"
  }
}

Pending manual approval:

{
  "status": "success",
  "message": "Refund created and waiting for approval.",
  "data": {
    "refundId": "01jzabk09xc4pbgwe8hyg4cwbf",
    "refundNumber": "2507-1751420414"
  }
}

Validation error (HTTP 422):

{
  "status": "error",
  "message": "Invalid request data.",
  "errors": [
    {
      "field": "amount",
      "message": ["The amount must be between 0.1 and 100."]
    }
  ]
}

---

Query Refund Status

Endpoint: POST /v2/refund/query
Content-Type: application/json

Request

Field	Type	Required	Description
refundId	String (ULID)	M	GLODIPAY refund ID (from Refund API response or Refund IPN). E.g. 01jzabk09xc4pbgwe8hyg4cwbf
signVersion	String	O	2.1: send the other fields as a JSON string in payload (see Signature). Omit to use the 2.0 rules.
signature	String(max:750)	M	RSA-MD5 signature. See Signature

Response

Field	Type	Description
status	String	success
message	String	Human-readable message
data	JSON	Refund details object

data object fields:

Field	Type	Description
transactionId	String	GLODIPAY original transaction ID
ref	String	Merchant's orderRef
refundId	String	GLODIPAY refund ID
currency	String	ISO 4217 currency code
refundAmount	Float	Refund amount
status	String	Refund status. See Status Codes
statusCode	Number	Numeric status code. See Status Codes
metadata	JSON	Key-value pairs from the original session
reason	String	Refund reason
message	String	Human-readable status message
originalRefundCreatedAt	ISO 8601 datetime	Refund creation time at the PSP
refundCreatedAt	ISO 8601 datetime	Refund creation time in GLODIPAY system
transactionCreatedAt	ISO 8601 datetime	Original transaction creation time
signature	String	2.0 only — on 2.1 the signature is sent next to payload. See Signature

Example:

{
  "status": "success",
  "message": "",
  "data": {
    "transactionId": "01jza90dy6w82dfrrqvadn5vs4",
    "ref": "ORDER-001",
    "refundId": "01jzabk09xc4pbgwe8hyg4cwbf",
    "currency": "USD",
    "refundAmount": 50.00,
    "status": "refund_successful",
    "statusCode": 11,
    "metadata": { "orderId": "12345" },
    "reason": "Customer request",
    "message": null,
    "originalRefundCreatedAt": "2026-04-14T11:00:00+00:00",
    "refundCreatedAt": "2026-04-14T11:00:01+00:00",
    "transactionCreatedAt": "2026-04-14T10:00:00+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.

---

Refund IPN Notification

GLODIPAY sends an HTTP POST to the notificationUrl of the original transaction when a refund status changes.

Method: POST
Content-Type: application/json

Retry policy: If your server does not return {"returnCode":"100"} within 30 seconds, GLODIPAY will retry delivery.

Payload

Field	Type	Required	Description
transactionId	String	M	GLODIPAY original transaction ID
ref	String	M	Merchant's orderRef
refundId	String	M	GLODIPAY refund ID
currency	String	M	ISO 4217 currency code
refundAmount	Float	M	Refund amount
status	String	M	Refund status. See Status Codes
statusCode	Number	M	Numeric status code
metadata	JSON	O	Key-value pairs from the original session
reason	String	O	Refund reason
message	String	O	Human-readable status message
originalRefundCreatedAt	ISO 8601 datetime	M	Refund creation time at the PSP
refundCreatedAt	ISO 8601 datetime	M	Refund creation time in GLODIPAY system
transactionCreatedAt	ISO 8601 datetime	M	Original transaction creation time
signature	String	M	2.0 only — on 2.1 the signature is sent next to payload. See Signature

Example IPN Payload:

{
  "transactionId": "01jza90dy6w82dfrrqvadn5vs4",
  "ref": "ORDER-001",
  "refundId": "01jzabk09xc4pbgwe8hyg4cwbf",
  "currency": "USD",
  "refundAmount": 50.00,
  "status": "refund_successful",
  "statusCode": 11,
  "metadata": { "orderId": "12345" },
  "reason": "Customer request",
  "message": null,
  "originalRefundCreatedAt": "2026-04-14T11:00:00+00:00",
  "refundCreatedAt": "2026-04-14T11:00:01+00:00",
  "transactionCreatedAt": "2026-04-14T10:00:00+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

Your server must respond within 30 seconds:

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

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

---

Source

This page is derived from GLODIPAY_Refund_API_Specification_v2.