Transient Virtual Accounts

Transient virtual accounts are short-lived virtual accounts that are automatically closed after an expiry period, set by the client. These endpoints allow you to create and manage transient virtual accounts.

Create Transient Virtual Account

POST /v1/api/virtual-accounts/transient

This endpoint is used to create a transient virtual account.

Parameters

Field	Mandatory	Parameter Type	Data Type	Description
api-key	Yes	Header	String	The client’s API key
secret	Yes	Header	String	The client's secret key for the environment to which the request is being made
requestReference	Yes	Body	String	A unique identifier for the request
timeToLive	Yes	Body	String	The number of seconds before the account expires
amount	No	Body	Numeric	This field should only be passed when the account is meant to receive a particular amount (kobo). Ensure to pass the exact amount you want the account to receive. If the account is meant to receive any amount, pass null. (For example, if the account is meant to receive 2,000 naira, pass 200000 (kobo), any other amount will be rejected)
IsSinglePayment	No	Body	Boolean	This should be set to ‘true’ if the account should expire after receiving a single payment regardless of expiry time of the account (timeToLive)

Sample Request

curl --location '{BASE_URL}/v1/api/virtual-accounts/transient' \ --header 'secret: {SECRET_KEY}' \ --header 'api-key: {API_KEY}' \ --header 'Content-Type: application/json' \ --data '{ "requestReference": "00000001", "timeToLive": "60" }'

Sample Response (201 - Created)

{
    "status": "SUCCESS",
    "message": "Operation successful.",
    "statusCode": "00",
    "data": {
        "requestReference": "00000001",
        "id": "942be374-8367-46f1-aaa8-e6a838034fcd",
        "accountNumber": "9000001277"
    }
}

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 Transient Virtual Account

PUT /v1/api/virtual-accounts/transient

This endpoint is used to update a transient virtual account.

Parameters

Field	Mandatory	Parameter Type	Data Type	Description
api-key	Yes	Header	String	The client’s API key
secret	Yes	Header	String	The client's secret key for the environment to which the request is being made
accountNumber	Yes	Path	String	The account number of the account to be updated
blockStatus	No	Body	Boolean	A flag for blocking the account. If true, the account is blocked. If false, the account is unblocked

Sample Request

curl --location --request PUT '{BASE_URL}/api/v1/virtual-accounts/transient/{accountNumber}' \ --header 'api-key: {API_KEY}' \ --header 'secret: {SECRET_KEY}' \ --header 'Content-Type: application/json' \ --data '{ "blockStatus": false }'

Sample Response (200 - OK)

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

Sample Response (400 - Bad Request)

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

Get Single Transient Virtual Account

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

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

Parameters

Field	Mandatory	Parameter Type	Data Type	Description
api-key	Yes	Header	String	The client’s API key
secret	Yes	Header	String	The client's secret key for the environment to which the request is being made
accountNumber	Yes	Path	String	The account number of the account number being retrieved

Sample Request

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

Sample Response (200 - OK)

{
    "status": "SUCCESS",
    "message": "Operation successful.",
    "statusCode": "00",
    "data": {
        "accountBalance": 1000000,
        "accountNumber": "9000001284",
        "accountName": "9JAPAY TEMP TEST 02",
        "businessId": "fcf6bc04-60c4-4e53-818f-957f046bd45e",
        "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 Transient Virtual Accounts

GET /v1/api/virtual-accounts/transient

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

Parameters

Field	Mandatory	Parameter Type	Data Type	Description
api-key	Yes	Header	String	The client’s API key
secret	Yes	Header	String	The client's secret key for the environment to which the request is being made
page-size	Yes	Query	Integer	The number of items or records to return per page
page-number	Yes	Query	Integer	The 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": 14,
    "status": "SUCCESS",
    "message": "Operation successful.",
    "statusCode": "00",
    "data": [
        {
            "accountNumber": "9000001796",
            "accountName": "PRINCESS IBIRONKE05",
            "businessId": "f13a542c-362e-41ce-a217-7f1ec2f8c53c",
            "status": "Closed"
        },
        {
            "accountNumber": "9000001789",
            "accountName": "PRINCESS IBIRONKE05",
            "businessId": "f13a542c-362e-41ce-a217-7f1ec2f8c53c",
            "status": "Closed"
        },
        {
            "accountNumber": "9000001765",
            "accountName": "PRINCESS IBIRONKE06",
            "businessId": "f13a542c-362e-41ce-a217-7f1ec2f8c53c",
            "status": "Closed"
        }
    ]
}

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"
}