Virtual accounts

Introduction

The Virtual Account API provides comprehensive management for virtual accounts, enabling operations such as account provisioning, transaction confirmation, and more. This API is ideal for use cases involving financial institutions, payment gateways, and e-commerce platforms, offering robust support for generating and managing virtual accounts tied to invoices and checkouts. For detailed information, please refer to the individual endpoint descriptions.

Payment lifecycle using a virtual account number

Endpoints

Endpoint 1: Provision virtual account

Description: This endpoint is used to provision a virtual account
Method: POST
URL: /v-accounts/provision
Request Parameters:

	Name	Type	Description	Default value	In
1.	`expiryType`	string ENUM: `SINGLE_USE` `MULTI_USE` `DEDICATED`	Configuration on how the virtual account should operate. `SINGLE_USE` accepts a single transaction and expires after a transaction. This option also expects payments to match the amount indicated on provisioning `MULTI_USE` accepts multiple split payments.	`SINGLE_USE`	body
2.	`amount`	number`<double>`			body
3.	`validityPeriod`	integer`<int32>`	in minutes, max 1440 (24 hours)	`30`	body
4.	`partnerReference`	string			body
5.	`settlementAccountNumber`	string		Value from auth server (via token)	body
6.	`callbackUrl`	string		Value from auth server (via token)	body
7.	`requestingInstitutionName`	string	Name of Institution to show when performing a name query on the account number		body
8.	`verifyAmount`	boolean	A boolean to validate if payments to the virtual account number match the provisioned amount. Applies only to single-use virtual account numbers.	`FALSE`

Response (Success: 200)

	Name	Type
1.	`transactionID`	string
2.	`partnerReference`	string
3.	`amount`	number`<double>`
4.	`virtualAccountNumber`	string
5.	`dateCreated`	string`<date-time>`
6.	`expireDate`	string`<date-time>`
7.	`expiryType`	string ENUM: `SINGLE_USE` `MULTI_USE` `DEDICATED`
8.	`accountStatus`	string ENUM: `USED` `UNUSED`
9.	`requestingInstitutionName`	string
10.	`verifyAmount`	boolean

Endpoint 2: Virtual account status query

Description: This endpoint is used to get the status of a virtual account
Method: GET
URL: /v-accounts/status-query/{virtual_account}
Request Parameters:

	Name	Type	Description	Default value	In
1.	`virtual_account` (required)	string			path

Response (Success: 200)

	Name	Type
1.	`virtualAccountNumber`	string
2.	`transactionId`	string
3.	`partnerReference`	string
4.	`expiryDate`	string`<date-time>`
5.	`expired`	boolean

Endpoint 3: List virtual accounts

Description: This endpoint is used to get the list of virtual accounts
Method: GET
URL: /v-accounts/virtual-accounts
Request Parameters:

	Name	Type	In
1.	`offset`	integer `<int32>`	path
2.	`start_date`	string`yyyy-MM-dd`
3.	`end_date`	string`yyyy-MM-dd`

Response (Success: 200)

	Name	Type	Description
1.	`offset`	integer `<int32>`
2.	`limit`	integer `<int32>`
3.	`size`	integer `<int32>`
4.	`total`	integer `<int32>`
5.	`accounts`	Array of objects	Refer to the account object table below for the list of objects

Account object table

	Name	Type
1.	`transactionId`	string
2.	`partnerReference`	string
3.	`virtualAccountNumber`	string
4.	`amount`	number`<double>`
5.	`expiryType`	string ENUM: `SINGLE_USE` `MULTI_USE` `DEDICATED`
6.	`dateCreated`	string`<date-time>`
7.	`expireDate`	string`<date-time>`
8.	`verifyAmount`	boolean
9.	`requestingInstitutionName`	string
10.	`accountStatus`	string ENUM: `USED` `UNUSED`

Sample account data

{
  "expiryType": "SINGLE_USE",
  "transactionId": "string",
  "partnerReference": "string",
  "virtualAccountNumber": "string",
  "dateCreated": "2024-10-03T09:51:21.664Z",
  "expireDate": "2024-10-03T09:51:21.664Z",
  "accountStatus": "USED",
  "requestingInstitutionName": "string",
  "verifyAmount": true,
  "amount": 0
}

Endpoint 4: Get virtual account info

Description: This endpoint is used to get the information on a virtual account
Method: GET
URL: /v-accounts/name-query/{virtual_account}
Request Parameters:

	Name	Type	Description	Default value	In
1.	`virtual_account` (required)	string			path

Response (Success: 200)

	Name	Type
1.	`expiryType`	string
2.	`transactionId`	string
3.	`amount`	number`<double>`
4.	`validityPeriod`	integer
5.	`partnerReference`	string
6.	`virtualAccountNumber`	string
7.	`settlementAccountNumber`	string
8.	`callbackUrl`	string
9.	`dateCreated`	string`<date-time>`
10.	`expireDate`	string`<date-time>`
11.	`accountStatus`	string ENUM: `USED` `UNUSED`
12.	`expired`	boolean
13.	`requestingInstitutionName`	string
14.	`verifyAmount`	boolean

Endpoint 5: Query virtual account transactions

