iFrame Card API

Ask AI

Create a session that returns a signed URL to a GLODIPAY-hosted card input form. Embed the URL in an <iframe> on your page — the buyer enters card details in the hosted form without leaving your site.

Endpoint: POST /v2/card/iframe 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	Must be card
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
billingEmail	String(max:255)	O	Buyer email address. E.g. john.doe@example.com
billingCountry	String	O	ISO 3166-1 alpha-2 country code. E.g. US. See Country Codes
billingFirstName	String(max:255)	O	Billing first name. E.g. John
billingLastName	String(max:255)	O	Billing last name. E.g. Doe
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
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
orderDescription	String(max:3000)	M	Short description of the order. 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"}]
feeBySeller	Number(0–100)	O	% of processing fee paid by merchant. 0 = buyer pays 100%. E.g. 50
brandName	String(1–255)	O	Override brand name on the card form. 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 card form. 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, paymentMethod	Forced to API and card — any value you send for these two is overridden
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, which for a server-side call is your server's IP. The buyer's real IP is recorded when the card form is loaded
metadata, transactionDocuments	Absent — nothing extra is added to the IPN or query response
billing* fields	Empty — when sent they only pre-fill the card form

---

Response

Field	Type	Description
status	String	created on success, error on failure
transactionId	String (ULID)	GLODIPAY transaction ID
url	String	Signed URL to the hosted card input form — embed in <iframe>
message	String	Human-readable message

Success:

{
  "status": "created",
  "transactionId": "01jza90dy6w82dfrrqvadn5vs4",
  "url": "https://payment.gpayprocessing.com/v2/card-iframe/01jza90dy6w82dfrrqvadn5vs4?...",
  "message": "Iframe card created successfully"
}

Error:

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

---

Embedding the iFrame

After receiving the url, embed it in your page:

<iframe
  src="{url}"
  width="100%"
  height="600"
  frameborder="0"
  scrolling="no"
  allowtransparency="true">
</iframe>

The URL is signed and expires at expiresAt. The buyer must complete payment within the session expiry time. Do not store or share the URL beyond the current checkout session.

---

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