# SGPayNowQR API — Full Reference > Generate EMVCo-compliant Singapore PayNow QR codes. Base URL: https://developers.sgpaynowqr.com/api/v1 --- ## Authentication All requests (except /health) require an API key in the X-API-Key header. Header: X-API-Key: sgpn_<32 hex characters> Get a free key at https://developers.sgpaynowqr.com/register --- ## POST /generate Generate a PayNow QR code Generate an EMVCo-compliant PayNow QR code for Singapore payments. Supports UEN, mobile number, and VPA payment types. Auth: required (X-API-Key header) ### Request Parameters | Field | Type | Required | Constraints | Description | |-------|------|----------|-------------|-------------| | payment_type | string | Yes | one of: uen, mobile, vpa | Type of PayNow payment | | uen | string | No | max 25 chars | UEN number (required if payment_type is "uen") | | merchant_name | string | No | max 25 chars | Merchant name (required if payment_type is "uen") | | mobile_number | string | No | pattern ^(\+65)?[89]\d{7}$ | Singapore mobile number (required if payment_type is "mobile") | | vpa | string | No | — | Virtual Payment Address (required if payment_type is "vpa") | | amount | number | Yes | range 0.01–999999.99 | Payment amount in SGD | | reference | string | No | max 25 chars; pattern ^[a-zA-Z0-9]*$ | Optional alphanumeric reference | | expiry | string | No | one of: 1h, 2h, 6h, 12h, 24h, none; default 24h | QR code expiry duration | | qr_color | string | No | pattern ^[0-9a-fA-F]{6}$; default 7d1979 | QR code color as 6-digit hex (without #) | | qr_size | integer | No | one of: 200, 300, 400; default 300 | QR code image size in pixels | | include_image | boolean | No | default true | Whether to include base64-encoded PNG image in response | ### Request Examples UEN payment: { "payment_type": "uen", "uen": "201234567A", "merchant_name": "My Company", "amount": 25, "reference": "INV001" } Mobile payment: { "payment_type": "mobile", "mobile_number": "+6591234567", "amount": 10.5 } VPA payment: { "payment_type": "vpa", "vpa": "+6591234567#OCBC", "amount": 5, "reference": "DONATION" } ### Responses - 200: QR code generated successfully - 400: Validation error, invalid JSON, or invalid content type { "success": false, "error": { "code": "VALIDATION_ERROR", "message": "Missing required fields for the selected payment_type" }, "meta": { "api_version": "v1", "request_id": "req_abc123def456" } } { "success": false, "error": { "code": "INVALID_JSON", "message": "Malformed JSON body" }, "meta": { "api_version": "v1", "request_id": "req_abc123def456" } } - 401: Missing or invalid API key { "success": false, "error": { "code": "UNAUTHORIZED", "message": "Invalid API key" }, "meta": { "api_version": "v1", "request_id": "req_abc123def456" } } - 429: Quota for the account's billing period used up: 50 codes on Free, or the codes the maximum monthly bill covers on pay as you go. Requests are refused until the period ends; `error.reset_at` and `Retry-After` say when, and `error.upgrade_url` links to the billing page, where a free account switches to pay as you go and a pay-as-you-go account raises its maximum monthly bill. { "success": false, "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Quota used up: 50 of 50 requests on the \"free\" tier this billing period. Resets 2026-11-12T00:00:00+08:00. Upgrade to pay as you go at https://developers.sgpaynowqr.com/billing.", "upgrade_url": "https://developers.sgpaynowqr.com/billing", "reset_at": "2026-11-12T00:00:00+08:00" }, "meta": { "api_version": "v1", "request_id": "req_abc123def456" } } - 500: Internal server error ### Conditional Requirements - payment_type="uen": Business/entity UEN. Requires uen and merchant_name. - payment_type="mobile": Singapore mobile number, format (+65)?[89]XXXXXXX. Requires mobile_number. - payment_type="vpa": Virtual Payment Address. Requires vpa. --- ## GET /health Health check Returns API health status. No authentication required. Auth: none ### Responses - 200: Health status --- ## GET /usage Get quota usage Returns the tier and quota usage for the account that owns the API key. Does not count toward the monthly quota, so it is safe to call to check that a key is valid. Auth: required (X-API-Key header) ### Responses - 200: Usage for the current period - 401: Missing or invalid API key --- ## Error Codes | HTTP | Code | Description | |------|------|-------------| | 400 | VALIDATION_ERROR | Invalid parameters or missing required fields | | 400 | INVALID_JSON | Request body is not valid JSON | | 400 | INVALID_CONTENT_TYPE | Content-Type must be application/json | | 401 | UNAUTHORIZED | Missing or invalid API key | | 429 | RATE_LIMIT_EXCEEDED | Quota for the billing period used up. error.reset_at and Retry-After say when it resets; error.upgrade_url links to billing | | 500 | INTERNAL_ERROR | Server error during QR generation | --- ## Plans and Rate Limits Limits are per account, shared across all your API keys, per monthly billing period. Pay-as-you-go accounts follow their Stripe billing date; free accounts reset each month on their sign-up day (Singapore time). | Plan | Price | Limit per billing period | |------|-------|--------------------------| | Free | S$0, no card needed | 50 codes, then requests stop until the next period | | Pay as you go | S$5 for the first 200 codes; 0.7¢ per code from 201 to 2,000; 0.35¢ per code from 2,001 to 10,000; 0.25¢ per code above 10,000 | Up to your maximum monthly bill: S$50 by default (11,760 codes), settable from S$10 (914) to S$500 (191,760) | Pay as you go is billed by Stripe after each billing period ends, for the codes used, graduated like tax brackets. The maximum monthly bill is set on the billing page; requests stop when the bill so far reaches it. Response headers: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset, X-Request-Id. Only successful (2xx) responses count. X-RateLimit-Reset gives the account's exact reset time. When the quota is used up, POST /generate returns 429 RATE_LIMIT_EXCEEDED with a Retry-After header (seconds until the reset), error.reset_at (the reset time) and error.upgrade_url (the billing page). Stop retrying until then. From 80% of the limit, successful /generate and /usage responses include meta.usage.warning, a human-readable message to pass on to whoever runs the integration. It is absent below 80%. --- ## TypeScript SDK npm install @alexhalfborg/sgpaynowqr import { createClient } from "@alexhalfborg/sgpaynowqr"; const client = createClient("sgpn_your_api_key_here"); const { data } = await client.generate({ payment_type: "uen", uen: "201234567A", merchant_name: "My Company", amount: 25.0, }); GitHub: https://github.com/alexhalfborg/sgpaynowqr-sdk npm: https://www.npmjs.com/package/@alexhalfborg/sgpaynowqr --- ## MCP Server (for agents, not just code-writing LLMs) Agents that support the Model Context Protocol can call QR generation directly as a tool, without writing REST integration code first. Endpoint: https://developers.sgpaynowqr.com/api/mcp (Streamable HTTP, stateless) Auth: same X-API-Key header as the REST API. Clients that only accept a URL (ChatGPT, Claude connectors without Request headers) use a personal URL with the key in the path instead: https://developers.sgpaynowqr.com/api/mcp/sgpn_your_api_key_here. No OAuth. Tool: `generate_qr` — same parameters as POST /generate above. Counts against the same quota as REST/SDK usage. From 80% of the limit the result ends with a short usage note; when the quota is used up the tool error gives the reset time and the upgrade link. ### Client setup #### Claude Code Where: Terminal - Run this once. Add `--scope user` to make it available in every project. - Start `claude` and run `/mcp` to confirm sgpaynowqr is connected. ```bash claude mcp add --transport http sgpaynowqr https://developers.sgpaynowqr.com/api/mcp \ --header "X-API-Key: sgpn_your_api_key_here" ``` #### Claude (web & desktop) Where: Customize → Connectors (Team/Enterprise: an Owner adds it under Organization settings → Connectors) - Open Customize → Connectors and click “Add custom connector”. Free plans allow one custom connector. - Name it SGPayNowQR and enter the server URL below. - Under Authentication, choose “No sign-in”. Under Request headers, pick `x-api-key` as the header name, paste your key as the value, and keep Required ticked. - In a chat, enable the connector from the tools menu, then ask for a PayNow QR. Server URL: https://developers.sgpaynowqr.com/api/mcp Header name: x-api-key Value: sgpn_your_api_key_here No Request headers section in your dialog? Request headers are still rolling out. Use your personal URL as the server URL instead and skip the header: ``` https://developers.sgpaynowqr.com/api/mcp/sgpn_your_api_key_here ``` #### ChatGPT Where: ChatGPT on the web, Plus/Pro/Business/Enterprise/Edu (Developer mode) - Turn on Developer mode in Settings (under Security and login). - Create a developer-mode app for a remote MCP server, name it SGPayNowQR, paste the personal URL below, and choose “No Authentication”. - In a chat, enable SGPayNowQR from the Developer mode tool in the composer. ``` https://developers.sgpaynowqr.com/api/mcp/sgpn_your_api_key_here ``` #### Cursor Where: ~/.cursor/mcp.json (or .cursor/mcp.json in a project) - Add this to your MCP config, then check Settings → MCP shows the server as green. ```json { "mcpServers": { "sgpaynowqr": { "url": "https://developers.sgpaynowqr.com/api/mcp", "headers": { "X-API-Key": "sgpn_your_api_key_here" } } } } ``` #### VS Code Where: .vscode/mcp.json - Add this to your workspace. VS Code prompts for the key once and stores it securely, so it never lands in the file. - Open Copilot Chat in Agent mode and enable sgpaynowqr from the tools picker. ```json { "inputs": [ { "type": "promptString", "id": "sgpaynowqr-api-key", "description": "SGPayNowQR API key", "password": true } ], "servers": { "sgpaynowqr": { "type": "http", "url": "https://developers.sgpaynowqr.com/api/mcp", "headers": { "X-API-Key": "${input:sgpaynowqr-api-key}" } } } } ``` #### Windsurf / Devin Desktop Where: mcp_config.json (open it from Cascade's MCP settings; the path moved in the Devin Desktop rename) - For Cascade: add this to mcp_config.json, then refresh the MCP list. Note the field is `serverUrl`, not `url`. - For the Devin Local agent, use `url` plus `"transport": "http"` in place of `serverUrl`. ```json { "mcpServers": { "sgpaynowqr": { "serverUrl": "https://developers.sgpaynowqr.com/api/mcp", "headers": { "X-API-Key": "sgpn_your_api_key_here" } } } } ``` #### Codex CLI Where: ~/.codex/config.toml - Add this table by hand. `codex mcp add` has no header flag, so the file is the way to send `X-API-Key`. - Run `codex` and type `/mcp` to confirm the tool is listed. ```toml [mcp_servers.sgpaynowqr] url = "https://developers.sgpaynowqr.com/api/mcp" http_headers = { "X-API-Key" = "sgpn_your_api_key_here" } ``` #### Gemini CLI Where: ~/.gemini/settings.json - Add this to your settings, then run `/mcp` inside gemini to confirm. ```json { "mcpServers": { "sgpaynowqr": { "httpUrl": "https://developers.sgpaynowqr.com/api/mcp", "headers": { "X-API-Key": "sgpn_your_api_key_here" } } } } ``` #### n8n Where: An AI Agent node in your n8n workflow - On an AI Agent node, click + under Tool and add the MCP Client Tool node. - Set Endpoint to the URL below and Server Transport to HTTP Streamable. - Set Authentication to Header Auth and create a credential with the name and value below. - Prefer a regular workflow step over an agent? Install the `n8n-nodes-sgpaynowqr` community node instead. Endpoint: https://developers.sgpaynowqr.com/api/mcp Header name: X-API-Key Header value: sgpn_your_api_key_here #### Other (stdio) Where: Your client's MCP config - For clients that can only launch a local process. @alexhalfborg/sgpaynowqr-mcp bridges stdio to the remote server (needs Node 18+). ```json { "mcpServers": { "sgpaynowqr": { "command": "npx", "args": [ "-y", "@alexhalfborg/sgpaynowqr-mcp" ], "env": { "SGPAYNOWQR_API_KEY": "sgpn_your_api_key_here" } } } } ``` Full guide with troubleshooting: https://developers.sgpaynowqr.com/docs/guides/mcp-server-setup