Wave Payout API

https://docs.wave.com/payout/
Admin
Wave's Payout API provides a programmatic way for businesses to send money to one or more...
Tokens:23,669
Snippets:137
Trust Score:9.6
Update:1 week ago
Show doc for...
Tokens:
Raw
### Example response for retrieving a payout

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

Example response for the retrieve a payout request.

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

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

### GET /v1/checkout/sessions

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

Guidance for signing GET requests to the Wave API when there is no request body.

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

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

### Method
GET

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

### Parameters
No parameters are documented in the source.

### Request Example
No request body is used for GET requests.

### Response
#### Success Response (200)
No response schema is provided in the source.

### Notes
- The request must include an `Authorization` header with a Bearer API key.
- The request must include a `Wave-Signature` header with the format `t=<timestamp>,v1=<signature>`.
- The signature is computed as HMAC-SHA256 of the timestamp string (empty body) using the signing secret.
- The timestamp must be within 5 minutes in the past and 30 seconds in the future.
```

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

### Example response for retrieving a payout batch

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

Example response from retrieving a payout batch. Shows a batch with status "complete" and individual payouts that can have statuses like "succeeded", "processing", or "failed". Failed payouts include a payout_error object with error_code and error_message.

```json
{
  "id": "pb-185skxq8g1006",
  "status": "complete",
  "payouts": [
    {
      "id": "pt-185skxq9g100w",
      "currency": "XOF",
      "receive_amount": "1000",
      "fee": "10",
      "mobile": "+221555110219",
      "name": "Fatou Ndiaye",
      "status": "succeeded",
      "timestamp": "2022-06-21T10:07:30Z"
    },
    {
      "id": "pt-185skxqa0100y",
      "currency": "XOF",
      "receive_amount": "1200",
      "fee": "10",
      "mobile": "+221555110233",
      "name": "Moustapha Mbaye",
      "status": "processing",
      "aggregated_merchant_id": "am-7lks22ap113t4",
      "timestamp": "2022-06-21T10:07:30Z"
    },
    {
      "id": "pt-185sw98jg1016",
      "currency": "XOF",
      "receive_amount": "16000",
      "fee": "160",
      "mobile": "+221555144081",
      "name": "Mame Diop",
      "status": "failed",
      "payout_error": {
        "error_code": "recipient-limit-exceeded",
        "error_message": "The recipient has reached their monthly limit."
      },
      "timestamp": "2022-06-21T10:25:46Z"
    }
  ]
}
```

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

### POST /v1/checkout/sessions

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

Example of creating a signed checkout session request to the Wave API.

```APIDOC
## [POST] /v1/checkout/sessions

### Description
Creates a checkout session for a payment. The request must be signed with a HMAC-SHA256 signature using the signing secret.

### Method
POST

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

### Parameters
#### Request Body
- **amount** (string) - Required - The amount to charge.
- **currency** (string) - Required - The currency code (e.g., XOF).

### Request Example
{
  "amount": "1000",
  "currency": "XOF"
}

### Response
#### Success Response (200)
No response schema is provided in the source.

### Notes
- The request must include an `Authorization` header with a Bearer API key.
- The request must include a `Wave-Signature` header with the format `t=<timestamp>,v1=<signature>`.
- The signature is computed as HMAC-SHA256 of the concatenation of the timestamp and the request body, using the signing secret.
- The timestamp must be within 5 minutes in the past and 30 seconds in the future.
```

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

### Generate signature and make signed request in Python

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

Python example using hmac, hashlib, time, and requests to generate the signature and send a signed POST request to the Wave checkout sessions endpoint. The signature is computed over the timestamp concatenated with the body and included in the Wave-Signature header.

```python
import hmac
import hashlib
import time
import requests

api_key = "wave_sn_prod_YhUNb9d...i4bA6"
signing_secret = "wave_sn_AKS_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"

body = '{"amount": "1000", "currency": "XOF"}'

timestamp = str(int(time.time()))
payload = timestamp + body
signature = hmac.new(signing_secret.encode('utf-8'), payload.encode('utf-8'), hashlib.sha256).hexdigest()
wave_signature = f"t={timestamp},v1={signature}"