Description: This endpoint is used to search by specific parameters for reporting on a virtual account
Method: GET
URL: /v-accounts/transactions
Request Parameters:

	Name	Type	In
1.	`offset`	integer`<int32>`	body
2.	`start_date`	string`yyyy-MM-dd`
3.	`end_date`	string`yyyy-MM-dd`
4.	`virtual_account_number`	string	body
5.	`partner_reference`	string
6.	`ghipss_session_id`	string
7.	`ghipss_tracking_numer`	string

Response (Success: 200)

	Name	Type	Description
1.	`offset`	integer`<int32>`
2.	`limit`	integer`<int32>`
3.	`size`	integer `<int32>`
4.	`total`	integer `<int32>`
5.	`transactions`	Array of objects (TransactionResponse)	Refer to the transactions object table below for the list of objects

Endpoint 6: Get transactions for virtual account

Description: This endpoint is used to query a transaction details on a virtual account
Method: GET
URL: /v-accounts/transactions/{virtual_account}
Request Parameters:

	Name	Type	Description	Default value	In
1.	`virtual_account` (required)	string			path
2.	`offset`	integer`<int32>`

Response (Success: 200)

	Name	Type	Description
1.	`offset`	integer`<int32>`
2.	`limit`	integer`<int32>`
3.	`size`	integer `<int32>`
4.	`total`	integer `<int32>`
5.	`transactions`	Array of objects (TransactionResponse)	Refer to the transactions object table below for the list of objects

Transactions object table

	Name	Type
1.	`transactionId`	string
2.	`partnerReference`	string
3.	`virtualAccountNumber`	string
4.	`amount`	number`<double>`
5.	`expiryType`	string ENUM: `SINGLE_USE` `MULTI_USE` `"DEDICATED"`
6.	`dateCreated`	string`<date-time>`
7.	`expireDate`	string`<date-time>`
8.	`expired`	boolean
9.	`trackingNumber`	string
10.	`sessionId`	string
11.	`ghippsTimestamp`	string`<date-time>`
12.	`transactionStatus`	string
13.	`narration`	string
14.	`payerAccountName`	string
15.	`payerBank`	string
16.	`payerAccountNumber`	string
17.	`settlementAccount`	string

Sample transactions data

{
  "transactionId": "string",
  "partnerReference": "string",
  "virtualAccountNumber": "string",
  "amount": 0,
  "expiryType": "SINGLE_USE",
  "dateCreated": "2024-10-02T15:29:23.428Z",
  "expireDate": "2024-10-02T15:29:23.428Z",
  "expired": true,
  "trackingNumber": "string",
  "sessionId": "string",
  "ghipssTimestamp": "2024-10-02T15:29:23.428Z",
  "transactionStatus": "SUCCESS",
  "narration": "string",
  "payerAccountName": "string",
  "payerBank": "string",
  "payerAccountNumber": "string",
  "settlementAccount": "string"
}

Endpoint 7: Expire virtual account

Description: This endpoint is used to manually expire a virtual account ahead of the timed lifespan
Method: PUT
URL: /v-accounts/expire-account/{virtual_account}
Request Parameters:

	Name	Type	Description	Default value	In
1.	`virtual_account` (required)	string			path

Response (Success: 200)

	Name	Type
1.	`virtualAccountNumber`	string
2.	`expireDate`	string`<date-time>`
3.	`expired`	boolean

Endpoint 8: Resend callback

Description: This endpoint is used to request for a callback to be resent
Method: GET
URL: /v-accounts/resend-callback/{partnerReference}
Request Parameters:

	Name	Type	Description	Default value	In
1.	`partnerReference` (required)	string			path

Response (Success: 200)

	Name	Type	Description
1.	`success`	boolean	Response sent to resend callback request. Returns `TRUE` to acknowledge receipt. The callback, containing webhook data, is resent to the callback URL.

Webhooks

Virtual account events

Affinity sends webhooks for transaction activity on virtual accounts

IP Whitelisting

To safeguard your applications, it is crucial to verify the source of the webhook before processing any data. Affinity will only send webhooks from the IP addresses listed below:

34.254.168.1
52.31.149.217

These IP addresses are valid for both your production and staging environments

Webhook data

	Name	Type
1.	`virtualAccountNumber`	string
2.	`amount`	number`<double>`
3.	`expiryType`	string ENUM: `SINGLE_USE` `MULTI_USE` `"DEDICATED"`
4.	`partnerReference`	string
5.	`settlementAccountNumber`	string
6.	`transactionStatus`	string
7.	`transactionDate`	string
8.	`narration`	string
9.	`payerAccountName`	string
10.	`payerBank`	string
11.	`payerAccountNumber`	string

Sample webhook data

{
  "virtualAccountNumber": "string",
  "amount": 0,
  "expiryType": "SINGLE_USE",
  "partnerReference": "string",
  "settlementAccountNumber": "string",
  "transactionStatus": "SUCCESS",
  "transactionDate": "2024-10-04T16:21:37.634Z",
  "narration": "string",
  "payerAccountName": "string",
  "payerBank": "string",
  "payerAccountNumber": "string",
  "gipSessionId": "string"}

Last modified: 27 August 2025