Wave API

https://docs.wave.com
Admin
Wave API provides REST endpoints for mobile money operations including payment processing via...
Tokens:40,162
Snippets:347
Trust Score:9.6
Update:1 month ago
Show doc for...
Tokens:
Raw
### Search for Checkout Sessions via API

Source: https://docs.wave.com/checkout

Examples of how to perform a GET request to search for checkout sessions using various programming languages.

```shell
curl -X GET \
  --url https://api.wave.com/v1/checkout/sessions/search?client_reference=123456 \
  -H 'Authorization : Bearer wave_sn_prod_YhUNb9d...i4bA6'
```

```php
<?php

# Specify your API KEY
$api_key = "wave_sn_prod_YhUNb9d...i4bA6";

$client_reference = "123456";

# Define the request options
$curlOptions = [
  CURLOPT_URL => "https://api.wave.com/v1/checkout/sessions/search?client_reference={$client_reference}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_TIMEOUT => 5,
  CURLOPT_HTTPHEADER => [
    "Authorization : Bearer {$api_key}",
  ],
];

# Execute the request and get a response
$curl = curl_init();
curl_setopt_array($curl, $curlOptions);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
    # You can now decode the response and use the checkout session. Happy coding ;)
    $checkout_session = json_decode($response);
    var_dump($checkout_session);
}
```

```javascript
const axios = require('axios');

const api_key = "wave_sn_prod_YhUNb9d...i4bA6";
const client_reference = "123456";

axios.get('https://api.wave.com/v1/checkout/sessions/search', { params: { client_reference }, headers: { 'Authorization': `Bearer ${api_key}` } })
.then((response) => {
  const checkout_session = response.data;
  console.log(checkout_session);
})
.catch((error) => {
  console.error(error);
});
```

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

public class CheckoutSession {
  public static void main(String[] args) {
    String api_key = "wave_sn_prod_YhUNb9d...i4bA6";
    String client_reference = "123456";

    OkHttpClient client = new OkHttpClient();
    Request request = new Request.Builder()
      .url("https://api.wave.com/v1/checkout/sessions/search?client_reference=" + client_reference)
      .get()
      .addHeader("Authorization", "Bearer " + api_key)
      .build();

    try {
      Response response = client.newCall(request).execute();
      if (response.isSuccessful()) {
        JSONObject jsonResponse = new JSONObject(response.body().string());
        System.out.println(jsonResponse.toString());
      } else {
        System.out.println("Error: " + response.body().string());
      }
    } catch (Exception e) {
      e.printStackTrace();
    }
  }
}
```

--------------------------------

### Search payouts response example

Source: https://docs.wave.com/payout

Example JSON response structure for a successful payout search query.

```json
{
  "result": [
      {
        "id": "pt-185sewgm8100t",
        "currency": "XOF",
        "receive_amount": "15000",
        "fee": "150",
        "mobile": "+221555110233",
        "name": "Moustapha Mbaye",
        "national_id": "1751197904376",
        "client_reference": "FAH.4827.1734",
        "payment_reason": "Salary November 2022",
        "status": "succeeded",
        "timestamp": "2022-06-21T09:56:29Z"
        "aggregated_merchant_id": "am-7lks22ap113t4",
      }
  ]
}
```

--------------------------------

### Wave-Signature Header Example

Source: https://docs.wave.com/aggregated-merchants

An example of the Wave-Signature header containing a timestamp and HMAC-SHA256 signature.

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

--------------------------------

### Create a payout batch response example

Source: https://docs.wave.com/payout

Example JSON response containing the ID used to poll for the batch processing status.

```json
{
  "id": "pb-185skxq8g1006"
}
```

--------------------------------

### Updated Aggregated Merchant Response Example

Source: https://docs.wave.com/aggregated-merchants

Example JSON response body after successfully updating an aggregated merchant.

```json
{
    "id": "am-7lks22ap113t4",
    "name": "Moustaphas Candle Shop",
    "business_sector": null,
    "business_type": "other",
    "business_registration_identifier": null,
    "website_url": "https://example.com",
    "payout_fee_structure_name": "one_percent",
    "checkout_fee_structure_name": "one_fifty_bps",
    "manager_name": "Moustapha",
    "business_description": "A grocery store in the heart of the city.",
    "when_created": "2022-06-21T09:56:29Z",
    "is_locked": true
}
```

--------------------------------

### Aggregated Merchants Response Example

Source: https://docs.wave.com/aggregated-merchants

Example JSON response containing a list of aggregated merchant objects and pagination metadata.

```json
{
    "page_info": {
        "has_next_page": false,
        "end_cursor": "YzE6YW0tMWFrbjhkeWcwMTAwOA"
    },
    "items": [
        {
            "id": "am-7lks22ap113t4",
            "name": "Moustaphas Groceries",
            "business_sector": null,
            "business_type": "other",
            "business_registration_identifier": null,
            "website_url": "https://groceries.example.com",
            "payout_fee_structure_name": "one_percent",
            "checkout_fee_structure_name": "one_fifty_bps",
            "business_description": "A grocery store in the heart of the city.",
            "manager_name": "Moustapha",
            "when_created": "2022-06-21T09:56:29Z",
            "is_locked": true
        },
        {
            "id": "am-2rtmi4j8973vq",
            "name": "Fancy Fintech",
            "business_sector": "b2b services/integrations",
            "business_type": "fintech",
            "business_registration_identifier": "A-12234-M",
            "website_url": "https://fancy-fintech.example.com/",
            "payout_fee_structure_name": "one_fifty_bps",
            "checkout_fee_structure_name": "one_fifty_bps",
            "business_description": "A fintech company that provides payment solutions.",
            "manager_name": "Alice",
            "when_created": "2022-08-11T13:31:42Z",
            "is_locked": false
        }
    ]
}
```

--------------------------------

### Create a checkout session

Source: https://docs.wave.com/checkout

Examples for initiating a checkout session via the Wave API.

```shell
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
```

```php
<?php

