GovWallet

The GovWallet Node allows your workflow to interact with Singapore’s GovWallet API for managing digital wallet operations. It enables secure disbursement of funds, account creation, and account information retrieval through GovWallet’s infrastructure.

Important: This node requires AWS SigV4 signing. You will need valid AWS credentials to use this node. Contact your GovWallet administrator to obtain the necessary credentials.

GovWallet Support: For any enquiries or issues related to GovWallet, please reach out to the GovWallet Service Desk via go.gov.sg/hello-govwallet.

How Does It Work?

Prerequisites: You will need AWS credentials configured for your agency. See Configuration for detailed requirements.

Setup Steps:

1. Build your workflow using Graph Edit Mode (minimum setup: input node → govwallet node → output node, but you can add more nodes as needed)
2. Click on the GovWallet node settings to open its configuration
3. Configure the connection settings with your credentials (GovWallet Environment, Base URL, AWS credentials)
4. Select the operation you want to perform and configure the required parameters

Output:

The GovWallet Node returns the response from the GovWallet API. The output structure varies depending on the operation performed:

Create Disbursement Output:

{
  "message": "Successfully disbursed",
  "customerId": "4963CEE2672AC6269243F359DD66B017B5274AB2B43C591BAF571B43A89C57B0",
  "amountCents": 10000,
  "transactionId": "1thEE1p0j8QcQqAyhKugz3omWJ4",
  "timestamp": "2021-07-13T00:00:00.000+08:00",
  "validFrom": "2021-07-13T00:00:00.000+08:00",
  "validTo": "2030-12-31T23:59:59.999+08:00",
  "details": {
    "schemeCode": "WIS",
    "subCode": "EE",
    "allotmentYear": "2021",
    "allotmentCycle": "01",
    "transactionDescription": "Workfare Income Supplement",
    "organisation": "Central Provident Fund Board"
  }
}Copy to clipboardErrorCopied

Create Account Output:

{
  "customerId": "4963CEE2672AC6269243F359DD66B017B5274AB2B43C591BAF571B43A89C57B0",
  "message": "Successfully created customer account",
  "timestamp": "2021-06-17T12:38:47.908+08:00"
}Copy to clipboardErrorCopied

Get Account Output:

{
  "customerId": "4963CEE2672AC6269243F359DD66B017B5274AB2B43C591BAF571B43A89C57B0",
  "accountDetails": [
    {
      "accountId": "4963CEE2672AC6269243F359DD66B017B5274AB2B43C591BAF571B43A89C57B0",
      "accountType": "NORMAL",
      "activationStatus": "ACTIVATED",
      "balance": 300,
      "campaign": "campaign_a",
      "category": "credits",
      "created": "2021-04-20T00:00:00.000+08:00",
      "entity": "Customer",
      "modified": "2021-04-20T00:00:00.000+08:00",
      "expiries": [
        {
          "initialAmount": 100,
          "availableAmount": 100,
          "expires": "2022-12-31T23:59:59.999+08:00"
        }
      ]
    }
  ]
}Copy to clipboardErrorCopied

Subsequent nodes can access the response data using field names like transactionId, customerId, accountDetails, etc.

Configuration

Connection Settings

GovWallet Environment

The GovWallet environment you are connecting to. This will determine which mTLS configuration OPUS will use to establish trust with the respective GovWallet environment.

Format: Staging or Production

Example: Staging

Important: Please ensure that GovWallet has whitelisted OPUS’ IP addresses.

GovWallet Base URL

The base URL for the GovWallet API endpoint.

