🫓Status & Responses

This explains the payload response and statuses returned by our API endpoints. These are commonly seen when consuming our endpoints. Note, these applies mostly on every endpoint.

General Response Structure

{
    "error": false,
    "errors": [],
    "data": {},
    "message": "",
    "status": 200
}

The response data structure is exactly the same for every response on our API call. Find the description below

Property	Data Type	Description	Example
error	boolean	Indicates if there is an error on the response or not. This can either be true or false	false
errors	array of strings	This array contains strings of error descriptions if error above is true	["error"]
data	object or array	This contains response data as an object or an array	{ name: "to" }
message	string	The response message	"successful"
status	number	The response status code	200

Pagination Data response

When API requests are made to retrieve a list of data ( ex. a list of banks ), the response comes with pagination information that can help you navigate the list. Below is an example of a response when a list of banks is requested.

{
    "error": false,
    "errors": [],
    "count": 1,
    "total": 533,
    "pagination": {
        "next": {
            "page": 3,
            "limit": 1
        },
        "prev": {
            "page": 1,
            "limit": 1
        }
    },
    "data": [
        {
            "name": "Polaris Bank",
            "code": "076",
            "country": "nigeria",
            "currency": "NGN",
            "isEnabled": true,
            "type": "nuban",
            "createdAt": "2024-01-20T09:21:39.261Z",
            "updatedAt": "2024-01-20T09:21:39.261Z"
        }
    ],
    "message": "successful",
    "status": 200
}

More about Pagination Read more about how to navigate lists with Vacepay pagination here

Transaction Status Descriptions

Status	Description	Recommended Action
pending	Transaction is in progress and pending completion	You can query the verify transaction endpoint to check the status of the transaction.
processing	A partial payment has been made on the transaction	You can query the verify transaction endpoint or wait till the transaction is completed.
successful / completed	Transaction has been processed successfully	Mark transaction as successful on your end
refunded	The transaction value has been refunded. This is usually linked to another transaction that tracks if the refund is successful.	Mark transaction as refunded and check the linked transaction to know the status of the refund.
cancelled	Transaction was cancelled. This means transaction was not processed at all.	Mark transaction as cancelled on your end.
failed	Transaction was processed but failed.	Mark transaction as failed. Initiate a refund or reach out to us as the case may be.

Transaction Feature Descriptions

Feature	Description
bank-account	This indicates that your wallet was funded via your Terraswitch virtual account number.
wallet-transfer	This means you send money from your wallet to a Terraswitch user or an NGN bank account
wallet-withdraw	This means you withdraw money from your wallet to your NGN bank account
wallet-airtime	This means you bought airtime via your Terraswitch wallet
wallet-data	This means your purchased data via your Terraswitch wallet
wallet-bill	This means you made a bill payment via your Terraswitch wallet
wallet-refund	This means you initiated a refund to an NGN bank account and indicated that the refund be via your Terraswitch wallet.
api-refund	This means you initiated a refund and specified that you want Terraswitch to handle the refund on your behalf.
wallet-chargeback	This transaction is a chargeback initiated by Terraswitch on your account on Terraswitch.
payment-link	This is a transaction created via any payment link on your Terraswitch account.
internal-credit	This transaction is created on your account because another Terraswitch user sends money to your Terraswitch wallet.
internal-debit	This transaction is created when you send money to another Terraswitch user via their phone number.

Invoice Status Description

Status	Description	Recommended Action
pending	The invoice was just created and has not been paid for.	Copy and share the invoice link with your customer/client
paid	The invoice has been paid for and no payment can be made on the invoice again	Mark invoice as paid
overdue	The due date on invoice has passed	Mark invoice as overdue and send a reminder to your customer/client.
failed	The payment attempt on the invoice failed. Another payment can be made at this point	inform your client to try and make a payment again.