Onboarding to use the GovWallet APIs using the OAuth authentication method

Last updated: 2025-03-06

This onboarding guide serves to guide you through the steps required to setup and achieve connectivity to the GovWallet APIs using the OAuth authentication method. These are used to make direct API calls to GovWallet, such as earmarking, getting of customer accounts and triggering of refunds.

Our APIs requires you to fetch a client credential from AWS Cognito given a set of client details, and to send over the request in a JWE format.

GovWallet’s public keys for encryption and signing can be found at https://paywith.wallet.gov.sg/.well-known/jwks.json, differentiated by the field use for their intended purpose. You can use GovWallet’s public encryption key to generate the JWE payload to make a request to our APIs, and you can use GovWallet’s public signing key to verify that a payload from us is legitimate.

Note that the prior url https://dist.wallet.gov.sg will be deprecated after 31 May 2025, so please make the switch to https://paywith.wallet.gov.sg before then.

Prerequisites

1. You have a secure way of storing the secrets and configuration used in the calling of the APIs
2. You have an existing ability to send us a unique hashed user id value
3. Staging campaign connectivity should be established before production campaign connectivity

Generate a new RSA 4096 encryption keypair using the following instructions

This keypair is used to encrypt the response returned from the GovWallet APIs to you. For simplicity of documentation, we’ll call this key the “partner encryption key”.

We also recommend generating a keypair per environment.

openssl genpkey -algorithm RSA -out rsa_private_key.pem -pkeyopt rsa_keygen_bits:4096
openssl rsa -in rsa_private_key.pem -pubout -out rsa_public_key.pem
base64 -i rsa_public_key.pem > rsa_public_key_base64.txt
base64 -i rsa_private_key.pem > rsa_private_key_base64.txtCopy to clipboardErrorCopied

Send the values to GovWallet

For non-production environments

1. Pass the partner’s public encryption key to GovWallet
2. Pass all possible issuer (iss) values
3. We’ll generate a set of client credentials and the campaign, and pass you these values along with the endpoint and point you to our api documentation.

For production environment

1. Pass the partner’s public encryption key to GovWallet
2. Pass all possible issuer (iss) values
3. We’ll generate a set of client credentials and the campaign, and pass you these values along with the endpoint and point you to our api documentation.
4. Let the GovWallet team know that you are ready to receive the configuration for your production environment by going to https://justencrypt.github.io/ and following the flow of Recipient: I want to receive a secret.
5. Send the Lock file to the GovWallet team.
6. GovWallet will send you back a Locked file.
7. Continue through the flow to unlock the Locked file.

Step 2: Setup cognito and get client credential

Obtain Access Token

Endpoint: POST https://wallet-suite.auth.ap-southeast-1.amazoncognito.com/oauth2/token

Request Parameters

• Grant Type: `client_credentials`
• Client ID: Provided by AWS Cognito application configuration
• Client Secret: Provided by AWS Cognito application configuration
• Scope: Specify required scopes

Example Request (CURL)

curl --location 'https://wallet-suite.auth.ap-southeast-1.amazoncognito.com/oauth2/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=client_credentials' \
--data-urlencode 'client_id=your_client_id' \
--data-urlencode 'client_secret=your_client_secret' \
--data-urlencode 'scope=wallet-core/earmark wallet-core/refund'Copy to clipboardErrorCopied

Successful Response

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "wallet-core/earmark wallet-core/refund"
}Copy to clipboardErrorCopied

Note: this token expires so needs to be refreshed periodically.

Step 3: JWE Header Specifications

When encrypting requests to and decrypting responses from the GovWallet API, you must use the following JWE header format:

{
  "alg": "RSA-OAEP-512",
  "enc": "A256GCM"
}Copy to clipboardErrorCopied

This header specifies:

• alg: The key encryption algorithm (RSA-OAEP-512)
• enc: The content encryption algorithm (A256GCM)

Step 4: Testing connectivity

Putting everything together, make the following call to the GovWallet Checkout Page to test connectivity. These are the rough steps and order of things to be done to prep the request

1. Use the access token received from cognito inside the header of the request
2. Use GovWallet’s public encryption key to encrypt the request payload
3. Send the encrypted request to the API
4. Use partner’s private encryption key to decrypt the response returned from the API
5. Use GovWallet’s public signing key to verify the response returned from the API

curl --location 'https://paywith.wallet.gov.sg/api/refund' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--header 'Authorization: Bearer access_token' \
--data-urlencode 'payload=jwe_token'Copy to clipboardErrorCopied

Notes

Compromise of partner’s encryption key

In the event of a suspected leak or compromise of your encryption key, do inform the GovWallet team as soon as possible and follow the same steps above to generate a new key.

There is no defined schedule for the rotation of encryption keys. This would be determined by your team’s security and policy guidelines. We would recommend a rotation at every 1 to 2 years mark.

Compromise of GovWallet’s signing or encryption key

In the event of a suspected leak or compromise of GovWallet’s signing key or encryption key, we will inform partners as soon as possible and publish a new key. Please go to the JWKs endpoint to retrieve the new key and retest connectivity.

For us our keys will be rotated once every 2 years.