Balance & Reconciliation API

The Balance API provides a programmatic means to retrieve the balance and list all the transactions processed by your Wave Business Wallet. With this API you will be able to easily do automated daily reconciliation, setup balance alerts, issue refunds and more.

For real time notifications about the payments received by your account, you should not use this API, but Webhooks.

ENDPOINTS:

GET /v1/balance
GET /v1/transactions
POST /v1/transactions/:transaction_id/refund

Base URL

All the endpoint paths referenced in the API document are relative to a base URL, https://api.wave.com.

Authentication

Authenticating to the API is done via API keys. These keys are bound to a single business wallet and can only interact with it.

If you need to interact with more than one wallet in your network, then you will have to obtain one key per wallet.

Each request must be sent over HTTPS and contain an authorization header specifying the bearer scheme with the api key:

Authorization: Bearer wave_sn_prod_YhUNb9d...i4bA6

Note that the actual key is much longer but for documentation purposes most of the characters have been replaced by an ellipses.

Obtaining your API key

You can manage API keys in the developer's section in the Wave Business Portal. You can create, view, and revoke keys, and define which specific APIs each key has access to.

When you create a new API key, you will only see the full key once. Make sure you copy it without missing any characters, since it will be masked afterwards for security reasons.

Wave doesn't know your full key, but if you contact API support we can identify them by the last 4 letters that you see displayed in the business portal.

Error codes

In the authentication phase, one of the following errors can cause your request to return early:

Types

Some of the parameters in Wave API requests or attributes in API objects follow specific data formats.

Amounts

All amounts are represented as strings. When the amount includes decimal places, the separator is a period (.). The following rules apply to valid amounts:

• Include between zero and two decimal places. (See Currency for the maximum number of allowed decimal places for each currency.)
• No leading zeroes where the value is one or greater.
• One leading zero where the value is less than one.
• May include trailing zeroes.
• Must be positive for requests. May be zero or negative in object attributes.

Currency

Standard ISO 4217 three-letter codes in upper case are used to specify currency. The code for the West African Franc is XOF. Decimal places are not allowed for XOF currency amounts.

Timestamps

Timestamp values follow the ISO 8601 standard. Timestamps that we provide in API objects will be of the form YYYY-MM-DDThh:mm:ssZ where the Z indicates the UTC time zone.

Transaction Type

The Balance object

BALANCE OBJECT

{
  "amount": "10245",
  "currency": "XOF"
}

The Balance object represents the amount of money in a Wave wallet.

Attributes

amount string
Balance amount.

currency currency
Three-letter ISO 4217 currency code.

API

Retrieve balance

GET /v1/balance

Retrieves the current balance of the account associated with the API key used to make the request.

curl \
-H 'Authorization: Bearer wave_sn_prod_YhUNb9d...i4bA6' \
https://api.wave.com/v1/balance

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.wave.com/v1/balance",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer wave_sn_prod_YhUNb9d...i4bA6"
  ],
]);

$response = curl_exec($curl);

curl_close($curl);
echo $response;

const axios = require('axios');

axios.get('https://api.wave.com/v1/balance', {
  headers: {
    'Authorization': 'Bearer wave_sn_prod_YhUNb9d...i4bA6'
  }
})
.then(response => {
  console.log(response.data);
})
.catch(error => {
  console.error(error);
});

HttpResponse<String> response = Unirest.get("https://api.wave.com/v1/balance")
.header("Authorization", "Bearer wave_sn_prod_YhUNb9d...i4bA6")
.asString();

System.out.println(response.getBody());

Parameters

URL parameters are passed in the form of https://api.wave.com/v1/balance?include_subaccounts=true.

Returns

Returns a balance object for the account associated with the API key used to make the request.

Retrieve your transactions

GET /v1/transactions

Returns a list of transactions of your account for a given day. Uses pagination if the number of transactions exceeds 1000 entries. The transactions are ordered from older to newer.

curl -X GET \
  --url https://api.wave.com/v1/transactions?date=2022-10-25 \
  -H 'Authorization: Bearer wave_sn_prod_YhUNb9d...i4bA6'

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.wave.com/v1/transactions?date=2022-10-25",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer wave_sn_prod_YhUNb9d...i4bA6"
  ],
]);

$response = curl_exec($curl);

curl_close($curl);
echo $response;

const axios = require('axios');

axios.get('https://api.wave.com/v1/transactions?date=2022-10-25', {
  headers: {
    'Authorization': 'Bearer wave_sn_prod_YhUNb9d...i4bA6'
  }
})
.then(response => {
  console.log(response.data);
})
.catch(error => {
  console.error(error);
});

HttpResponse<String> response = Unirest.get("https://api.wave.com/v1/transactions?date=2022-10-25")
.header("Authorization", "Bearer wave_sn_prod_YhUNb9d...i4bA6")
.asString();
System.out.println(response.getBody());

Example response