# Specify your API KEY
$api_key = "wave_sn_prod_YhUNb9d...i4bA6";

$checkout_params = [
    "amount" => "1000",
    "currency" => "XOF",
    "error_url" => "https://example.com/error",
    "success_url" => "https://example.com/success",
];

# Define the request options
$curlOptions = [
  CURLOPT_URL => "https://api.wave.com/v1/checkout/sessions",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_TIMEOUT => 5,
  CURLOPT_POST => true,
  CURLOPT_POSTFIELDS => json_encode($checkout_params),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer {$api_key}",
    "Content-Type: application/json"
  ],
];

# Execute the request and get a response
$curl = curl_init();
curl_setopt_array($curl, $curlOptions);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
    # You can now decode the response and use the checkout session. Happy coding ;)
    $checkout_session = json_decode($response);

    # You can redirect the user by using the 'wave_launch_url' field.
    $wave_launch_url = $checkout_session["wave_launch_url"]
    header('Location: $wave_launch_url');
    exit;
}
```

```javascript
const axios = require('axios');

const api_key = "wave_sn_prod_YhUNb9d...i4bA6";

const checkout_params = {
  amount: "1000",
  currency: "XOF",
  error_url: "https://example.com/error",
  success_url: "https://example.com/success",
};

axios.post('https://api.wave.com/v1/checkout/sessions', checkout_params, {
  headers: {
    'Authorization': `Bearer ${api_key}`,
    'Content-Type': 'application/json',
  },
})
.then((response) => {
  // You can now use the response to redirect the user to the Wave app
  const wave_launch_url = response.data.wave_launch_url;
  window.location.href = wave_launch_url;
})
.catch((error) => {
  console.error(error);
});
```

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

public class CheckoutSession {
  public static void main(String[] args) {
    String api_key = "wave_sn_prod_YhUNb9d...i4bA6";

    OkHttpClient client = new OkHttpClient();
    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")
      .post(body)
      .addHeader("Authorization", "Bearer " + api_key)
      .addHeader("Content-Type", "application/json")
      .build();

    try {
      Response response = client.newCall(request).execute();
      if (response.isSuccessful()) {
        JSONObject jsonResponse = new JSONObject(response.body().string());
        String wave_launch_url = jsonResponse.getString("wave_launch_url");
        // Redirect the user to the Wave app
        System.out.println(wave_launch_url);
      } else {
        System.out.println("Error: " + response.body().string());
      }
    } catch (Exception e) {
      e.printStackTrace();
    }
  }
}
```

--------------------------------

### Example API response