response = requests.post(
    "https://api.wave.com/v1/checkout/sessions",
    data=body,
    headers={
        "Authorization": f"Bearer {api_key}",
        "Wave-Signature": wave_signature,
        "Content-Type": "application/json",
    },
)
```

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

### Create payout batch response

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

Example response from the create payout batch endpoint. Contains the batch ID to poll for results.

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

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

### Successful payout response

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

Example successful response from the create payout endpoint. Includes the submitted fields plus id, fee, status, and timestamp.

```json
{
  "id": "pt-185b5e4b8100c",
  "currency": "XOF",
  "receive_amount": "500",
  "fee": "5",
  "mobile": "+221555110219",
  "name": "Fatou Ndiaye",
  "status": "succeeded",
  "timestamp": "2022-06-20T17:17:11Z"
}
```

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

### Search payouts response

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

Example response from the search payouts endpoint. Contains a list of payout objects with details such as id, currency, amount, mobile, name, and status.

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

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

### Generate signature and make signed request in PHP

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

PHP example that builds a JSON body, computes the HMAC-SHA256 signature using the timestamp and body, and sends a signed POST request to the Wave checkout sessions endpoint via cURL. The signature is included in the Wave-Signature header.

```php
<?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);
?>
```

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

### Successful reversal response (200 OK)

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

Example response for a successful payout reversal. The endpoint returns HTTP 200 with no body. Failure returns an HTTP code above 400 with an error_code such as insufficient-funds, payout-reversal-time-limit-exceeded, payout-reversal-account-terminated, or not-found.

```text
200 OK
```

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

### Search payouts with curl

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

Searches payouts by client reference using the GET /v1/payouts/search endpoint. Requires a bearer token and the client_reference query parameter.

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

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

### GET /v1/payouts/search

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

Retrieves a list of payouts based on the provided query parameters. Currently supports only search by client reference (`client_reference`).

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

### Description
Retrieves a list of payouts based on the provided query parameters. Currently supports only search by client reference (`client_reference`).

### Method
GET

### Endpoint
/v1/payouts/search

### Parameters
#### Query Parameters
- **client_reference** (string) - Required - The client reference to search for.

### Request Example
```
curl -X GET \
  --url https://api.wave.com/v1/payouts/search?client_reference=FAH.4827.1734 \
  -H 'Authorization : Bearer wave_sn_prod_YhUNb9d...i4bA6'
```

### Response
#### Success Response (200)
- **result** (List of payouts) - The list of payouts that match the search criteria.

#### Response Example
```
{
  "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"
      }
  ]
}
```
```

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

### Generate signature and make signed request in Node.js

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

Node.js example using crypto and axios to create an HMAC-SHA256 signature from the timestamp and body, then send a signed POST request to the Wave checkout sessions endpoint. The signature is placed in the Wave-Signature header.

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

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

### POST /v1/payout

Source: https://docs.wave.com/payout/#payout-api

Creates a new payout. The payout is created with status `processing` and immediately starts processing. In extraordinary cases, a 5XX error may be returned even though the payout was created; retry with the same idempotency key to avoid duplicates.

```APIDOC
## POST /v1/payout

### Description
Creates a new payout. The payout is created with status `processing` and immediately starts processing. In extraordinary cases, a 5XX error may be returned even though the payout was created; retry with the same idempotency key to avoid duplicates.

### Method
POST

### Endpoint
/v1/payout

### Parameters
#### Request Body
- **idempotency_key** (string) - Required - A unique key to ensure idempotent retries.
- **amount** (number) - Required - The amount to send to the recipient.
- **recipient** (string) - Required - The final recipient of the payout.

### Response
#### Success Response (200)
- **id** (string) - The id of the created payout, used to query its status.

#### Error Response
- **5xx** - Internal server errors, such as 500 or 503, may occur during outages. The payout may still be created; retry with the same idempotency key.
```

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

### Generate random idempotency keys (openssl, PHP, Python, JavaScript)

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

Generate a random idempotency key using the command line or a language-specific random string generator. The shell command uses openssl to produce a hex string; the PHP, Python, and JavaScript examples create a UUID or unique string. Use a new random string for each new request and reuse the same key when retrying a request.

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

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

### Retrieve a payout with curl

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

Sends a GET request to the Wave payouts API endpoint /v1/payout/:id using an Authorization bearer token. The payout id starts with `pt-`.

```shell
curl -X GET \
  --url https://api.wave.com/v1/payout/pt-185sewgm8100t \
  -H 'Authorization: Bearer wave_sn_prod_YhUNb9d...i4bA6'
```

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

### GET /v1/payouts/search

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

Searches for payouts based on query parameters.

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

### Description
Searches for payouts based on query parameters.

### Method
GET

### Endpoint
/v1/payouts/search

### Authentication
Bearer token (API key) required in Authorization header.