{
  "page_info": {
    "start_cursor": null,
    "end_cursor": "TFRfdUZ1MGoyMzVKemtz",
    "has_next_page": true
  },
  "date": "2022-11-07",
  "items": [
    {
      "timestamp": "2022-11-07T14:41:15Z",
      "transaction_id": "T_V3TFOUE7VU",
      "amount": "99",
      "fee": "1",
      "currency": "XOF",
      "counterparty_name": "Mame Diop",
      "counterparty_mobile": "+221761110000"
    },
    {
      "timestamp": "2022-11-07T14:42:06Z",
      "transaction_id": "T_2YJNPWMCIY",
      "amount": "99",
      "fee": "1",
      "currency": "XOF",
      "counterparty_name": "Fatou Ndiaye",
      "counterparty_mobile": "+221761110001"
    },
    {
      "timestamp": "2022-11-07T14:42:41Z",
      "transaction_id": "T_2YJNPWMCIY",
      "amount": "-99",
      "fee": "-1",
      "currency": "XOF",
      "is_reversal": true
    },
    {
      "timestamp": "2022-11-07T14:42:54Z",
      "transaction_id": "pt-1azcvz4081002",
      "amount": "-101",
      "fee": "1",
      "currency": "XOF",
      "counterparty_name": "Moustapha Mbaye",
      "counterparty_mobile": "+221761110519"
    },
    {
      "timestamp": "2022-11-07T14:43:00Z",
      "transaction_id": "pt-1azcw0qkg1004",
      "amount": "-121",
      "fee": "1",
      "currency": "XOF",
      "counterparty_name": "Moustapha Mbaye",
      "counterparty_mobile": "+221761110519"
    },
    {
      "timestamp": "2022-11-07T14:43:14Z",
      "transaction_id": "pt-1azcw0qkg1004",
      "amount": "121",
      "fee": "1",
      "currency": "XOF",
      "counterparty_name": "Moustapha Mbaye",
      "counterparty_mobile": "+221761110519",
      "is_reversal": true
    }
  ]
}

Request parameters

URL parameters are passed in the form of https://api.wave.com/v1/transactions?date=value1&after=value2.

Return attributes

Refund a transaction

POST /v1/transactions/:transaction_id/refund

With this endpoint you can reverse a payment received, including fees. You don't need to indicate a reason, you can simply refund your customers any time you deem necessary.

curl -X POST \
  -L https://api.wave.com/v1/transactions/T_VZSWJF5MMQ/refund \
  -H 'Authorization: Bearer wave_sn_prod_YhUNb9d...i4bA6'

Example response

HTTP 200 OK

Request parameters

There are no parameters necessary in the request body. Note that the transaction_id is passed in the request path.

Response body

There is no response body. The status code will inform you whether a refund was successful (200), or the transaction doesn't exist (404), or something else went wrong (500).

Pagination

Many of Wave's listing endpoints support pagination. If you are using a paginated endpoint, you must be prepared to accept paginated responses and continue making requests until no items remain or you have retrieved all of the data your application needs.

Paginated request

Paginated endpoints currently only support forward pagination. Backward pagination is not yet supported.

Example paginated request

curl -X GET \
  --url 'https://api.wave.com/v1/paginated-endpoint?first=10&after=YzE6YW0tMWFrbjhkeWcwMTAwOA'

For pagination, you may use the following query parameters:

Paginated response

Example paginated response

{
    "page_info": {
        "has_next_page": true,
        "end_cursor": "YzE6YW0tMWFrbjhkeWcwMTAwOA"
    },
    "items": [
        {
            "id": "xyz-bm29dahzl",
            "name": "Item 1"
        }
    ]
}

A paginated response contains pagination information and a list of items. The specific item type is endpoint-dependent.

Page Info object

The page info object contains information related to the current page of results, and a cursors that can be used to retrieve the next page.

Example pagination request flow

Example initial request

curl -X GET \
  --url 'https://api.wave.com/v1/paginated-endpoint?first=10' \
  -H 'Authorization: Bearer wave_sn_prod_YhUNb9d...i4bA6'

Example initial response

{
    "page_info": {
        "has_next_page": true,
        "end_cursor": "YzE6YW0tMWFrbjhkeWcwMTAwOA"
    },
    "items": [
      ...
    ]
}

As an example, we can retrieve items from an endpoint, ten items at a time.

Note: The first query parameter is optional if we don't care about the precise number of items being retrieved. The server will choose a sensible default for the collection being retrieved.

Example next-page request

curl -X GET \
  --url 'https://api.wave.com/v1/paginated-endpoint?first=10&after=YzE6YW0tMWFrbjhkeWcwMTAwOA' \
  -H 'Authorization: Bearer wave_sn_prod_YhUNb9d...i4bA6'

Example next-page response

{
    "page_info": {
        "has_next_page": false,
        "end_cursor": "YzE6YW0tMWFrbjhkeWc6iNNoqP"
    },
    "items": [
      ...
    ]
}

When the response's page_info.has_next_page is true, more items remain to be retrieved. We can request another page of items using the page_info.end_cursor as our after query parameter.

Because this response has returned page_info.has_next_page as false, no items remain to be retrieved, and no further requests should be made. However, if page_info.has_next_page had been true, we could have again used the value of page_info.end_cursor as the value of our after query parameter to continue retrieving items.

Changelog

2024-03-29

Removes override_business_name details from the Checkout API

2022-10-17

Added aggregated_merchant_id details to the Checkout API.

2022-05-10

The Checkout API now validates decimal places following the rules described in the Amount section.

2022-03-29

Adds override_business_name details to Checkout API

2022-03-23

Initial release of Checkout and Balance APIs.