Source: https://docs.wave.com/balance-api

A sample JSON response containing transaction items and pagination metadata.

```json
{
  "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
    }
  ]
}
```

--------------------------------

### Generate Idempotency Keys

Source: https://docs.wave.com/payout

Examples for generating unique idempotency keys across different programming languages.

```shell
openssl rand -hex 8
```

```php
$idem_key = uniqid(more_entropy: True)
```

```python
import uuid
idem_key = str(uuid.uuid4())
```

```javascript
let idem_key = crypto.randomUUID();
```

--------------------------------

### Refund a Checkout Session via Java

Source: https://docs.wave.com/checkout

This Java example uses the OkHttp library to execute the refund request.

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

public class CheckoutSession {
  public static void main(String[] args) {
    String api_key = "wave_sn_prod_YhUNb9d...i4bA6";
    String checkout_id = "cos-18qq25rgr100a";

    OkHttpClient client = new OkHttpClient();
    Request request = new Request.Builder()
      .url("https://api.wave.com/v1/checkout/sessions/" + checkout_id + "/refund")
      .post(RequestBody.create(null, new byte[0]))
      .addHeader("Authorization", "Bearer " + api_key)
      .build();

    try {
      Response response = client.newCall(request).execute();
      if (response.isSuccessful()) {
        JSONObject jsonResponse = new JSONObject(response.body().string());
        System.out.println(jsonResponse.toString());
      } else {
        System.out.println("Error: " + response.body().string());
      }
    } catch (Exception e) {
      e.printStackTrace();
    }
  }
}
```

--------------------------------

### GET /v1/checkout/sessions

Source: https://docs.wave.com/checkout

Lists all checkout sessions.

```APIDOC
## GET /v1/checkout/sessions

### Description
Lists all checkout sessions.

### Method
GET

### Endpoint
https://api.wave.com/v1/checkout/sessions
```

--------------------------------

### Aggregated Merchant Response Example

Source: https://docs.wave.com/aggregated-merchants

Example JSON response body returned by the API for an aggregated merchant.

```json
{
    "id": "am-7lks22ap113t4",
    "name": "Moustaphas Groceries",
    "business_sector": null,
    "business_type": "other",
    "business_registration_identifier": null,
    "website_url": "https://example.com",
    "payout_fee_structure_name": "one_percent",
    "checkout_fee_structure_name": "one_fifty_bps",
    "manager_name": "Moustapha",
    "business_description": "A grocery store in the heart of the city.",
    "when_created": "2022-06-21T09:56:29Z",
    "is_locked": true
}
```

--------------------------------

### Send Webhook Request via cURL

Source: https://docs.wave.com/webhook

Command-line example for sending a POST request with a valid signature header.

```shell
curl -i -X POST <your webhook URL> \
-H 'Content-Type: application/json' \
-H "Wave-Signature: t=1667920421,v1=53c971695230e9c51b1030d673eee76e70bbcdf8a7c5b8c1d44e0b8b1329647b" \
-d '{
    "id": "AE_ijzo7oGgrlM7",
     "type": "checkout.session.completed",
      "data": {
        "id": "cos-1b01sghpg100j",
        "amount": "100",
        "checkout_status": "complete",
        "client_reference": null,
        "currency": "XOF",
        "error_url": "https://example.com/error",
        "last_payment_error": null,
        "business_name": "Annas Apiaries",
        "payment_status": "succeeded",
        "success_url": "https://example.com/success",
        "wave_launch_url": "https://pay.wave.com/c/cos-1b01sghpg100j?a=100&c=XOF&m=Annas%20Apiaries",
        "when_completed": "2022-11-08T15:05:45Z",
        "when_created": "2022-11-08T15:05:32Z",
        "when_expires": "2022-11-09T15:05:32Z",
        "transaction_id": "TCN4Y4ZC3FM"
      }
    }'
