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
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

M = Mandatory, O = Optional

Defaults for optional fields

What the gateway applies when the field is omitted.

Field	Default when omitted
connectionMode	API when the request is sent with Content-Type: application/json, DIRECT_POST for a form post
feeBySeller	The Fee by seller percentage configured for your merchant account in the Portal. The buyer's share is 100 − feeBySeller
expiresAt	24 hours after the request
websiteUrl	callbackUrl — its host is what the allowed-domain check validates
brandName	Your company name as registered in the Portal
logoSource	Your merchant logo as uploaded in the Portal
colorMode	The default GLODIPAY theme
customerIp	The IP of the incoming request — with connectionMode: API that is your server's IP, so send customerIp explicitly if geo routing matters. The buyer's real IP is recorded when they open the checkout page
paymentFilter	[] — no payment method is excluded
paymentSorter	[] — methods keep the order configured for your merchant account
metadata, transactionDocuments	Absent — nothing extra is added to the IPN or query response
billing* fields	Empty — the buyer fills them in on the checkout page

---

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

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.