Integration

iFrame Checkout Integration

Embed Cloud9's hosted checkout form in your application via iFrame. No PCI scope for card data — Cloud9 handles collection, tokenization, and processing.

1. Request Fields

Field	Description
`WebGMID`	SHA256 hash of the real GMID (uppercase hex). Protects the real GMID from client-side exposure. C9PG looks up the real GMID using the GTID and validates the hash.
`Seed`	Transaction integrity token. Generated server-side as: `SHA256(InvoiceNum:WebGMID:GTID:SeedTime:GMPW)` hex uppercase. Valid for 5 minutes.
`SeedTime`	Seed generation timestamp in UTC. Format: `DD-MM-YYYY:HH:MM:SS:SSS`
`AcceptPaymentList`	Payment methods to accept: `ACH`, `GPay`, `ApplePay`, `Card`. Comma-separate multiple values or use `All` (default).
`Template`	CSS template name. Send your custom CSS to Cloud9 in advance, then reference it here.
`GTID`	Cloud9 Gateway Terminal ID.
`InvoiceNum`	Invoice number (optional).
`CallbackUrl`	Your backend server URL to receive the authorization response.
`UICallbackUrl`	URL to redirect the iFrame after the transaction completes (optional).
`CallbackContext`	Merchant-defined tracing value. Returned in both the iFrame and server callback responses.
`MerchantName`	Display name shown in Google Pay and Apple Pay prompts.

Security — The GMPW (Gateway Merchant Password) is the key field for seed validation. Never include it in the request or send it to the browser. Update it regularly through the portal.

WebGMID Generation

Backend (real GMID)

"GMID": "2001008149"

Browser (hashed WebGMID)

"WebGMID": "4FDB4707CB8A821C49ED19B0F2F26C6FF7D6572057C8EB5A8492E9763CB3E3DD"

Seed Generation

Server-side formula

SHA256(InvoiceNum:WebGMID:GTID:SeedTime:GMPW) → hex uppercase

2. iFrame Response Fields

Field	Description
`Status`	Set to `success` only if the CallbackUrl call is successful.
`CallbackContext`	The merchant trace value from the original request.
`CallbackVersion`	Response delivery mode: `0.1` — iFrame redirects to CallbackUrl with the response (default) `1.0` — Cloud9 backend sends the response to your CallbackUrl API `2.0` — iFrame posts the response to the parent window
`KeyIndex`	RSA encryption key index, provided by Cloud9.

3. RSA Encryption

Cloud9 provides a public key and KeyIndex for encrypting sensitive parameters (e.g. GTID) before transmission. Encrypted values are sent base64-encoded.

Environment	Key Length
QA / Test	1024-bit
Production	2048-bit

Encryption Parameters

Public Key: Base64-encoded
Padding: RSA_PKCS1_OAEP_PADDING

4. Integration Flow

Browser JS

Merchant Backend

Cloud9 iFrame

Cloud9 Gateway

Browser → Backend: Client sign-in
Backend → Browser: Successful auth
Backend: Generate Seed using GMPW — SHA256(InvoiceNum:WebGMID:GTID:SeedTime:GMPW)
Backend → Browser: Return Seed, WebGMID, GTID, SeedTime, InvoiceNum
Browser → iFrame: Load Cloud9 iFrame with all parameters
iFrame → Gateway: Send transaction to Cloud9
Gateway → Backend: Send response to CallbackUrl with CallbackContext
Gateway → iFrame: Return callback status
iFrame → Browser: Redirect to UICallbackUrl with Status

5. Examples

5.1 iFrame Request

Basic request URL

https://testvterm.c9pg.com/checkout?
  AcceptPaymentList=All
  &WebGMID=4FDB4707CB8A821C...CB3E3DD
  &SeedTime=12-08-2023:12:32:11:023
  &InvoiceNum=IN1234
  &Seed=D1A39C95730BA975...30C8A9
  &GTID=GT1001396406
  &CallbackUrl=https://yoursite.com/callback
  &UICallbackUrl=https://yoursite.com/result
  &CallbackContext=eyJhY3Rpb24iOiJ0aWNrZXRQYXltZW50In0

5.2 UICallbackUrl Response

Redirect after transaction

https://yoursite.com/result?
  CallbackContext=eyJhY3Rpb24iOiJ0aWNrZXRQYXltZW50In0
  &Status=success

5.3 CallbackUrl Payload

Server-to-server POST from Cloud9

curl --location 'https://yoursite.com/callback' \
  --header 'Content-Type: application/json' \
  --data '{
    "AccountNum": "411111******1111",
    "AuthAmt": "100",
    "AuthDate": "20230925",
    "AuthTime": "121344",
    "Brand": "Visa",
    "ErrorCode": "000",
    "ExpDate": "1223",
    "GMID": "2001008149",
    "GTID": "GT1001396406",
    "MainAmt": "100",
    "Medium": "Credit",
    "ResponseCode": "00",
    "ResponseText": "Approved",
    "ResultCode": "000",
    "ResultText": "Approved",
    "Status": "success",
    "TipAmt": "0",
    "TransType": "Auth",
    "CallbackContext": "eyJhY3Rpb24iOiJ0aWNrZXRQYXltZW50In0"
  }'

← API Guide Payment Device Controller →