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.

Request signing

Request signing allows you to prove the integrity of your API requests. When enabled, each request must include a Wave-Signature header containing a timestamp and an HMAC-SHA256 signature of the request body.

Request signing is optional. When you create an API key with request signing enabled, a signing secret is generated and shown to you once. After that, all requests made with that API key must include a valid Wave-Signature header.

Enabling request signing

When creating a new API key in the Wave Business Portal, select the option to enable request signing. You will receive a signing secret in the format:

wave_sn_AKS_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

Constructing the signature

To sign a request, you must:

1. Get the current time as a Unix timestamp (integer seconds).
2. Construct the payload by concatenating the timestamp with the raw request body (i.e. timestamp + body).
3. Compute the HMAC-SHA256 of the payload using your signing secret as the key.
4. Set the Wave-Signature header to t={timestamp},v1={signature}.

Example Wave-Signature header:

Wave-Signature: t=1639081943,v1=942119aedf9fa377844cf010785fe14ef8478c72af0b73d62ea3941335b526a8

The Wave-Signature header consists of a timestamp prefixed by t= and a signature prefixed by v1=, separated by a comma.

Signature generation examples

# Generate the signature and make a signed request
TIMESTAMP=$(date +%s)
BODY='{"amount": "1000", "currency": "XOF"}'
SIGNING_SECRET="wave_sn_AKS_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"

SIGNATURE=$(printf '%s%s' "$TIMESTAMP" "$BODY" \
  | openssl dgst -sha256 -hmac "$SIGNING_SECRET" \
  | sed 's/^.* //')

curl -X POST \
  -H "Authorization: Bearer wave_sn_prod_YhUNb9d...i4bA6" \
  -H "Wave-Signature: t=${TIMESTAMP},v1=${SIGNATURE}" \
  -H "Content-Type: application/json" \
  -d "$BODY" \
  https://api.wave.com/v1/checkout/sessions

<?php
$api_key = "wave_sn_prod_YhUNb9d...i4bA6";
$signing_secret = "wave_sn_AKS_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX";

$body = json_encode([
    "amount" => "1000",
    "currency" => "XOF",
]);

$timestamp = time();
$signature = hash_hmac("sha256", $timestamp . $body, $signing_secret);
$wave_signature = "t={$timestamp},v1={$signature}";

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, "https://api.wave.com/v1/checkout/sessions");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, $body);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "Authorization: Bearer {$api_key}",
    "Wave-Signature: {$wave_signature}",
    "Content-Type: application/json",
]);

$result = curl_exec($ch);
curl_close($ch);
?>

const crypto = require('crypto');
const axios = require('axios');

const apiKey = "wave_sn_prod_YhUNb9d...i4bA6";
const signingSecret = "wave_sn_AKS_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX";

const body = JSON.stringify({
  amount: "1000",
  currency: "XOF",
});

const timestamp = Math.floor(Date.now() / 1000);
const payload = timestamp + body;
const signature = crypto.createHmac('sha256', signingSecret).update(payload).digest('hex');
const waveSignature = `t=${timestamp},v1=${signature}`;

axios.post("https://api.wave.com/v1/checkout/sessions", body, {
  headers: {
    "Authorization": `Bearer ${apiKey}`,
    "Wave-Signature": waveSignature,
    "Content-Type": "application/json",
  },
});

import java.nio.charset.StandardCharsets;
import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;

public class WaveRequestSigner {
    private static final byte[] HEX_ARRAY = "0123456789abcdef".getBytes(StandardCharsets.US_ASCII);

    public static String sign(String body, String signingSecret) throws Exception {
        long timestamp = System.currentTimeMillis() / 1000;
        String payload = timestamp + body;

        Mac sha256Hmac = Mac.getInstance("HmacSHA256");
        SecretKeySpec secretKey = new SecretKeySpec(
            signingSecret.getBytes(StandardCharsets.UTF_8), "HmacSHA256");
        sha256Hmac.init(secretKey);
        byte[] hash = sha256Hmac.doFinal(payload.getBytes(StandardCharsets.UTF_8));

        String signature = bytesToHex(hash);
        return "t=" + timestamp + ",v1=" + signature;
    }

    private static String bytesToHex(byte[] bytes) {
        byte[] hexChars = new byte[bytes.length * 2];
        for (int j = 0; j < bytes.length; j++) {
            int v = bytes[j] & 0xFF;
            hexChars[j * 2] = HEX_ARRAY[v >>> 4];
            hexChars[j * 2 + 1] = HEX_ARRAY[v & 0x0F];
        }
        return new String(hexChars, StandardCharsets.UTF_8);
    }
}

Timestamp validation

Wave validates that the signature timestamp is recent to prevent replay attacks. Requests are rejected if:

• The timestamp is more than 5 minutes in the past.
• The timestamp is more than 30 seconds in the future (to allow for minor clock skew).

Ensure your server's clock is reasonably synchronized.

Signed request for GET endpoints

For GET requests that have no body, use an empty string as the body when constructing the signature payload. That is, the payload is just the timestamp string.

Error codes

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

IP Whitelisting

IP whitelisting restricts API access to requests originating from specific, pre-approved IP addresses. Even if an API key is compromised, requests from unrecognized IPs are rejected; adding a second layer of defense on top of key-based authentication.

This helps meet financial-services compliance requirements and gives internal teams tighter control over which servers can reach Wave's APIs.

How It Works

IP whitelisting works alongside API key authentication. When a request hits the API, three checks happen in order:

1. API key validation: Is the API key valid?
2. Enforcement check: Is IP whitelisting enabled for this wallet?
3. IP validation: Does the request's source IP match an entry in the whitelist?

All three must pass for the request to succeed.

Configuration

IP whitelisting is managed in the Wave Business Portal under the Developer section.

Supported Formats

You can whitelist a single IP or a CIDR range:

Validation Rules

The system enforces the following constraints:

Managing Entries

The portal lets you view all active whitelist entries, including labels and who created each one (created_by). Each entry should have a clear label describing the server, environment or purpose. This makes future audits much easier.

Error Handling

Requests from non-whitelisted IPs receive a 403 response:

{
  "error": {
    "code": "ip-not-allowed",
    "message": "Request from IP address not in allowlist",
    "httpcode": 403
  }
}

Best Practices

Use static IPs. Dynamic IPs that rotate will break your integration. In cloud environments (AWS, GCP), use elastic or reserved IPs.

Keep ranges narrow. Whitelist only the specific IPs that need access. A single /32 per server is ideal; resort to broader ranges only when your infrastructure requires it.

Label everything. Include the server name, environment (staging/production) or purpose. Six months from now, an unlabelled entry is an entry nobody wants to touch.

Review regularly. Decommissioned servers and old test environments accumulate. Periodically audit the whitelist and remove stale entries.

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.