### Request Example
```
Authorization: Bearer wave_sn_prod_YhUNb9d...i4bA6
```
```

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

### POST /v1/user_name_matches/

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

Documentation for the name verification endpoint, including response fields, comparison algorithms, match values, and rate limiting.

```APIDOC
## POST /v1/user_name_matches/

### Description
Verifies a recipient's name and national ID against Wave's records before sending a payout. Returns match results and whether the payout is within limits.

### Method
POST

### Endpoint
/v1/user_name_matches/

### Parameters
#### Request Body
- **within_limits** (Boolean, or null) - Optional - True if the payout is likely to succeed. Null if currency and amount not set on request.
- **name_match** (Name match string, or null) - Optional - One of "MATCH", "NO_MATCH", "NAME_NOT_KNOWN", or null if name not provided in request body.
- **national_id_match** (National ID match string, or null) - Optional - One of "MATCH", "NO_MATCH", "ID_NOT_KNOWN", or null if national_id not provided in request body (only included if ID verification is enabled for your business).

### Request Example
{
  "within_limits": true,
  "name_match": "NAME_NOT_KNOWN",
  "national_id_match": "NO_MATCH"
}

### Response
#### Success Response (200)
- **within_limits** (Boolean, or null) - True if the payout is likely to succeed. Null if currency and amount not set on request.
- **name_match** (Name match string, or null) - One of "MATCH", "NO_MATCH", "NAME_NOT_KNOWN", or null if name not provided in request body.
- **national_id_match** (National ID match string, or null) - One of "MATCH", "NO_MATCH", "ID_NOT_KNOWN", or null if national_id not provided in request body (only included if ID verification is enabled for your business).

#### Response Example
{
  "within_limits": true,
  "name_match": "NAME_NOT_KNOWN",
  "national_id_match": "NO_MATCH"
}

### Rate Limiting
- **Limit:** up to 30 checks for the same phone number in any 5-minute window.
- **Penalty:** if you exceed this limit for the same phone number, that phone number will be blocked for 60 minutes for further name-checks.

### Notes
- This rate limit applies only to the name verification endpoint and does not affect remittance or payout posting endpoints.
- The `recipient-not-verified` error is no longer raised and can be disregarded.
```

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

### GET /v1/payout/:id

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

Retrieves details of a specific payout by its ID.

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

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

### Method
GET

### Endpoint
/v1/payout/:id

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

### Authentication
Bearer token (API key) required in Authorization header.

### Request Example
```
Authorization: Bearer wave_sn_prod_YhUNb9d...i4bA6
```
```

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

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

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

Retrieves details of a specific batch payout by its ID.

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

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

### Method
GET

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

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

### Authentication
Bearer token (API key) required in Authorization header.

### Request Example
```
Authorization: Bearer wave_sn_prod_YhUNb9d...i4bA6
```
```

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

### Create payout batch with curl

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

Creates a payout batch with multiple payouts using the POST /v1/payout-batch endpoint. Requires an idempotency key and a JSON body with a payouts array.

```shell
curl -X POST \
  --url https://api.wave.com/v1/payout-batch \
  -H "authorization: Bearer wave_sn_prod_YhUNb9d...i4bA6" \
  -H 'content-type: application/json' \
  -H 'idempotency-key: 65f735b4-b44b-429d-b0a8-550701e2393a' \
  -d '{"payouts": [
        { "currency": "XOF",
            "receive_amount": "1000",
            "name": "Fatou Ndiaye",
            "mobile": "+221555110219"
        },
        { "currency": "XOF",
            "receive_amount": "1200",
            "name": "Moustapha Mbaye",
            "mobile": "+221555110233",
            "aggregated_merchant_id": "am-7lks22ap113t4",
        },
        { "currency": "XOF",
            "receive_amount": "16000",
            "name": "Mame Diop",
            "mobile": "+221555144081"
        }
      ]}'
```

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

### Payout error response

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

Example error response when the request fails validation or other checks. Contains a top-level code and message.

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

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

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

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

Retrieves a payout batch by its ID. The response includes the batch status and a list of individual payouts with their details and statuses.

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

### Description
Retrieves a payout batch.

### Method
GET

### Endpoint
/v1/payout-batch/:id

### Parameters
#### Path Parameters
- **id** (String) - Required - The ID of the payout batch.

### Request Example
```
curl -X GET \
  --url https://api.wave.com/v1/payout-batch/pb-185skxq8g1006 \
  -H 'Authorization: Bearer wave_sn_prod_YhUNb9d...i4bA6'