```

--------------------------------

### Example API Response

Source: https://docs.wave.com/checkout

The JSON structure returned when a checkout session search is successful.

```json
{
  "result": [
    {
      "id": "cos-18qq25rgr100a",
      "amount": "1000",
      "checkout_status": "complete",
      "client_reference": "123456",
      "currency": "XOF",
      "error_url": "https://example.com/error",
      "last_payment_error": null,
      "business_name": "Papa's Penguins",
      "payment_status": "succeeded",
      "transaction_id": "TDH5TEWTLFE",
      "aggregated_merchant_id": "am-7lks22ap113t4",
      "success_url": "https://example.com/success",
      "wave_launch_url": "https://pay.wave.com/c/cos-18qq25rgr100a",
      "when_completed": "2021-12-08T10:15:32Z",
      "when_created": "2021-12-08T10:13:04Z",
      "when_expires": "2021-12-09T10:13:04Z"
    }
  ]
}
```

--------------------------------

### Incorrect Webhook Payload Examples

Source: https://docs.wave.com/webhook

Examples of invalid payloads that will fail signature verification due to formatting differences.

```json
'{"id":"AE_ijzo7oGgrlM7","type":"checkout.session.completed","data":{"id":"cos-1b01sghpg100j","amount":"100","checkout_status":"complete","client_reference":null,"currency":"XOF","error_url":"https://example.com/error","last_payment_error":null,"business_name":"AnnasApiaries","payment_status":"succeeded","success_url":"https://example.com/success","wave_launch_url":"https://pay.wave.com/c/cos-1b01sghpg100j?a=100&c=XOF&m=Annas%20Apiaries","when_completed":"2022-11-08T15:05:45Z","when_created":"2022-11-08T15:05:32Z","when_expires":"2022-11-09T15:05:32Z","transaction_id":"TCN4Y4ZC3FM"}}'
```

```json
{"id": "cos-1b01sghpg100j", "amount": "100", "checkout_status": "complete", "client_reference": null, "currency": "XOF", "error_url": "https://example.com/error", "last_payment_error": null, "business_name": "Annas Apiaries", "payment_status": "succeeded", "success_url": "https://example.com/success", "wave_launch_url": "https://pay.wave.com/c/cos-1b01sghpg100j?a=100&c=XOF&m=Annas%20Apiaries", "when_completed": "2022-11-08T15:05:45Z", "when_created": "2022-11-08T15:05:32Z", "when_expires": "2022-11-09T15:05:32Z", "transaction_id": "TCN4Y4ZC3FM"}
```

```json
{
 "id": "AE_ijzo7oGgrlM7",
 "type": "checkout.session.completed",
 "data": {
    "id": "cos-1b01sghpg100j",
    "amount": "100",
    "checkout_status": "complete",
    "client_reference": null,
    "currency": "XOF",
    "error_url": "https://example.com/error",
    "last_payment_error": null,
    "business_name": "Annas Apiaries",
    "payment_status": "succeeded",
    "success_url": "https://example.com/success",
    "wave_launch_url": "https://pay.wave.com/c/cos-1b01sghpg100j?a=100&c=XOF&m=Annas%20Apiaries",
    "when_completed": "2022-11-08T15:05:45Z",
    "when_created": "2022-11-08T15:05:32Z",
    "when_expires": "2022-11-09T15:05:32Z",
    "transaction_id": "TCN4Y4ZC3FM"
 }
}
```

--------------------------------

### Correct Webhook Payload Example

Source: https://docs.wave.com/webhook

A valid webhook body string for signature verification.

```json
'{"id": "AE_ijzo7oGgrlM7", "type": "checkout.session.completed", "data": {"id": "cos-1b01sghpg100j", "amount": "100", "checkout_status": "complete", "client_reference": null, "currency": "XOF", "error_url": "https://example.com/error", "last_payment_error": null, "business_name": "Annas Apiaries", "payment_status": "succeeded", "success_url": "https://example.com/success", "wave_launch_url": "https://pay.wave.com/c/cos-1b01sghpg100j?a=100&c=XOF&m=Annas%20Apiaries", "when_completed": "2022-11-08T15:05:45Z", "when_created": "2022-11-08T15:05:32Z", "when_expires": "2022-11-09T15:05:32Z", "transaction_id": "TCN4Y4ZC3FM"}}'
```

--------------------------------

### Retrieve a checkout session

Source: https://docs.wave.com/checkout

Examples for retrieving a Checkout Session object by ID using different programming languages.

```shell
curl \
-H 'Authorization: Bearer wave_sn_prod_YhUNb9d...i4bA6' \
https://api.wave.com/v1/checkout/sessions/cos-18qq25rgr100a
```

```php
<?php

