A Singapore Government Agency Website

GovWallet API Specs (1.2)

Download OpenAPI specification:Download

API Usage

In order to use GovWallet API, you are required to generate temporary security credentials, sign your requests and bind the transport security with mTLS. Please use the following information as a guide.

Overall flow

Overall usage flow

Transport Security

mTLS is the transport layer security mechanism on top of standard HTTPS.

  • Your web client will generate requests using provided client private-public key pair. Upload this private key to the server that will be handling outgoing TLS connection and use an appropriate requests library that supports mTLS with the latest TLS cipher standards.
  • The client will make API calls using the private key (e.g. MyClient.pem) to the server. The GovWallet server will recognise this connection as a means of recognising the authenticity of the request.
  • The private-public key pair are time-bound and will need to be renewed before a pre-set expiry date or as needed for security reasons.
  • For a practical example of how mTLS is commonly implemented, please refer to https://medium.com/contino-engineering/mtls-auth-with-aws-api-gateway-9bbd619f7de4

Authorization

For all endpoints you'll need to sign requests using AWS signature version 4.

Differences in Fetching Customer Transactions: Ordered by Created vs. Modified Date

Initially, we introduced the endpoint /v2/customer/transactions/get to fetch all transactions for a customer. The results returned by this endpoint are sorted in ascending order by the created date of the transaction by default. All transaction items related to the transaction are also returned in ascending order of their created dates, based on the accountType specified.

However, we have heard concerns from our partners about the challenges posed by this approach. In response, we introduced a new endpoint: /v2/customer/transactions/getByModifiedDate. This endpoint returns transaction items sorted by their modified date in ascending order, making the accountType field in the request body no longer mandatory. This change means you no longer need to call the endpoint twice to fetch transactions for both normal and outflow accounts.

Differences in Fetching Transactions: Ordered by Created vs. Modified Date

Initially, we introduced the endpoint /v2/transactions/get to fetch all transactions associated with a particular campaign. By default, the results returned by this endpoint are sorted in ascending order by the created date of each transaction. Similarly, all transaction items related to a transaction are returned in ascending order of their created dates.

However, we have heard concerns from our partners about the challenges posed by this approach, especially regarding the need to perform the same backdate query to receive any updated transaction items belonging to a transaction. In response, we introduced a new endpoint: /v2/transactions/getByModifiedDate. This endpoint returns transaction items sorted by their modified date in ascending order by default. Importantly, the request body accepts an optional field "orderBy" that allows users to change the sorting order to descending. This flexibility ensures that you no longer need to repeatedly call the endpoint with the same start and end dates to check for updates to the transaction items associated with a transaction.

Changelog

2024-12-10 (v1.2)

  • Update regex for trancheId and error message in endpoint "v2/benefactor/tranche/create"

2024-11-26 (v1.1)

  • Add new endpoint "v2/benefactor/tranche/create" to create a disbursement tranche for a particular campaign
  • Add new endpoint "v2/benefactor/tranche/disburse" to create a disbursement for a customer based on a tranche for a particular campaign

2024-10-22 (v1.0)

  • Create specification

GovWallet

GovWallet core APIs

Get account details

  • Get customer account details for a campaign, including balance and if it's deactivated.
  • By default, details of the "NORMAL" account will be returned.
  • Account details for all categories of the campaign will be returned.
  • When "campaign" field is omitted, account details for all campaigns will be returned.
  • If credits expiry is enabled, "expiries" field will be returned.
Request Body schema: application/json
customerId
required
string

Hashed ID of customer

campaign
string
Value: "campaign_abbrv"

When omitted, account details for all campaigns will be returned.

accountType
string
Default: "NORMAL"
Enum: "NORMAL" "OUTFLOW"

Responses

Request samples

Content type
application/json
{
  • "customerId": "4963CEE2672AC6269243F359DD66B017B5274AB2B43C591BAF571B43A89C57B0",
  • "campaign": "campaign_abbrv"
}

Response samples

Content type
application/json
Example
{
  • "customerId": "4963CEE2672AC6269243F359DD66B017B5274AB2B43C591BAF571B43A89C57B0",
  • "accountDetails": [
    ]
}

Get customer transactions sorted by transaction item's modified date

  • Get transactions of a customer between an optional date range, for a campaign.
  • By default, the ordering of the transactions are sorted in ascending order of transaction modified date.
  • Transactions for all categories of the campaign will be returned.
  • Each call returns up to 1MB of data. To retrieve the next 1MB of data, use the "exclusiveStartKey" property that is returned from the previous request.
Request Body schema: application/json
customerId
required
string

Hashed ID of customer

campaign
required
string
Value: "campaign_abbrv"

Campaign to perform action on

startDate
string <date-time>

Start date of filter, in ISO8601, Singapore timezone

endDate
string <date-time>

End date of filter, in ISO8601, Singapore timezone

exclusiveStartKey
string

Used for pagination. Provide the value from the response parameter lastEvaluatedKey (if it exists) to retrieve the next set of transactions.

orderBy
string
Default: "ASC"
Enum: "ASC" "DESC"

Returns transactions in ascending or descending order of transaction modified date.

Responses

Request samples

Content type
application/json
Example
{
  • "customerId": "4963CEE2672AC6269243F359DD66B017B5274AB2B43C591BAF571B43A89C57B0",
  • "campaign": "campaign_abbrv",
  • "startDate": "2021-06-17T12:38:47.908+08:00",
  • "endDate": "2021-07-17T12:38:47.908+08:00"
}

