Server-to-Server Card API

Ask AI

Submit card details directly from your server to charge the buyer without redirecting them to an external payment page.

Endpoint: POST /v2/card/api Content-Type: application/json

This endpoint requires PCI DSS compliance on your server, as raw card data passes through your systems.

---

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
cardNumber	String(12–19)	M	Card number. E.g. 4111111111111111
cardMonth	String	M	Expiry month. E.g. 12
cardYear	String	M	Expiry year (2-digit). E.g. 30
cardSecurityCode	String(3–4)	M	CVV / CVC. E.g. 123
billingFirstName	String(max:255)	M	Billing first name. E.g. John
billingLastName	String(max:255)	M	Billing last name. E.g. Doe
billingEmail	String(max:255)	M	Buyer email address. E.g. john.doe@example.com
billingStreet1	String(max:255)	M	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)	M	Billing city. E.g. New York
billingState	String(2–255)	C	Billing state / province. Required when billingCountry is US or CA. E.g. NY
billingCountry	String	M	ISO 3166-1 alpha-2 country code. E.g. US. See Country Codes
billingPostalCode	String(max:25)	M	Postal / ZIP code. E.g. 10001
billingPhoneCountryCode	String(max:10)	O	Phone country code. E.g. 1 for US
billingPhoneNumber	String(max:30)	M	Phone number. E.g. 5551234567
customerIp	String	M	IP address of the customer. E.g. 203.0.113.42
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
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
browserDetails	JSON	M	Browser fingerprint. See browserDetails Object
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, C = Conditional

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
websiteUrl	callbackUrl — its host is what the allowed-domain check validates
expiresAt	No effect on this endpoint. It is accepted and validated, but S2S has no hosted page to expire
metadata, transactionDocuments	Absent — nothing extra is added to the IPN or query response
billingStreet2, billingPhoneCountryCode	Empty. billingPhoneCountryCode becomes mandatory when your processor is SmartPay or a hosted-page (HPP) processor
browserDetails optional keys	Omitted — no substitute value is generated. Sending them improves the approval rate

---

browserDetails Object

Required on every S2S card request. Can be submitted as a JSON object (nested) or a JSON-encoded string. Keys are snake_case as listed below; camelCase keys are accepted and normalized.

Field	Type	Required	Description
accept_header	String	M	Browser Accept header
screen_width	String	M	Screen width in pixels
screen_height	String	M	Screen height in pixels
screen_color_depth	String	M	Screen color depth in bits
window_width	String	M	Viewport width in pixels
window_height	String	M	Viewport height in pixels
language	String	M	Browser language. E.g. en-US
java_enabled	String	M	"true" or "false"
user_agent	String	M	Browser user agent string
time_zone	String	M	UTC offset in hours. E.g. 7 for UTC+7
time_zone_name	String	M	IANA timezone name. E.g. Asia/Ho_Chi_Minh
languages	Array<String>	O	Ordered list of browser preferred languages. E.g. ["vi-VN", "en-US", "en"]
platform	String(max:255)	O	Browser platform identifier. E.g. Win32, MacIntel, Linux x86_64
cookieEnabled	Boolean	O	Indicates whether cookies are enabled in the browser
online	Boolean	O	Indicates whether the browser reports an active network connection
hardwareConcurrency	Integer	O	Number of logical CPU cores available to the browser. E.g. 8, 16
deviceMemory	Number	O	Approximate device memory in GB reported by the browser. E.g. 4, 8, 16. May be unavailable on some browsers
availWidth	Integer	O	Available screen width excluding OS UI elements such as taskbars and docks
availHeight	Integer	O	Available screen height excluding OS UI elements such as taskbars and docks
currentUrl	String(max:2048)	O	Full URL of the page where the payment request originated
hostname	String(max:255)	O	Hostname (domain) of the current page. E.g. example.com

JavaScript snippet:

document.addEventListener('DOMContentLoaded', () => {
  const browserDetails = {
    accept_header: "{{ request()->header('Accept', 'text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8') }}",
    screen_width: window.screen.width.toString(),
    screen_height: window.screen.height.toString(),
    screen_color_depth: window.screen.colorDepth.toString(),
    window_width: String(window.innerWidth || document.documentElement.clientWidth || screen.width),
    window_height: String(window.innerHeight || document.documentElement.clientHeight || screen.height),
    language: navigator.language,
    java_enabled: 'false',
    user_agent: navigator.userAgent,
    time_zone: String(-new Date().getTimezoneOffset() / 60),
    time_zone_name: Intl.DateTimeFormat().resolvedOptions().timeZone

    // ── Recommended fields (improves approval rate) 
    languages: navigator.languages,
    platform: navigator.platform,
    cookieEnabled: navigator.cookieEnabled,
    online: navigator.onLine,
    hardwareConcurrency: navigator.hardwareConcurrency,
    deviceMemory: navigator.deviceMemory || "N/A",
    availWidth: screen.availWidth,
    availHeight: screen.availHeight,
    currentUrl: location.href,
    hostname: location.hostname,
  };

  document.getElementById('browserDetails').value = JSON.stringify(browserDetails, null, 2);
});

---

Response

All responses from this endpoint are wrapped by the gateway:

{ "status": "...", "message": "...", "data": { ... } }

Success (no 3DS required)

{
  "status": "success",
  "message": "The transaction has been successfully completed.",
  "data": {
    "transactionId": "01jwz13qfcx4z61ded3jcj0tf2"
  }
}

3DS Authentication Required

{
  "status": "redirect",
  "message": "Please redirect the user to complete the payment.",
  "data": {
    "transactionId": "01jwz0ty1640apxvmyzqpvc18a",
    "url": "https://payment.gpayprocessing.com/card/3ds/01jwz0ty1640apxvmyzqpvc18a"
  }
}

Redirect the buyer to data.url to complete 3DS. After verification, GLODIPAY processes the transaction and sends the result via IPN to notificationUrl and redirects the buyer to callbackUrl.

Pending

{
  "status": "pending",
  "message": "pending",
  "data": {
    "transactionId": "01jwz0ty1640apxvmyzqpvc18a"
  }
}

Validation Error (HTTP 422)

{
  "status": "error",
  "message": "Invalid request data.",
  "errors": [
    {
      "field": "billingEmail",
      "message": ["The billing email field is required."]
    }
  ]
}

Processing Error (HTTP 400/500)

{
  "status": "error",
  "message": "No payment provider could process this transaction. Please try again or contact support.",
  "data": {
    "transactionId": "01jwz0ty1640apxvmyzqpvc18a"
  }
}

No S2S Provider Configured (HTTP 422)

Returned when the merchant's account only has hosted-page (HPP) processors configured — this endpoint requires a direct server-to-server processor. Note the shape differs from the other errors above: transactionId sits at the top level (always null), not nested in data, and there is no errors array.

{
  "status": "error",
  "transactionId": null,
  "message": "No S2S payment service provider is configured for your merchant. Please contact support."
}

Contact support to have an S2S-capable processor added to the account, or use the Checkout API / iframe instead, which support HPP processors.

---

Auto-Cascade

When enabled, the gateway automatically retries failed charges across multiple providers. Only the final outcome is returned.

---

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