# Specify your API KEY
$api_key = "wave_sn_prod_YhUNb9d...i4bA6";

$checkout_id = "cos-18qq25rgr100a";

# Define the request options
$curlOptions = [
  CURLOPT_URL => "https://api.wave.com/v1/checkout/sessions/{$checkout_id}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_TIMEOUT => 5,
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer {$api_key}",
  ],
];

# Execute the request and get a response
$curl = curl_init();
curl_setopt_array($curl, $curlOptions);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
    # You can now decode the response and use the checkout session. Happy coding ;)
    $checkout_session = json_decode($response);
    var_dump($checkout_session);
}
```

```javascript
const axios = require('axios');

const api_key = "wave_sn_prod_YhUNb9d...i4bA6";
const checkout_id = "cos-18qq25rgr100a";

axios.get('https://api.wave.com/v1/checkout/sessions/' + checkout_id, { headers: { 'Authorization': `Bearer ${api_key}` } })
.then((response) => {
  const checkout_session = response.data;
  console.log(checkout_session);
})
.catch((error) => {
  console.error(error);
});
```

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

public class CheckoutSession {
  public static void main(String[] args) {
    String api_key = "wave_sn_prod_YhUNb9d...i4bA6";
    String checkout_id = "cos-18qq25rgr100a";

    OkHttpClient client = new OkHttpClient();
    Request request = new Request.Builder()
      .url("https://api.wave.com/v1/checkout/sessions/" + checkout_id)
      .get()
      .addHeader("Authorization", "Bearer " + api_key)
      .build();

    try {
      Response response = client.newCall(request).execute();
      if (response.isSuccessful()) {
        JSONObject jsonResponse = new JSONObject(response.body().string());
        System.out.println(jsonResponse.toString());
      } else {
        System.out.println("Error: " + response.body().string());
      }
    } catch (Exception e) {
      e.printStackTrace();
    }
  }
}
```

--------------------------------

### Shared Secret Webhook Request Example

Source: https://docs.wave.com/webhook

Example of an incoming webhook request using the Shared Secret authentication method.

```http
POST /your-webhook-endpoint
Host: your-domain.com
Content-Type: application/json
Authorization: Bearer your_webhook_secret
User-Agent: Wave/1.0

{
  "id": "AE5D3JYN6WA",
  "type": "checkout.session.completed",
  "data": {
    // event data
  }
}
```

--------------------------------

### Retrieve account balance via Java

Source: https://docs.wave.com/balance-api

Use the Unirest library to perform a GET request to the balance endpoint.

```java
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());
```

--------------------------------

### Refund a Checkout Session via JavaScript

Source: https://docs.wave.com/checkout

This JavaScript example uses the Axios library to send the POST request.

```javascript
const axios = require('axios');

const api_key = "wave_sn_prod_YhUNb9d...i4bA6";
const checkout_id = "cos-18qq25rgr100a";

axios.post('https://api.wave.com/v1/checkout/sessions/' + checkout_id + '/refund', null, { headers: { 'Authorization': `Bearer ${api_key}` } })
.then((response) => {
  const checkout_session = response.data;
  console.log(checkout_session);
})
.catch((error) => {
  console.error(error);
});
```

--------------------------------

### Error response example

Source: https://docs.wave.com/payout

The JSON structure returned when a request fails validation or other checks.

```json
{
  "code": "request-validation-error",
  "message": "An 'Idempotency-Key' header is required for POST requests"
}
```

--------------------------------

### Retrieve transactions with Java

Source: https://docs.wave.com/balance-api

Use the Unirest library to execute the GET request. The response body is retrieved as a string.

```java
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());
```

--------------------------------

### Paginated Response Structure

Source: https://docs.wave.com/aggregated-merchants

Example of a JSON response containing pagination metadata and a list of items.

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

--------------------------------

### Refund a Checkout Session via PHP

Source: https://docs.wave.com/checkout

This PHP example uses the cURL library to perform the POST request.

```php
<?php

# Specify your API KEY
$api_key = "wave_sn_prod_YhUNb9d...i4bA6";

$checkout_id = "cos-18qq25rgr100a";

# Define the request options
$curlOptions = [
  CURLOPT_URL => "https://api.wave.com/v1/checkout/sessions/{$checkout_id}/refund",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_TIMEOUT => 5,
  CURLOPT_POST => true,
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer {$api_key}",
  ],
];

# Execute the request and get a response
$curl = curl_init();
curl_setopt_array($curl, $curlOptions);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
    # You can now decode the response and use the checkout session. Happy coding ;)
    $checkout_session = json_decode($response);
    var_dump($checkout_session);
}
```

