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
signature	String(max:750)	M	RSA-MD5 signature. See Signature

M = Mandatory, O = Optional

---

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.