Response samples

Content type
application/json
Example
{
  • "customerId": "4963CEE2672AC6269243F359DD66B017B5274AB2B43C591BAF571B43A89C57B0",
  • "transactions": [ ]
}

Get all transactions sorted by modified date

  • Get transactions of everyone between a date range, for a campaign.
  • Each call returns up to 1MB of data. To retrieve the next 1MB of data, use the "exclusiveStartKey" property that is returned from the previous request.
  • By default, the ordering of the transactions are sorted in ascending order of transaction modified date.
  • An optional field can be provided to filter for a specific type of transaction state.
Request Body schema: application/json
campaign
required
string
Value: "campaign_abbrv"

Campaign to perform action on

startDate
required
string <date-time>

Start date of filter, in ISO8601, Singapore timezone

endDate
string <date-time>

End date of filter, in ISO8601, Singapore timezone

exclusiveStartKey
string

Used for pagination. Provide the value from the response parameter lastEvaluatedKey (if it exists) to retrieve the next set of transactions.

orderBy
string
Default: "ASC"
Enum: "ASC" "DESC"

Returns transactions in ascending or descending order of transaction modified date.

filterBy
string
Enum: "ATM_CREATE" "ATM_COMPLETE" "ATM_COMPLETE_MANUAL" "ATM_CANCEL" "ATM_REFUND_MANUAL" "PAYNOW_CREATE" "PAYNOW_COMPLETE" "PAYNOW_CANCEL" "PAYNOW_FAILURE" "PAYNOW_CREATE_MANUAL" "PAYNOW_COMPLETE_MANUAL" "PAYNOW_CANCEL_MANUAL" "PAYNOW_REFUND_MANUAL" "PAYNOW_REFUND_PARTIAL_MANUAL" "NETS_CREATE" "NETS_COMPLETE" "NETS_CANCEL" "NETS_REFUND" "DISBURSE" "EXPIRE" "CLAWBACK"

Filter transactions by type

Responses

Request samples

Content type
application/json
Example
{
  • "campaign": "campaign_abbrv",
  • "startDate": "2021-06-17T12:38:47.908+08:00",
  • "exclusiveStartKey": "eyJTSyI6ImNhbXBhaWduX2EjY2F0ZWdvcnlfYSNUWE4jMjE1M2N2RmMxZUxZd3JkOXE3bW56VFducjRRIzIiLCJQSyI6IkNVUyNTMDAwMDAwMUkjY2FtcGFpZ25fYSJ9"
}

Response samples

Content type
application/json
Example
{
  • "transactions": [ ]
}

Create disbursement tranche

  • Create a new tranche representing a fixed disbursement of credits for a campaign.

A tranche represents a fixed allocation of credits that must be created first before any disbursement of credits can take place. Each tranche is uniquely identified by a trancheId and is associated with a predetermined credit amount. This structure allows for controlled disbursement, where every customer linked to a specific tranche receives the same fixed amount of credits. All disbursements associated with a given "trancheId" will share the same fixed amount defined by "amountInCents".

Request Body schema: application/json
trancheId
required
string/^[a-zA-Z0-9-]{1,128}$/

Tranche ID to be associate with this disbursement tranche

campaign
required
string
Value: "campaign_abbrv"

Campaign to perform action on

amountInCents
required
integer

Amount in cents

Responses

Request samples

Content type
application/json
{
  • "trancheId": "FY2025-payout",
  • "campaign": "campaign_abbrv",
  • "amountInCents": 10000
}

Response samples

Content type
application/json
{
  • "message": "Successfully created tranche",
  • "trancheId": "FY2025-payout",
  • "campaign": "campaign_abbrv",
  • "amountInCents": 10000
}

Create disbursement to a customer based on tranche

  • Disburses a fixed amount of credits to the specified customer based on the "trancheId".
  • The validity period for the disbursed credits must be specified using "validFrom" and "validTo". If "validFrom" is not provided, it defaults to the current time.
  • The "validTo" field specifies when the credits will expire. For any given tranche ID, each customer can have only one disbursement, and the validity period for that disbursement is determined by the customer's specific "validFrom" and "validTo" values.

Previously, customer account creation ("/v2/customer/account/create") and disbursement ("/v2/benefactor/disbursement/create") were handled separately. This new disbursement endpoint ("/v2/benefactor/tranche/disburse") simplifies the process by combining both operations into a single step. Account creation and disbursement occur on or after the "validFrom" date. If "validFrom" is specified, the customer account is created only if it doesn't already exist at that time. This endpoint is idempotent, ensuring that credits are never disbursed to the same customer more than once for the same "customerId" and "trancheId", even when "validFrom" defaults to the current time.

Request Body schema: application/json
customerId
required
string

Hashed ID of customer

campaign
required
string
Value: "campaign_abbrv"

Campaign to perform action on

required
object (Disbursement with tranche details)

Responses

Request samples

Content type
application/json
Example
{
  • "customerId": "4963CEE2672AC6269243F359DD66B017B5274AB2B43C591BAF571B43A89C57B0",
  • "campaign": "campaign_abbrv",
  • "disbursement": {
    }
}

Response samples

Content type
application/json
Example
{
  • "customerId": "4963CEE2672AC6269243F359DD66B017B5274AB2B43C591BAF571B43A89C57B0",
  • "campaign": "campaign_abbrv",
  • "disbursement": {
    }
}