--------------------------------

### Retrieve account balance via JavaScript

Source: https://docs.wave.com/balance-api

Use the Axios library to perform a GET request to the balance endpoint.

```javascript
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);
});
```

--------------------------------

### Retrieve Checkout Session by Transaction ID

Source: https://docs.wave.com/checkout

Examples for fetching a checkout session using a transaction ID across different programming environments.

```shell
curl -X GET \
  --url https://api.wave.com/v1/checkout/sessions?transaction_id=FAH.4827.1734 \
  -H 'Authorization : Bearer wave_sn_prod_YhUNb9d...i4bA6'
```

```php
<?php

# Specify your API KEY
$api_key = "wave_sn_prod_YhUNb9d...i4bA6";

$transaction_id = "FAH.4827.1734";

# Define the request options
$curlOptions = [
  CURLOPT_URL => "https://api.wave.com/v1/checkout/sessions?transaction_id={$transaction_id}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_TIMEOUT => 5,
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer {$api_key}",
  ],
];

# Execute the request and get a response
$curl = curl_init();
curl_setopt_array($curl, $curlOptions);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
    # You can now decode the response and use the checkout session. Happy coding ;)
    $checkout_session = json_decode($response);
    var_dump($checkout_session);
}
```

```javascript
const axios = require('axios');

const api_key = "wave_sn_prod_YhUNb9d...i4bA6";
const transaction_id = "FAH.4827.1734";

axios.get('https://api.wave.com/v1/checkout/sessions', { params: { transaction_id }, headers: { 'Authorization': `Bearer ${api_key}` } })
.then((response) => {
  const checkout_session = response.data;
  console.log(checkout_session);
})
.catch((error) => {
  console.error(error);
});
```

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

public class CheckoutSession {
  public static void main(String[] args) {
    String api_key = "wave_sn_prod_YhUNb9d...i4bA6";
    String transaction_id = "FAH.4827.1734";

    OkHttpClient client = new OkHttpClient();
    Request request = new Request.Builder()
      .url("https://api.wave.com/v1/checkout/sessions?transaction_id=" + transaction_id)
      .get()
      .addHeader("Authorization", "Bearer " + api_key)
      .build();

    try {
      Response response = client.newCall(request).execute();
      if (response.isSuccessful()) {
        JSONObject jsonResponse = new JSONObject(response.body().string());
        System.out.println(jsonResponse.toString());
      } else {
        System.out.println("Error: " + response.body().string());
      }
    } catch (Exception e) {
      e.printStackTrace();
    }
  }
}
```

--------------------------------

### GET /v1/checkout/sessions

Source: https://docs.wave.com/checkout

Retrieves a Checkout Session object by transaction id (identifier starting with T_).

```APIDOC
## GET /v1/checkout/sessions

### Description
Retrieves a Checkout Session object by transaction id (identifier starting with T_).

### Method
GET

### Endpoint
https://api.wave.com/v1/checkout/sessions

### Parameters
#### Query Parameters
- **transaction_id** (string) - Required - The transaction ID of the checkout session to retrieve.

### Response
#### Success Response (200)
- **Checkout Session object** (object) - Returns a Checkout Session object if a valid identifier was provided.
```

--------------------------------

### Implement Webhook Endpoint in Go

Source: https://docs.wave.com/webhook

Uses the standard net/http library to handle incoming requests and verify signatures.

```go
package main

import (
    "encoding/json"
    "io/ioutil"
    "net/http"
)

func handleWaveWebhook(w http.ResponseWriter, r *http.Request) {
    // 1. Get the raw request body and headers
    rawBody, err := ioutil.ReadAll(r.Body)
    if err != nil {
        http.Error(w, "Failed to read body", http.StatusBadRequest)
        return
    }
    waveSignature := r.Header.Get("Wave-Signature")

    // 2. Verify the webhook signature (see Security section)
    if !verifySignature(rawBody, waveSignature) {
        http.Error(w, "Invalid signature", http.StatusUnauthorized)
        return
    }

    // 3. Parse the event data
    var eventData map[string]interface{}
    if err := json.Unmarshal(rawBody, &eventData); err != nil {
        http.Error(w, "Invalid JSON", http.StatusBadRequest)
        return
    }
    eventType := eventData["type"].(string)

    // 4. Respond quickly with success
    // (Do heavy processing asynchronously)
    w.WriteHeader(http.StatusOK)
    w.Write([]byte("OK"))
}

