Checkout API

Ask AI

Create a checkout session that redirects your buyer to a GLODIPAY-hosted payment page, or returns a shareable payment link.

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

---

Request Parameters

Field	Type	Required	Description
merchantId	String(1–50)	M	Merchant's ID. E.g. 1100000123
orderRef	String(1–250)	M	Unique transaction reference per merchant. E.g. ORDER-2026-001
amount	Float	M	Invoice amount. Minimum: 1. Up to 2 decimal places. E.g. 100.00
currency	String(3)	M	ISO 4217 currency code. E.g. USD
paymentMethod	String	M	Payment method(s) to display. E.g. checkout. See Payment Methods
callbackUrl	String(1–300)	M	Redirect URL after successful payment. Must be https. E.g. https://yoursite.com/return. See Callback URL
notificationUrl	String(1–300)	M	Your server endpoint for IPN webhooks. Must be https. E.g. https://yoursite.com/webhook
cancelUrl	String(1–300)	M	Redirect URL on cancellation. Must be https. E.g. https://yoursite.com/cancel
errorUrl	String(1–300)	M	Redirect URL on error. Must be https. E.g. https://yoursite.com/error
connectionMode	String	O	API (Default) or DIRECT_POST. See Connection Modes
orderDescription	String(max:3000)	M	Short description shown on the checkout screen. E.g. Order #2026-001
metadata	JSON	O	Key-value pairs returned in IPN and query responses. E.g. {"orderId":"12345"}
transactionDocuments	JSON	O	Supporting documents for the transaction. E.g. [{"type":"invoice","url":"https://yoursite.com/inv.pdf"}]
paymentFilter	JSON	O	Array of payment method types to exclude from the session. E.g. ["card"]
paymentSorter	JSON	O	Ordered array to control display order. E.g. ["checkout","card"]
feeBySeller	Number(0–100)	O	% of processing fee paid by merchant. 0 = buyer pays 100%. E.g. 50
billingFirstName	String(max:255)	O	Billing first name. E.g. John
billingLastName	String(max:255)	O	Billing last name. E.g. Doe
billingEmail	String(max:255)	O	Buyer email address. E.g. john.doe@example.com
billingStreet1	String(max:255)	O	Billing street address line 1. E.g. 123 Main St
billingStreet2	String(max:255)	O	Billing street address line 2. E.g. Suite 4B
billingCity	String(max:255)	O	Billing city. E.g. New York
billingState	String(2–255)	O	Billing state / province. E.g. NY
billingCountry	String	O	ISO 3166-1 alpha-2 country code. E.g. US. See Country Codes
billingPostalCode	String(max:25)	O	Postal / ZIP code. E.g. 10001
billingPhoneCountryCode	String(max:10)	O	Phone country code. E.g. 1 for US
billingPhoneNumber	String(max:20)	O	Phone number. E.g. 5551234567
brandName	String(1–255)	O	Override brand name on the hosted checkout screen. E.g. My Store
colorMode	String(1–255)	O	Up to 3 colors separated by ---. Accepts color names, HEX, or RGBA. E.g. #2e7d32---#e8f5e9---#81c784
logoSource	String(1–255)	O	Override the logo on the hosted checkout screen. E.g. https://yoursite.com/logo.png
customerIp	String	O	IP address of the customer. E.g. 203.0.113.42
websiteUrl	String(max:300)	O	Merchant website URL. E.g. https://yoursite.com
expiresAt	String	O	Session expiry in ISO 8601 format. Default: 24 hours. E.g. 2026-04-22T10:00:00+00:00
signature	String(max:750)	M	RSA-MD5 signature. See Signature

M = Mandatory, O = Optional

---

Response

connectionMode: API

Field	Type	Description
status	String	created on success, error on failure
transactionId	String (ULID)	GLODIPAY transaction ID
paymentLink	String	Signed URL — redirect the buyer to this URL to complete payment
message	String	Human-readable message

Success:

{
  "status": "created",
  "transactionId": "01jza90dy6w82dfrrqvadn5vs4",
  "paymentLink": "https://payment.gpayprocessing.com/v2/checkout/01jza90dy6w82dfrrqvadn5vs4?...",
  "message": "Payment Link created successfully"
}

Error:

{
  "status": "error",
  "transactionId": null,
  "paymentLink": null,
  "message": "No active payment service providers found. Please contact support."
}

connectionMode: DIRECT_POST

The buyer's browser is redirected directly to the GLODIPAY-hosted checkout page. No JSON response is returned to your server.

---

Callback URL

After payment, GLODIPAY performs a GET redirect to your callbackUrl with a payload query parameter:

GET {callbackUrl}?payload={base64-encoded-json}

Decoded payload fields:

Field	Type	Description
status	String	Final transaction status. See Status Values
transactionId	String	GLODIPAY transaction ID
ref	String	Merchant's orderRef
amount	Float	Invoice amount
currency	String	Currency code
signature	String	RSA-MD5 signature — verify with RSA Public Key

Always verify the signature in the callback payload before trusting the status. Use the Transaction Query endpoint to get complete payment details.

---

IPN Notification

GLODIPAY posts a payment result to your notificationUrl when the transaction reaches a terminal state. See IPN Notifications for the full payload and acknowledgement format.

---

Transaction Query

Use POST /v2/checkout/query to check the status of a transaction at any time. See Transaction Query.

---

Source

This page is derived from GLODIPAY_Checkout_API_Specification_v2.