Skip to main content

Permanent Virtual Accounts

Permanent virtual accounts are long-lived virtual accounts that remain open until they are intentionally closed by the client. These endpoints allow you to create and manage permanent virtual accounts.

Create Permanent Virtual Account​

POST /v1/api/virtual-accounts/permanent

This endpoint is used to create a permanent virtual account.

Parameters​

FieldMandatoryParameter TypeData TypeDescription
api-keyYesHeaderStringThe client’s API key
secretYesHeaderStringThe client's secret key for the environment to which the request is being made
requestReferenceYesBodyStringA unique identifier for the request
accountNameYesBodyStringThe name of the account to be created
autoPayoutEnabledYesBodyBooleanIndicates whether deposits into the virtual account should be automatically transferred to the client’s collection account.
Note: The transfer happens when the webhook of the transaction is acknowledged with a 200 OK.

Sample Request​

curl --location '{BASE_URL}/v1/api/virtual-accounts/permanent' \ --header 'api-key: {API_KEY}' \ --header 'secret: {SECRET_KEY}' \ --header 'Content-Type: application/json' \ --data '{ "requestReference": "74a583d0-1be3-4862-8613-8297d4ec2037", "accountName": "PERMANENT ACCOUNT NAME 01", "autoPayoutEnabled": true }'

Sample Response (201 - Created)​

{
    "status": "SUCCESS",
    "message": "Operation successful.",
    "statusCode": "00",
    "data": {
        "requestReference": "74a583d0-1be3-4862-8613-8297d4ec2037",
        "id": "4d971299-0095-468f-9903-551ee764e329",
        "accountNumber": "9000002133"
    }
}

Sample Response (400 - Bad Request)​

{
  "status": "FAILED",
  "message": "Request Reference can only contain alphanumeric characters.",
  "statusCode": "09"
}

Sample Response (409 - Conflict)​

{
    "status": "FAILED",
    "message": "Duplicate record found.",
    "statusCode": "26"
}

Update Permanent Virtual Account​

PATCH /v1/api/virtual-accounts/permanent

This endpoint is used to update a permanent virtual account.

Parameters​

FieldMandatoryParameter TypeData TypeDescription
api-keyYesHeaderStringThe client’s API key
secretYesHeaderStringThe client's secret key for the environment to which the request is being made
accountNumberYesPathStringThe account number of the account to be updated
accountNameNoBodyStringThe new account name
blockStatusNoBodyBooleanA flag for blocking the account. If true, the account is blocked. If false, the account is unblocked
autoPayoutEnabledNoBodyBooleanIndicates whether deposits into the virtual account should be automatically transferred to the client’s collection account.
Note: The transfer happens when the webhook of the transaction is acknowledged with a 200 OK.

Sample Request​

curl --location --request PATCH '{BASE_URL}/api/v1/virtual-accounts/permanent/{accountNumber}' \ --header 'api-key: {API_KEY}' \ --header 'secret: {SECRET_KEY}' \ --header 'Content-Type: application/json' \ --data '{ "accountName": "MICHAEL JORDAN 24", "blockStatus": false, "autoPayoutEnabled": true  }'

Sample Response (200 - OK)​

{
    "status": "SUCCESS",
    "message": "Operation successful.",
    "statusCode": "00",
    "data": {
        "accountNumber": "9000002425",
        "accountName": "MICHAEL JORDAN 24",
        "businessId": "5f80c1cd-0c14-43dd-8cf7-e316c05b696a",
		"autoPayoutEnabled": true,
        "status": "Active"
    }
}

Sample Response (400 - Bad Request)​

{
    "status": "FAILED",
    "message": "Account Number must have a length of 10 characters.",
    "statusCode": "09"
}

Get Single Permanent Virtual Account​

GET /v1/api/virtual-accounts/permanent/{account_number}

This endpoint is used to retrieve the details of a permanent virtual account.

Parameters​

FieldMandatoryParameter TypeData TypeDescription
api-keyYesHeaderStringThe client’s API key
secretYesHeaderStringThe client's secret key for the environment to which the request is being made
accountNumberYesPathStringThe account number of the account number being retrieved

Sample Request​

curl --location '{BASE_URL}/v1/api/virtual-accounts/permanent/{account_number}' \ --header 'secret: {SECRET_KEY}' \ --header 'api-key: {API_KEY}'