func verifySignature(body []byte, signature string) bool {
    // Signature verification logic (see Security section)
    return true
}

func main() {
    http.HandleFunc("/webhooks/wave", handleWaveWebhook)
    http.ListenAndServe(":8080", nil)
}
```

--------------------------------

### Pagination Request Flow

Source: https://docs.wave.com/aggregated-merchants#aggregated-merchants-api

Demonstrates the sequence of initial and subsequent requests to fetch all pages of data.

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

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

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

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

--------------------------------

### Initial Pagination Request

Source: https://docs.wave.com/aggregated-merchants

The first request in a sequence to retrieve a paginated collection.

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

--------------------------------

### GET /v1/checkout/sessions/search

Source: https://docs.wave.com/checkout

Searches for checkout sessions.

```APIDOC
## GET /v1/checkout/sessions/search

### Description
Searches for checkout sessions.

### Method
GET

### Endpoint
https://api.wave.com/v1/checkout/sessions/search
```

--------------------------------

### GET /v1/payouts/search

Source: https://docs.wave.com/payout

Searches for payouts based on criteria.

```APIDOC
## GET /v1/payouts/search

### Description
Searches for payouts based on criteria.

### Method
GET

### Endpoint
https://api.wave.com/v1/payouts/search
```

--------------------------------

### GET /v1/payout/:id

Source: https://docs.wave.com/payout

Retrieves the details of a specific payout by its ID.

```APIDOC
## GET /v1/payout/:id

### Description
Retrieves the details of a specific payout by its ID.

### Method
GET

### Endpoint
https://api.wave.com/v1/payout/:id
```

--------------------------------

### GET /v1/transactions

Source: https://docs.wave.com/balance-api

Lists all transactions processed by the Wave Business Wallet.

```APIDOC
## GET /v1/transactions

### Description
Lists all transactions processed by your Wave Business Wallet.

### Method
GET

### Endpoint
https://api.wave.com/v1/transactions
```

--------------------------------

### POST /v1/payout-batch

Source: https://docs.wave.com/payout

Initiates a batch of payouts.

```APIDOC
## POST /v1/payout-batch

### Description
Initiates a batch of payouts.

### Method
POST

### Endpoint
https://api.wave.com/v1/payout-batch
```

--------------------------------

### GET /v1/balance

Source: https://docs.wave.com/balance-api

Retrieves the current balance of the Wave Business Wallet.

```APIDOC
## GET /v1/balance

### Description
Retrieves the current balance of your Wave Business Wallet.

### Method
GET

### Endpoint
https://api.wave.com/v1/balance
```

--------------------------------

### Implement a Python Webhook Endpoint

Source: https://docs.wave.com/webhook

A basic Flask-based endpoint structure for receiving and verifying Wave webhook events.

```python
@app.route('/webhooks/wave', methods=['POST'])
def handle_wave_webhook():
    # 1. Get the raw request body and headers
    raw_body = request.get_data()
    wave_signature = request.headers.get('Wave-Signature')

    # 2. Verify the webhook signature (see Security section)
    if not verify_signature(raw_body, wave_signature):
        return 'Invalid signature', 401

    # 3. Parse the event data
    event_data = request.json
    event_type = event_data['type']

    # 4. Respond quickly with success
    # (Do heavy processing asynchronously)
    return 'OK', 200

def verify_signature(body, signature):
    # Signature verification logic (see Security section)
    pass
```

--------------------------------

### GET /v1/aggregated_merchants/:id

Source: https://docs.wave.com/aggregated-merchants

Retrieves the details of a single aggregated merchant.

```APIDOC
## GET /v1/aggregated_merchants/:id

### Description
Retrieves the details of a single aggregated merchant.

### Method
GET

### Endpoint
/v1/aggregated_merchants/:id

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the aggregated merchant.