```

### Response
#### Success Response (200)
- **id** (String) - The ID of the payout batch.
- **payouts** (List of payout results) - The list of payouts, with each item having the same structure as a single retrieved payout.
- **status** (Payout batch state) - The status of the payout batch: `processing` or `complete`.

#### Response Example
```
{
  "id": "pb-185skxq8g1006",
  "status": "complete",
  "payouts": [
    {
      "id": "pt-185skxq9g100w",
      "currency": "XOF",
      "receive_amount": "1000",
      "fee": "10",
      "mobile": "+221555110219",
      "name": "Fatou Ndiaye",
      "status": "succeeded",
      "timestamp": "2022-06-21T10:07:30Z"
    },
    {
      "id": "pt-185skxqa0100y",
      "currency": "XOF",
      "receive_amount": "1200",
      "fee": "10",
      "mobile": "+221555110233",
      "name": "Moustapha Mbaye",
      "status": "processing",
      "aggregated_merchant_id": "am-7lks22ap113t4",
      "timestamp": "2022-06-21T10:07:30Z"
    },
    {
      "id": "pt-185sw98jg1016",
      "currency": "XOF",
      "receive_amount": "16000",
      "fee": "160",
      "mobile": "+221555144081",
      "name": "Mame Diop",
      "status": "failed",
      "payout_error": {
        "error_code": "recipient-limit-exceeded",
        "error_message": "The recipient has reached their monthly limit."
      },
      "timestamp": "2022-06-21T10:25:46Z"
    }
  ]
}
```
```

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

### GET /v1/payout

Source: https://docs.wave.com/payout/#payout-api

Retrieves the status of a payout by its id. The payout status can be `processing`, `succeeded`, or `failed`. If the payout could not be entered in the system, a `not-found` error is returned.

```APIDOC
## GET /v1/payout

### Description
Retrieves the status of a payout by its id. The payout status can be `processing`, `succeeded`, or `failed`. If the payout could not be entered in the system, a `not-found` error is returned.

### Method
GET

### Endpoint
/v1/payout

### Parameters
#### Query Parameters
- **id** (string) - Required - The id of the payout returned at creation time.

### Response
#### Success Response (200)
- **status** (string) - The current status of the payout: `processing`, `succeeded`, or `failed`.
- **payout_error** (object) - Present when the payout failed, containing the reason for the failure.

#### Error Response
- **not-found** - Returned when the payout id does not exist in the system.
- **5xx** - Internal server errors, such as 500 or 503, may occur during outages.

### Response Example
{
  "status": "succeeded"
}
```

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

### GET /v1/payout/:id

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

Retrieves a single payout by its unique identifier. The response includes detailed payout information such as amount, fees, recipient details, and status.

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

### Description
Retrieves a single payout by id (identifier starting with `pt-`).

### Method
GET

### Endpoint
/v1/payout/:id

### Parameters
#### Path Parameters
- **id** (String) - Required - The payout identifier, starting with `pt-`.

### Request Example
```
curl -X GET \
  --url https://api.wave.com/v1/payout/pt-185sewgm8100t \
  -H 'Authorization: Bearer wave_sn_prod_YhUNb9d...i4bA6'
```

### Response
#### Success Response (200)
- **id** (String) - A unique identifier for the payout object. Up to 20 characters.
- **currency** (Currency code) - The amount currency. Note that your business wallet and the recipient must be in the same country.
- **fee** (Amount) - The fee for sending the payout.
- **mobile** (Phone number) - The recipient mobile phone number.
- **name** (String, optional) - The recipient name, may be used for user verification. Up to 255 characters.
- **national_id** (String, optional) - An optional field to save the recipient's national ID, for further user verification. Up to 255 characters.
- **payout_error** (Payout error, optional) - Details about the reason for a failed payout. Only populated when the status is `failed`.
- **receive_amount** (Amount) - The amount to be paid out to the recipient, net of fees.
- **status** (Payout state) - The status of the payout: `processing`, `failed`, or `succeeded`.
- **timestamp** (Timestamp) - The time and date that this payout request was recorded in our system. Note that this doesn't describe when payments were executed, only when they were submitted.
- **client_reference** (String, optional) - A unique string that you provide which can be used to correlate the payout in your system. Up to 255 characters.
- **payment_reason** (String, optional) - An optional message with a payment reason that is shown to customers in the payment receipt. Up to 40 characters.
- **aggregated_merchant_id** (String, optional) - The aggregated merchant ID used for this payout, if any.

#### Response Example
```
{
    "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"
}
```
```
Tokens:
Raw