API Reference

Wave Business APIs provide a programmatic means to work with your Wave business account. By using these REST APIs you can receive payments, send money to your clients, check the balance on your wallet and perform automated reconciliation.

To use these APIs, you need a Wave Business Account.

• Balance & Reconciliation API
• Checkout API
• Payout API
• Aggregated Merchants API
• Webhooks

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:

Rate limiting

Wave APIs are rate limited to prevent abuse that would degrade performance for all users. If you send many requests in a short period of time, you may receive 429 error responses.

Requests

Here's an example of how you can construct a POST request with Authorization and Content-Type headers and JSON data:

curl \
-X POST \
-H 'Authorization: Bearer wave_sn_prod_YhUNb9d...i4bA6' \
-H 'Content-Type: application/json' \
-d '{
      "amount": "1000",
      "currency": "XOF",
      "error_url": "https://example.com/error",
      "success_url": "https://example.com/success"
    }' \
https://api.wave.com/v1/checkout/sessions

const axios = require('axios');

axios.post('https://api.wave.com/v1/checkout/sessions', {
  amount: "1000",
  currency: "XOF",
  error_url: "https://example.com/error",
  success_url: "https://example.com/success"
}, {
  headers: {
    'Authorization': 'Bearer wave_sn_prod_YhUNb9d...i4bA6',
    'Content-Type': 'application/json'
  }
})
.then(response => {
  console.log(response.data);
})
.catch(error => {
  console.error(error);
});

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.wave.com/v1/checkout/sessions",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    "amount" => "1000",
    "currency" => "XOF",
    "error_url" => "https://example.com/error",
    "success_url" => "https://example.com/success"
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer wave_sn_prod_YhUNb9d...i4bA6",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);

curl_close($curl);
echo $response;

import okhttp3.*;
import org.json.JSONObject;

public class Main {
  public static void main(String[] args) {
    OkHttpClient client = new OkHttpClient().newBuilder().build();
    MediaType mediaType = MediaType.parse("application/json");
    RequestBody body = RequestBody.create(mediaType, new JSONObject()
      .put("amount", "1000")
      .put("currency", "XOF")
      .put("error_url", "https://example.com/error")
      .put("success_url", "https://example.com/success")
      .toString());
    Request request = new Request.Builder()
      .url("https://api.wave.com/v1/checkout/sessions")
      .method("POST", body)
      .addHeader("Authorization", "Bearer wave_sn_prod_YhUNb9d...i4bA6")
      .addHeader("Content-Type", "application/json")
      .build();
    try {
      Response response = client.newCall(request).execute();
      System.out.println(response.body().string());
    } catch (Exception e) {
      e.printStackTrace();
    }
  }
}

Wave API requests use HTTP bearer authorization and, for those with a body, JSON format and UTF-8 encoding. All requests should be sent with HTTPS.

Methods

Wave API requests use the HTTP GET or POST methods.

The GET method is used to retrieve resources. GET requests are idempotent and will not change any data on the server.

The POST method is used to create new resources.

Headers

For authentication, the Authorization header must be included in the request. The value consists of the auth scheme, Bearer followed by the api key:

Authorization: Bearer <API key>

For requests which include a body, the Content-Type header must specify that the body is JSON:

Content-Type: application/json

Body

Some Wave API requests include data. That data must be in JSON format and use UTF-8 encoding.

Responses

Wave API responses use HTTP status codes to indicate whether a request has been completed successfully. 2xx codes indicate that the request was successful received, understood and accepted. 4xx codes signal a problem with the request from the client and 5xx codes indicate a problem on the server end. See Errors for more information about error responses.

For a response to a successful API request, the message body contains information provided by the server in JSON format (using UTF-8 encoding).

For a response to an unsuccessful request, the message body includes details about the error in JSON format (using UTF-8 encoding). Minimally, this includes a short error code and a longer user-readable message describing the reason for the failure.

Errors

When an API request cannot be completed successfully, the response provides information about the failure in the message body and in the HTTP status code.

Error details

Here's what the message body of a response to an invalid request might look like:

{
  "code": "request-validation-error",
  "message": "Request invalid",
  "details": [{
    "loc": ["payments", 1, "mobile"],
    "msg": "field required"
  }]
}

In response to unsuccessful requests, Wave provides details about the error in the message body. This includes, minimally, a short code and longer user-readable message describing the error. For validation errors, Wave may also provide details of what failed including the field that failed validation and the problem with it.

Status codes

The general reason for the failure is reflected in the HTTP response status code. 4xx codes signal a problem with the request from the client and 5xx codes indicate a problem on the server end. Specific details of the problem are provided in the message body.

Some of the status codes we return are listed below.

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.