### Response
#### Success Response (200)
- **id** (string) - The merchant ID
- **name** (string) - The merchant name
- **business_sector** (string|null) - The business sector
- **business_type** (string) - The business type
- **business_registration_identifier** (string|null) - The registration identifier
- **website_url** (string) - The merchant website URL
- **payout_fee_structure_name** (string) - The payout fee structure
- **checkout_fee_structure_name** (string) - The checkout fee structure
- **manager_name** (string) - The manager name
- **business_description** (string) - Description of the business
- **when_created** (string) - Creation timestamp
- **is_locked** (boolean) - Whether the merchant is locked

### Response Example
{
    "id": "am-7lks22ap113t4",
    "name": "Moustaphas Groceries",
    "business_sector": null,
    "business_type": "other",
    "business_registration_identifier": null,
    "website_url": "https://example.com",
    "payout_fee_structure_name": "one_percent",
    "checkout_fee_structure_name": "one_fifty_bps",
    "manager_name": "Moustapha",
    "business_description": "A grocery store in the heart of the city.",
    "when_created": "2022-06-21T09:56:29Z",
    "is_locked": true
}
```

--------------------------------

### GET /v1/payout

Source: https://docs.wave.com/payout

Retrieves the current status of a payout using its unique identifier.

```APIDOC
## GET /v1/payout

### Description
Retrieves the status of a payout by providing the ID returned at creation time.

### Method
GET

### Endpoint
/v1/payout

### Parameters
#### Query Parameters
- **id** (string) - Required - The unique identifier of the payout.
```

--------------------------------

### Implement a PHP Webhook Endpoint

Source: https://docs.wave.com/webhook

A standard PHP implementation for processing raw POST data and verifying signatures from Wave.

```php
<?php
// webhook_handler.php

// 1. Get the raw request body and headers
$rawBody = file_get_contents('php://input');
$waveSignature = $_SERVER['HTTP_WAVE_SIGNATURE'] ?? '';

// 2. Verify the webhook signature (see Security section)
if (!verifySignature($rawBody, $waveSignature)) {
    http_response_code(401);
    echo 'Invalid signature';
    exit;
}

// 3. Parse the event data
$eventData = json_decode($rawBody, true);
$eventType = $eventData['type'];

// 4. Respond quickly with success
// (Do heavy processing asynchronously)
http_response_code(200);
echo 'OK';

function verifySignature($body, $signature) {
    // Signature verification logic (see Security section)
    return true;
}
?>
```

--------------------------------

### GET /v1/payouts-batch/:id

Source: https://docs.wave.com/payout

Retrieves the details of a specific batch payout by its ID.

```APIDOC
## GET /v1/payouts-batch/:id

### Description
Retrieves the details of a specific batch payout by its ID.

### Method
GET

### Endpoint
https://api.wave.com/v1/payouts-batch/:id
```

--------------------------------

### GET /v1/checkout/sessions/:id

Source: https://docs.wave.com/checkout

Retrieves details for a specific checkout session by its ID.

```APIDOC
## GET /v1/checkout/sessions/:id

### Description
Retrieves details for a specific checkout session.

### Method
GET

### Endpoint
https://api.wave.com/v1/checkout/sessions/:id
```

--------------------------------

### Construct a POST request with Java OkHttp

Source: https://docs.wave.com/business

Use the OkHttp library to send a POST request, requiring the org.json library for payload construction.

```java
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();
    }
  }
}
```

--------------------------------

### GET /v1/aggregated_merchants/:id

Source: https://docs.wave.com/aggregated-merchants

Retrieve details for a specific aggregated merchant identity.

```APIDOC
## GET /v1/aggregated_merchants/:id

### Description
Retrieve the details of a specific aggregated merchant identity by its ID.

### Method
GET

### Endpoint
https://api.wave.com/v1/aggregated_merchants/:id

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the aggregated merchant.
```

--------------------------------

### GET /v1/aggregated_merchants

Source: https://docs.wave.com/aggregated-merchants

Retrieve a list of all aggregated merchant identities associated with the account.

```APIDOC
## GET /v1/aggregated_merchants

### Description
Retrieve a list of all aggregated merchant identities associated with your merchant account.

### Method
GET

### Endpoint
https://api.wave.com/v1/aggregated_merchants
```
Tokens:
Raw