Sample Response (200 - OK)​

{
    "status": "SUCCESS",
    "message": "Operation successful.",
    "statusCode": "00",
    "data": {
        "accountBalance": 0,
        "accountNumber": "9000001222",
        "accountName": "9JAPAY 01",
        "businessId": "fcf6bc04-60c4-4e53-818f-957f046bd45e",
				"accountName": "9JAPAY 01",
				"autoPayoutEnabled": true
        "status": "Closed"
    }
}

Sample Response (400 - Bad Request)​

{
    "status": "FAILED",
    "message": "Account Number must have a length of 10 characters.",
    "statusCode": "09"
}

Sample Response (404 - Not found)​

{
    "status": "FAILED",
    "message": "No record found.",
    "statusCode": "25"
}

Get All Permanent Virtual Accounts​

GET /v1/api/virtual-accounts/permanent

This endpoint is used to retrieve a paginated list of all the client’s permanent virtual accounts.

Parameters​

FieldMandatoryParameter TypeData TypeDescription
api-keyYesHeaderStringThe client’s API key
secretYesHeaderStringThe client's secret key for the environment to which the request is being made
page-sizeYesQueryIntegerThe number of items or records to return per page
page-numberYesQueryIntegerThe page number of the request

Sample Request​

curl --location '{BASE_URL}/v1/api/virtual-accounts/permanent?page-size=3&page-number=1' \ --header 'secret: {SECRET_KEY}' \ --header 'api-key: {API_KEY}'

Sample Response (200 - OK)​

{
    "totalCount": 31,
    "status": "SUCCESS",
    "message": "Operation successful.",
    "statusCode": "00",
    "data": [
        {
            "accountNumber": "9000001806",
            "accountName": "Everrich CO",
            "businessId": "f13a542c-362e-41ce-a217-7f1ec2f8c53c",
						"autoPayoutEnabled": true
            "status": "Closed"
        },
        {
            "accountNumber": "9000001772",
            "accountName": "TEST QUEEN3",
            "businessId": "f13a542c-362e-41ce-a217-7f1ec2f8c53c",
		"autoPayoutEnabled": true,
            "status": "Active"
        },
        {
            "accountNumber": "9000001758",
            "accountName": "TEST QUEEN2",
            "businessId": "f13a542c-362e-41ce-a217-7f1ec2f8c53c",
						"autoPayoutEnabled": true
            "status": "Active"
        }
    ]
}

Sample Response (400 - Bad Request)​

{
    "status": "FAILED",
    "message": "Page Number must be an integer.",
    "statusCode": "09"
}

Sample Response (404 - Not found)​

{
    "status": "FAILED",
    "message": "No record found.",
    "statusCode": "25"
}

Close Permanent Virtual Account​

DELETE /v1/api/virtual-accounts/permanent

This endpoint is used to close a permanent virtual account.

Parameters​

FieldMandatoryParameter TypeData TypeDescription
api-keyYesHeaderStringThe client’s API key
secretYesHeaderStringThe client's secret key for the environment to which the request is being made
requestReferenceYesBodyStringA unique identifier for the request
accountNumberYesBodyStringThe account number of the account being closed
reasonForClosureYesBodyStringThe reason for closing the account

Sample Request​

curl --location --request DELETE '{BASE_URL}/v1/api/virtual-accounts/permanent' \ --header 'secret: {SECRET_KEY}' \ --header 'api-key: {API_KEY}' \ --header 'Content-Type: application/json' \ --data '{ "requestReference": "74a583d0-1be3-4862-8613-8297d4ec2037", "accountNumber": "9000002133", "reasonForClosure": "CUSTOMER REQUEST" }'

Sample Response (200 - OK)​

{
    "status": "SUCCESS",
    "message": "Operation successful.",
    "statusCode": "00"
}

Sample Response (400 - Bad Request)​

{
    "status": "FAILED",
    "message": "Reason For Closure is required.",
    "statusCode": "09"
}

Sample Response (409 - Conflict)​

{
    "status": "FAILED",
    "message": "Duplicate record found.",
    "statusCode": "26"
}

Sample Response (404 - Not found)​

{
    "status": "FAILED",
    "message": "This virtual account has already been closed.",
    "statusCode": "25"
}