Aggregated Merchants API

Wave's Aggregated Merchants API provides a programmatic way to create, update, delete, and list aggregated merchant identities that are associated with your merchant account. An aggregated merchant identity allows you to interact with customers under a different name than your official account, and potentially with different fee structures. Once created, aggregated merchant identities can be used with the Checkout API and the Payout API.

Endpoints:

GET /v1/aggregated_merchants
POST /v1/aggregated_merchants
GET /v1/aggregated_merchants/:id
PUT /v1/aggregated_merchants/:id
DELETE /v1/aggregated_merchants/:id

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.

Types

Base types

Timestamp

An ISO 8601 date and time.

• The time zone is UTC.
• The precision is in seconds.
• The format is YYYY-MM-DDThh:mm:ssZ. Example: 2022-06-20T17:17:11Z.

Business Type

A string indicating the type of business an aggregated merchant engages in. This list may change. The following values are possible:

Fee Structure

A string naming a fee structure. This list may change. The following values are possible:

Aggregated Merchant API request objects

Aggregated Merchant request

When creating or updating an Aggregated Merchant, a JSON object with the following fields is used:

Aggregated Merchant API return objects

Aggregated Merchant response

After creating, or when retrieving an Aggregated Merchant, a JSON object with the following fields is returned:

Paginated Aggregated Merchants response

A Paginated Aggregated Merchants is a paginated response containing a paginated list of aggregated merchants associated with an account.

Aggregated Merchants Error response

Example

{
  "error_code": "not-found",
  "error_message": "Aggregated merchant not found."
}

Aggregated Merchants Error response is an object. If you send an invalid request, or a request that cannot be satisfied for normal reasons, you will receive an error object as a response. For some server errors (where the HTTP response code is 5xx or above), you may not receive a JSON response body.

API

Retrieve a list of Aggregated Merchants

GET /v1/aggregated_merchants

curl -X GET \
  --url https://api.wave.com/v1/aggregated_merchants \
  -H 'Authorization: Bearer wave_sn_prod_YhUNb9d...i4bA6'

Example response

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

Retrieves a paginated list of aggregated merchants available for use with the current account.

Query parameters

This endpoint accepts standard pagination query parameters.

Create an Aggregated Merchant

POST /v1/aggregated_merchants

curl -X POST \
  --url https://api.wave.com/v1/aggregated_merchants \
  -H 'Authorization: Bearer wave_sn_prod_YhUNb9d...i4bA6' \
  -H 'Content-Type: application/json' \
  -d '{
          "name": "Moustaphas Groceries",
          "business_sector": null,
          "business_type": "other",
          "business_registration_identifier": null,
          "website_url": "https://groceries.example.com",
          "manager_name": "Moustapha",
          "business_description": "A grocery store in the heart of the city.
      }'

Example response

{
    "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_fity_bps",
    "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": false
}

Creating an aggregated merchant makes it immediately available for use. The request body must be an Aggregated Merchant request object.

When creating an aggregated merchant, supply the most accurate information you can about the aggregated merchant in all fields, including:

• The business name
• The correct business registration identifier
• The business's website, if any
• The business's sector of operation
• The business type (either "fintech" or "other")
• The business manager's name
• A description of the business

When you provide correct and complete information, Wave can more effectively and quickly review aggregated merchants and choose appropriate fee structures.

Retrieve an Aggregated Merchant

GET /v1/aggregated_merchants/:id

curl -X GET \
  --url https://api.wave.com/v1/aggregated_merchants/am-7lks22ap113t4 \
  -H 'Authorization: Bearer wave_sn_prod_YhUNb9d...i4bA6'

Example response

{
    "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
}

Retrieves the details of a single aggregated merchant. The response body will be an Aggregated Merchant response.

Update an Aggregated Merchant

PUT /v1/aggregated_merchants/:id

curl -X PUT \
  --url https://api.wave.com/v1/aggregated_merchants/am-7lks22ap113t4 \
  -H 'Authorization: Bearer wave_sn_prod_YhUNb9d...i4bA6' \
  -H 'Content-Type: application/json' \
  -d '{
          "name": "Moustaphas Candle Shop",
          "business_sector": null,
          "business_type": "other",
          "business_registration_identifier": null,
          "website_url": "https://example.com",
          "business_description": "A grocery store in the heart of the city.",
      }'

Example response

{
    "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
}

Updates the details of a single aggregated merchant. The response body will be an Aggregated Merchant response.

After Wave has reviewed an aggregated merchant's details and set appropriate fee structures, an aggregated merchant will become locked from further updates. Attempting to update an aggregated merchant will fail with an HTTP 403 Forbidden response code. You may still delete a locked aggregated merchant.

Delete an Aggregated Merchant

DELETE /v1/aggregated_merchants/:id

curl -X DELETE \
  --url https://api.wave.com/v1/aggregated_merchants/am-7lks22ap113t4 \
  -H 'Authorization: Bearer wave_sn_prod_YhUNb9d...i4bA6' \

Example response

Expect an HTTP 204 response, with no response body.

Deletes a single aggregated merchant. You will no longer be able to use or update this aggregated merchant.

When successful, the server will return a HTTP 204 ("OK, no content") response. There will be no response body.

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.

Errors

Aggregated Merchants API errors

Example errors returned by the API

Permissions error

{
    "code": "no-permission",
    "message": "No permission to access this endpoint"
}

Validation error

{
    "code": "request-validation-error",
    "details": [
        {
            "ctx": { "limit_value": 255 },
            "loc": ["name"],
            "msg": "ensure this value has at most 255 characters",
            "type": "value_error.any_str.max_length"
        }
    ],
    "message": "Request invalid"
}

The following is the list of errors that can occur when using this API.

We suggest that you write code that can handle the errors above. We might occasionally add a new error type.

The list above only covers known errors that are within Wave's control. There could be other technical issues like connection errors or timeouts if there are any network issues between your servers and Wave's. These are too numerous to list, but in any of those cases, requests can be safely retried, as long as the same idempotency key is used on those endpoints that support idempotent requests.

HTTP 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

2023-01-10

• Added business_sector, business_type, website_url, payout_fee_structure, and checkout_fee_structure. Updated examples.
• Fixed some erroneous fields.
• Fixed the errors table.

2022-11-10

• Fixed a typo in the API URLs

2022-10-27

• Initial release