GovWallet API Integration

This guide explains how agencies can integrate with GovWallet using APIs to support payout workflows in their own systems. It covers the required setup, authentication methods, overall request flow, and core endpoints for account management and disbursements.

A GovWallet integration is a collaboration between three parties:

• Scheme owners — the policy owners who define the rules, eligibility criteria, and disbursement logic of a scheme
• Agency systems (if applicable) — the technical systems that implement those rules and trigger API calls. Some scheme owners may not have their own systems, in which case they use GovWallet or other WOG systems directly.
• GovWallet — the platform that executes disbursements, manages accounts, and serves as the source of truth for payments and transaction records

Scheme owners drive the business intent — they decide who qualifies, how much recipients are entitled to, and under what conditions credits should be disbursed or clawed back. Agency systems translate those policy decisions into API operations, maintaining beneficiary eligibility data and orchestrating the integration. GovWallet provides the mechanism through which those decisions are executed and recorded.

Not all scheme owners have their own agency systems. In these cases, scheme owners can use GovWallet’s portal or other WOG systems to manage their schemes without building a custom integration. This guide focuses on the API integration path for agencies that do maintain their own systems.

Before you begin

Complete the following before making your first API connectivity call:

• Confirm scheme details with the GovWallet team
• Kickstart administrative onboarding with the banking partner (OCBC, DBS)
• Generate a Certificate Signing Request (CSR) and compile the IP addresses for whitelisting
• If the agency system is on AWS, provision an AWS IAM role that will be used for role assumption
• If the agency system is not on AWS, inform GovWallet — both an AWS IAM user and AWS IAM role will need to be provisioned instead

Authentication Methods

GovWallet supports two authentication methods. The agency’s onboarding documentation will specify which method applies to the integration.

Option 1: mTLS + AWS Signature Version 4

This option uses two layers of security:

• mTLS — transport security. Both client and server verify each other’s identity during the TLS handshake.
• AWS Signature Version 4 — request-level authorisation. Each API request is signed using temporary credentials obtained via IAM role assumption.

For full setup instructions (CSR generation, IP whitelisting, role configuration, and making your first call), see the mTLS and SigV4 Setup Guide.

Option 2 : OAuth (AWS Cognito)

Note: OAuth support is currently a work in progress — not all endpoints are available via this authentication method yet. Check with the GovWallet team for current coverage and let the team know the required endpoints for prioritisation.

This option uses client credentials flow with AWS Cognito. No AWS account is required — the agency authenticates with a client ID and secret, and includes the resulting access token in API requests.

For full setup instructions, see the OAuth Setup Guide.

Choosing Between Authentication Methods