Format: Full URL including protocol (https://)

Example: https://api.govwallet.gov.sg

Important: The URL must use HTTPS and end with .wallet.gov.sg for security compliance. Contact your GovWallet administrator if you are unsure of the base URL.

Tip: Use the Verify button to test your connection settings before running the workflow.

AWS Access Key ID

Your AWS Access Key ID for SigV4 request signing.

Format: Plain text (typically 20 characters)

Example: AKIAIOSFODNN7EXAMPLE

AWS Secret Access Key

Your AWS Secret Access Key for SigV4 request signing.

Format: Plain text (will be encrypted)

Example: wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY

AWS Role ARN

The ARN of the IAM role to assume for cross-account access.

Format: ARN string

Example: arn:aws:iam::123456789012:role/GovWalletAccessRole

AWS Role Session Name

A name for the assumed role session.

Format: Plain text (alphanumeric and limited special characters)

Example: opus-workflow-session

External ID

The external ID required for assuming the IAM role (if configured in the trust policy).

Format: Plain text

Example: your-external-id-here

Operations

The GovWallet Node supports three operations:

Create Disbursement

Transfers funds or credits to a customer’s GovWallet account.

Tip: The idempotency key ensures that if the same request is sent multiple times (e.g., due to network issues), only one disbursement is created. If not provided, a UUID is automatically generated.

Create Account

Creates a new GovWallet account for a customer under a specific campaign.

Get Account

Retrieves account information for a customer under a specific campaign.

Deactivate Account

Deactivate account in a specific campaign.

Activate Account

Activate account in a specific campaign.

Clawback Transaction

Perform clawback of credits from a customer within a campaign.

Examples

Example 1: Disburse GST Vouchers to Citizen

A workflow that disburses GST vouchers to a citizen’s GovWallet account after eligibility verification.

Configuration:

Connection:
  GovWallet Base URL: https://api.govwallet.gov.sg
  Client Certificate: <base64-encoded-certificate>
  Client Key: <base64-encoded-key>
  Access Key ID: AKIAIOSFODNN7EXAMPLE
  Secret Access Key: ••••••••••••••••
  AWS Role ARN: arn:aws:iam::123456789012:role/GSTDisbursementRole
  Role Session Name: GST-disbursement
  External ID: GST-external-id

Operation: Create Disbursement

Parameters:
  Idempotency Key: {{input.applicationId}}
  Customer ID: {{input.nric}}
  Campaign: GST_VOUCHERS_2025
  Benefactor ID: GST_SINGAPORE
  Amount: {{decision.approvedAmount}}Copy to clipboardErrorCopied

Input:

{
  "applicationId": "APP-2025-001234",
  "nric": "S1234567A",
  "approvedAmount": "10000"
}Copy to clipboardErrorCopied

Output:

{
  "message": "Successfully disbursed",
  "customerId": "S9876543B",
  "amountCents": 10000,
  "transactionId": "1thEE1p0j8QcQqAyhKugz3omWJ4",
  "timestamp": "2025-01-15T10:30:00.000+08:00",
  "validFrom": "2025-01-15T10:30:00.000+08:00",
  "validTo": "2030-12-31T23:59:59.999+08:00",
  "details": {
    "schemeCode": "WIS",
    "subCode": "EE",
    "allotmentYear": "2025",
    "allotmentCycle": "01",
    "transactionDescription": "Workfare Income Supplement",
    "organisation": "Central Provident Fund Board"
  }
}Copy to clipboardErrorCopied

Example 2: Create GovWallet Account for New Beneficiary

A workflow that creates a GovWallet account for a new beneficiary enrolled in a grant programme.

Configuration:

Connection:
  GovWallet Base URL: https://api.govwallet.gov.sg
  Client Certificate: <base64-encoded-certificate>
  Client Key: <base64-encoded-key>
  (AWS credentials configured)

Operation: Create Account

Parameters:
  Customer ID: {{input.beneficiaryNric}}
  Campaign: GRANT_PROGRAMME_2025Copy to clipboardErrorCopied

Input:

{
  "beneficiaryNric": "S9876543B",
  "beneficiaryName": "Jane Doe"
}Copy to clipboardErrorCopied

Output:

{
  "customerId": "S9876543B",
  "message": "Successfully created customer account",
  "timestamp": "2025-01-15T10:30:00.000+08:00"
}Copy to clipboardErrorCopied

Example 3: Check Account Balance Before Disbursement

A workflow that retrieves account information to check the current balance before making additional disbursements.

Configuration:

Connection:
  (credentials configured as above)

Operation: Get Account

Parameters:
  Customer ID: {{input.nric}}
  Campaign: {{input.campaignCode}}Copy to clipboardErrorCopied

Input:

{
  "nric": "S1234567A",
  "campaignCode": "GST_VOUCHERS_2025"
}Copy to clipboardErrorCopied

Output:

{
  "customerId": "S1234567A",
  "accountDetails": [
    {
      "accountId": "S1234567A",
      "accountType": "NORMAL",
      "activationStatus": "ACTIVATED",
      "balance": 5000,
      "campaign": "GST_VOUCHERS_2025",
      "category": "credits",
      "created": "2025-01-01T00:00:00.000+08:00",
      "entity": "Customer",
      "modified": "2025-01-01T00:00:00.000+08:00",
      "expiries": []
    }
  ]
}Copy to clipboardErrorCopied

Example 4: Deactivate Account

A workflow that deactivates an account so that the account can no perform any transactions on GovWallet (e.g. receive or spend credits).

Configuration:

Connection:
  (credentials configured as above)

Operation: Deactivate Account

Parameters:
  Customer ID: {{input.nric}}
  Campaign: {{input.campaignCode}}Copy to clipboardErrorCopied

Input:

{
  "nric": "S1234567A",
  "campaignCode": "GST_VOUCHERS_2025"
}Copy to clipboardErrorCopied

Output:

{
  "customerId": "S1234567A",
  "message": "Successfully de-activated customer account",
  "timestamp": "2021-06-17T12:38:47.908+08:00"
}Copy to clipboardErrorCopied

Tip: An error will be thrown by GovWallet if you try to deactivate an already deactivated customer. You can choose to ignore this error by adding a special handling when the error message returned by GovWallet is "Customer account does not exist, or is deactivated"

Response Handling

Response Handling lets you decide which HTTP status codes returned by GovWallet count as a successful execution of the node. You list the status codes (or ranges) that should be treated as success — everything else is treated as an Error, including network failures and timeouts.

How it works:

• Treat as Success — Add the status codes or ranges that indicate success. When GovWallet responds with one of these, the node completes normally and passes its response to the next node.
• Everything else → Error — Any status code not listed as success (as well as network failures and timeouts) fails the node, which then follows its error path and retry policy.

Configuring the codes:

• Add a code or range — Type a single 3-digit code (e.g. 404) or an inclusive range (e.g. 400-429) and click Add.
• Quick add — Use the shortcut chips (2xx, 3xx, 4xx, 404) to add common patterns instantly.
• Remove — Click the × on any code chip to remove it from the success list.
• Reset to defaults — Restores the default configuration.
• Check a status code — Enter a status code in the tester to preview whether it would resolve to Success or Error with your current configuration.

Default configuration (new nodes):

Tip: Most workflows only need the defaults. Extend the success list when GovWallet returns a non-2xx/3xx code that your workflow should treat as a valid, non-retryable outcome — for example, treating the "Customer account does not exist, or is deactivated" response as a branchable result you handle with a downstream Switch Node (see the Deactivate Account tip above).

Older nodes: GovWallet nodes created before this feature was introduced keep their original behaviour (client 4xx codes returned as output, except 429; 429 and 5xx treated as errors) until you first edit and save the Response Handling section.

This is the same Response Handling behaviour available on the API node.

When to Use It?

Use GovWallet Node when:

• You need to disburse funds or credits to citizens through government programmes (e.g., GST vouchers, grants, subsidies).
• You want to create GovWallet accounts for beneficiaries enrolled in government schemes.
• You need to retrieve account information to verify balances or account status.
• You are building workflows for government-to-citizen (G2C) payment operations.
• You want to automate disbursement processes with idempotency guarantees.

Tip: Always use meaningful idempotency keys (such as application IDs or transaction references) for disbursements to prevent duplicate payments in case of retries.