🔒

Restricted Documentation

Verifying authenticated session... Vendor API specifications are restricted to authorized Partners and Administrators.

Vendor Payment Integration API

Comprehensive developer documentation for external merchants, platforms, and partners (Singapore & Global) integrating with the Sogdo Payment Gateway.

⚡ Zero PCI Burden (Hosted Checkout) 🔒 256-Bit SSL Encrypted 🌐 Multi-Tenant Vendor Support 💳 UPI · Cards · NetBanking · Wallets

1. Vendor Onboarding & Credentials

Before initiating payments, external vendors must be registered by the Sogdo Payment administrator (pay.sogdo.com) to receive their production credentials.

Credential Type Description & Usage
Client Code Identifier Your vendor client code (e.g. SINGAPORE_PORTAL_WEB).
Publishable Key (pk_...) Public Key Included in hosted checkout redirect links and client-side web requests. Safe for browser use.
Client Secret (sec_...) Private Secret Kept confidential on your server backend. Used to sign server-to-server HMAC requests and verify webhooks.
Allowed Origins URL Whitelist Your registered application domains (e.g. https://yourdomain.sg) permitted to trigger and receive redirects.

2. Hosted Checkout Integration (Recommended)

The hosted checkout flow provides an immediate, turn-key payment experience with zero compliance overhead. Customers are seamlessly redirected to https://pay.sogdo.com/checkout.html, where your branded order is presented and paid, after which the customer returns directly to your application.

Checkout Endpoint URL

https://pay.sogdo.com/checkout.html?pk={PUBLIC_KEY}&plan={PLAN_CODE}&amount={AMOUNT}&r={RETURN_URL}&email={EMAIL}&name={NAME}&ref={YOUR_ORDER_REF}

Query Parameters Specification

Parameter Requirement Description
pk (or publicKey) Required Your publishable API key (e.g. pk_live_...).
plan (or planCode) Required Plan code, package, or fee identifier configured for your account.
amount Optional Custom amount for open-amount plans (e.g. 499.00). Omit if plan has fixed catalogue pricing.
r (or returnUrl) Required Fully qualified callback URL on your site where customer is returned after payment (must match an Allowed Origin).
ref Optional Your platform's internal Order ID or invoice tracking number (e.g. ORD-SG-9012).
email Optional Customer email address for receipt and gateway prefill.
name Optional Customer full name.
phone Optional Customer mobile phone number for SMS payment updates.

Customer Return & Callback Parameters

When the transaction concludes, the customer's browser is automatically redirected to your returnUrl with these parameters:

https://yourdomain.sg/payment-complete?paid=true&orderRef=SOGDO-ORD-8F42B1&status=PAID
Parameter Values Meaning
paid "true" | "false" | "pending" Payment settlement indicator. Only fulfill orders when paid=true or confirmed via status API.
orderRef "SOGDO-ORD-..." Unique transaction reference ID generated by Sogdo Payment.
status "PAID" | "CANCELLED" | "PENDING" Final gateway status.

3. Server-to-Server Verification API

To guard against client-side tampering, your backend server should verify the order status using the public status endpoint or HMAC client API.

A. Public Status Verification Endpoint

GET https://pay.sogdo.com/api/v1/public/orders/{orderRef}/status Headers: X-Sogdo-Public-Key: {YOUR_PUBLIC_KEY}

Status Response Example

{ "orderRef": "SOGDO-ORD-8F42B1", "status": "PAID", "paid": true, "currency": "INR", "totalAmount": 499.00, "customerReference": "ORD-SG-9012", "paidAt": "2026-10-06T08:00:00Z" }

4. Code Examples (Vendor Integration)

// 1. Generate Checkout Redirect URL in Node.js function buildCheckoutUrl(order) { const baseUrl = "https://pay.sogdo.com/checkout.html"; const params = new URLSearchParams({ pk: process.env.SOGDO_PAY_PUBLIC_KEY, // e.g. "pk_live_xxx" plan: "STANDARD_ORDER", amount: order.amount.toFixed(2), ref: order.id, email: order.customerEmail, name: order.customerName, r: "https://yourdomain.sg/checkout/callback" }); return `${baseUrl}?${params.toString()}`; } // 2. Verify Return in Callback Route app.get("/checkout/callback", async (req, res) => { const { paid, orderRef, status } = req.query; if (paid === "true" && status === "PAID") { // Re-verify with Sogdo Payment API server-side const verify = await fetch(`https://pay.sogdo.com/api/v1/public/orders/${orderRef}/status`, { headers: { "X-Sogdo-Public-Key": process.env.SOGDO_PAY_PUBLIC_KEY } }).then(r => r.json()); if (verify.paid === true) { // Mark order as fulfilled in your database return res.render("payment-success", { orderRef }); } } res.render("payment-failed"); });
<?php // 1. Build redirect URL in PHP $publicKey = "pk_live_your_key"; $returnUrl = "https://yourdomain.sg/payment-callback.php"; $queryParams = http_build_query([ 'pk' => $publicKey, 'plan' => 'STANDARD_ORDER', 'amount' => '499.00', 'ref' => 'INV-SG-2026-001', 'email' => 'customer@client.sg', 'name' => 'Jane Doe', 'r' => $returnUrl ]); $checkoutUrl = "https://pay.sogdo.com/checkout.html?" . $queryParams; header("Location: " . $checkoutUrl); exit;
import urllib.parse import requests # 1. Build redirect URL params = { 'pk': 'pk_live_your_key', 'plan': 'STANDARD_ORDER', 'amount': '499.00', 'ref': 'ORD-SG-8821', 'email': 'customer@example.sg', 'r': 'https://yourdomain.sg/payment/return' } checkout_url = f"https://pay.sogdo.com/checkout.html?{urllib.parse.urlencode(params)}" # 2. Server-side verification def verify_order(order_ref, public_key): url = f"https://pay.sogdo.com/api/v1/public/orders/{order_ref}/status" headers = {"X-Sogdo-Public-Key": public_key} response = requests.get(url, headers=headers) data = response.json() return data.get("paid") is True
# Check order payment status via cURL: curl -X GET "https://pay.sogdo.com/api/v1/public/orders/SOGDO-ORD-8F42B1/status" \ -H "X-Sogdo-Public-Key: pk_live_your_key" \ -H "Accept: application/json"

5. Vendor Refund API (Customer Refund Request)

When an external vendor needs to refund a customer, you can submit a refund request via the API or your Vendor Portal. The refund request lands on the Sogdo Admin console, where the administrator reviews and processes it through our payment network to return the funds to the customer's bank account or UPI.

Endpoint Specification

POST https://pay.sogdo.com/api/v1/public/refunds/raise
Header / Parameter Type Description
X-Sogdo-Public-Key Header Your vendor publishable key (pk_...).
orderRef String (Body) The original Sogdo order reference (e.g. SOGDO-ORD-20261005-XXXXXX). Required.
amount Decimal (Body) Refund amount (optional; defaults to full order amount).
reason String (Body) Reason for customer refund (e.g. Customer requested refund / duplicate payment).

Refund Status Checking

GET https://pay.sogdo.com/api/v1/public/orders/{orderRef}/refunds

Returns refund status (PENDING_APPROVAL, REFUNDED, or REJECTED) and gateway refund reference.

6. Interactive Checkout URL Generator

Test and build your vendor checkout redirect URL in real time:

Generated Vendor Checkout URL:
https://pay.sogdo.com/checkout.html