Wave

create_checkout_session

• ⚠Store session.id immediately before redirecting the user — it is the only identifier for calling verify_payment server-side.
• ⚠wave_launch_url must be opened directly in the user's browser. Never open it in a WebView or an iframe — the payment will not initiate correctly.
• ⚠By default the session expires 30 minutes after creation. After expiration, checkout_status changes to 'expired' and payment is not possible.
• ⚠amount is a string, not a number. XOF accepts no decimals — send "5000", not "5000.00" or 5000.
• ⚠The API key is tied to a single Wave wallet. To operate in several countries, get one key per wallet.
• ⚠The Wave documentation describes no sandbox environment or test host: the only documented host is https://api.wave.com, and the API key is tied to a real wallet.
• ⚠If the API key was created with request signing (optional Business Portal setting), every call must carry Wave-Signature: t={timestamp},v1={HMAC-SHA256(timestamp + raw body)} computed with the signing secret (format wave_sn_AKS_…, shown only once) — empty body for a GET. Without it: 401 missing-signature; other codes: invalid-signature, invalid-signature-format, invalid-signature-timestamp, expired-signature-timestamp (timestamp more than 5 minutes in the past or more than 30 seconds in the future). The setting is permanent for a key: to drop it, revoke the key and create another one.
• ⚠[MUST TELL USER] The API IP whitelist turns on as soon as the first address is added in the Business Portal (Developer section) and can no longer be turned off from the portal — you have to go through your Wave account manager. Calls from an unlisted IP get 403 ip-not-allowed: on hosting without a fixed outbound IP (serverless functions, most PaaS), do not add any IP before you have a fixed egress.
• ⚠Wave checks the key before anything else, even before routing: an invalid key returns 401 on any path. The no-matching-api-key message quotes the last 4 characters of the received key ("No API key found ending in '…'") — compare them with your key to spot a badly loaded environment variable. (Measured without a valid key on 2026-10-24.)

create_payout_batch

• ⚠Every POST /v1/payout-batch request must include a unique Idempotency-Key header (UUID v4 recommended, max 255 chars). A batch can distribute funds to dozens of recipients — a retry without an idempotency key can trigger every payout twice.
• ⚠This endpoint is asynchronous — it immediately returns a batch.id without waiting for the payouts to be processed. Poll GET /v1/payout-batch/{id} until status === 'complete'.
• ⚠batch.status === 'complete' does not mean that all payouts succeeded. Inspect the status of each individual payout in the response — some can be 'failed' while others are 'succeeded'.
• ⚠There is no 'success' or 'failed' status at the batch level itself, only 'processing' and 'complete'. The actual result is in each payout.
• ⚠Each payout in the batch is processed independently. A failure on one payout (e.g. insufficient-funds) does not cancel the others.
• ⚠If the API key was created with request signing (optional Business Portal setting), every call must carry Wave-Signature: t={timestamp},v1={HMAC-SHA256(timestamp + raw body)} computed with the signing secret (format wave_sn_AKS_…, shown only once) — empty body for a GET. Without it: 401 missing-signature; other codes: invalid-signature, invalid-signature-format, invalid-signature-timestamp, expired-signature-timestamp (timestamp more than 5 minutes in the past or more than 30 seconds in the future). The setting is permanent for a key: to drop it, revoke the key and create another one.
• ⚠[MUST TELL USER] The API IP whitelist turns on as soon as the first address is added in the Business Portal (Developer section) and can no longer be turned off from the portal — you have to go through your Wave account manager. Calls from an unlisted IP get 403 ip-not-allowed: on hosting without a fixed outbound IP (serverless functions, most PaaS), do not add any IP before you have a fixed egress.

expire_checkout

• ⚠A session that is already completed or already expired cannot be expired — Wave returns HTTP 409.
• ⚠Sessions expire automatically 30 minutes after creation. This endpoint is useful for releasing reserved stock immediately without waiting for the natural expiration.
• ⚠If the API key was created with request signing (optional Business Portal setting), every call must carry Wave-Signature: t={timestamp},v1={HMAC-SHA256(timestamp + raw body)} computed with the signing secret (format wave_sn_AKS_…, shown only once) — empty body for a GET. Without it: 401 missing-signature; other codes: invalid-signature, invalid-signature-format, invalid-signature-timestamp, expired-signature-timestamp (timestamp more than 5 minutes in the past or more than 30 seconds in the future). The setting is permanent for a key: to drop it, revoke the key and create another one.
• ⚠[MUST TELL USER] The API IP whitelist turns on as soon as the first address is added in the Business Portal (Developer section) and can no longer be turned off from the portal — you have to go through your Wave account manager. Calls from an unlisted IP get 403 ip-not-allowed: on hosting without a fixed outbound IP (serverless functions, most PaaS), do not add any IP before you have a fixed egress.

get_balance

• ⚠The API key is tied to a single wallet. To check the balance of several wallets (multi-country), get one API key per wallet and call this endpoint once per key.
• ⚠amount is returned as a string and can be negative when in debit. Always parse it to a number before doing comparisons.
• ⚠If the API key was created with request signing (optional Business Portal setting), every call must carry Wave-Signature: t={timestamp},v1={HMAC-SHA256(timestamp + raw body)} computed with the signing secret (format wave_sn_AKS_…, shown only once) — empty body for a GET. Without it: 401 missing-signature; other codes: invalid-signature, invalid-signature-format, invalid-signature-timestamp, expired-signature-timestamp (timestamp more than 5 minutes in the past or more than 30 seconds in the future). The setting is permanent for a key: to drop it, revoke the key and create another one.
• ⚠[MUST TELL USER] The API IP whitelist turns on as soon as the first address is added in the Business Portal (Developer section) and can no longer be turned off from the portal — you have to go through your Wave account manager. Calls from an unlisted IP get 403 ip-not-allowed: on hosting without a fixed outbound IP (serverless functions, most PaaS), do not add any IP before you have a fixed egress.
• ⚠Wave checks the key before anything else, even before routing: an invalid key returns 401 on any path. The no-matching-api-key message quotes the last 4 characters of the received key ("No API key found ending in '…'") — compare them with your key to spot a badly loaded environment variable. (Measured without a valid key on 2026-10-24.)

get_payout

• ⚠Use this endpoint to monitor a payout in 'processing' status returned by send_payout. A 'processing' payout can still switch to 'succeeded' or 'failed' — never mark it as permanently failed before observing a final status.
• ⚠A payout in 'reversed' status was cancelled via POST /v1/payout/{id}/reverse. The amount + the fees are credited back to the sending wallet.
• ⚠If the API key was created with request signing (optional Business Portal setting), every call must carry Wave-Signature: t={timestamp},v1={HMAC-SHA256(timestamp + raw body)} computed with the signing secret (format wave_sn_AKS_…, shown only once) — empty body for a GET. Without it: 401 missing-signature; other codes: invalid-signature, invalid-signature-format, invalid-signature-timestamp, expired-signature-timestamp (timestamp more than 5 minutes in the past or more than 30 seconds in the future). The setting is permanent for a key: to drop it, revoke the key and create another one.
• ⚠[MUST TELL USER] The API IP whitelist turns on as soon as the first address is added in the Business Portal (Developer section) and can no longer be turned off from the portal — you have to go through your Wave account manager. Calls from an unlisted IP get 403 ip-not-allowed: on hosting without a fixed outbound IP (serverless functions, most PaaS), do not add any IP before you have a fixed egress.

get_transactions

• ⚠Transactions are returned from oldest to newest for a given day. To get the most recent transactions first, reverse the array client-side.
• ⚠Without a date parameter, Wave returns only the current day's transactions (UTC). For reconciliation, always specify the date explicitly.
• ⚠Pagination uses opaque cursors (end_cursor), not offsets. Do not build the cursor manually — use only the value returned by the API.
• ⚠To fetch all of a day's transactions, loop while page_info.has_next_page === true, passing end_cursor as the after parameter.
• ⚠If the API key was created with request signing (optional Business Portal setting), every call must carry Wave-Signature: t={timestamp},v1={HMAC-SHA256(timestamp + raw body)} computed with the signing secret (format wave_sn_AKS_…, shown only once) — empty body for a GET. Without it: 401 missing-signature; other codes: invalid-signature, invalid-signature-format, invalid-signature-timestamp, expired-signature-timestamp (timestamp more than 5 minutes in the past or more than 30 seconds in the future). The setting is permanent for a key: to drop it, revoke the key and create another one.
• ⚠[MUST TELL USER] The API IP whitelist turns on as soon as the first address is added in the Business Portal (Developer section) and can no longer be turned off from the portal — you have to go through your Wave account manager. Calls from an unlisted IP get 403 ip-not-allowed: on hosting without a fixed outbound IP (serverless functions, most PaaS), do not add any IP before you have a fixed egress.

refund_checkout

• ⚠This endpoint is idempotent — calling refund twice on the same session returns HTTP 200 without creating a duplicate refund.
• ⚠Only a session with payment_status 'succeeded' can be refunded. Calling refund on a session that is not completed returns an error.
• ⚠The refund is for the full amount — Wave does not support partial refunds via this endpoint.
• ⚠Alternative by transaction ID: if the session ID is lost but the Wave transaction_id is known, use POST /v1/transactions/{transaction_id}/refund (Balance API) to refund by transaction.
• ⚠If the API key was created with request signing (optional Business Portal setting), every call must carry Wave-Signature: t={timestamp},v1={HMAC-SHA256(timestamp + raw body)} computed with the signing secret (format wave_sn_AKS_…, shown only once) — empty body for a GET. Without it: 401 missing-signature; other codes: invalid-signature, invalid-signature-format, invalid-signature-timestamp, expired-signature-timestamp (timestamp more than 5 minutes in the past or more than 30 seconds in the future). The setting is permanent for a key: to drop it, revoke the key and create another one.
• ⚠[MUST TELL USER] The API IP whitelist turns on as soon as the first address is added in the Business Portal (Developer section) and can no longer be turned off from the portal — you have to go through your Wave account manager. Calls from an unlisted IP get 403 ip-not-allowed: on hosting without a fixed outbound IP (serverless functions, most PaaS), do not add any IP before you have a fixed egress.

search_checkouts

• ⚠If client_reference is not unique per order in your system, the search can return several sessions — filter on checkout_status === 'complete' && payment_status === 'succeeded' to identify the paid session.
• ⚠This endpoint is the main recovery mechanism when session.id was not stored (server crash between create and redirect). Always pass a client_reference at creation so the session can be found again.
• ⚠If the API key was created with request signing (optional Business Portal setting), every call must carry Wave-Signature: t={timestamp},v1={HMAC-SHA256(timestamp + raw body)} computed with the signing secret (format wave_sn_AKS_…, shown only once) — empty body for a GET. Without it: 401 missing-signature; other codes: invalid-signature, invalid-signature-format, invalid-signature-timestamp, expired-signature-timestamp (timestamp more than 5 minutes in the past or more than 30 seconds in the future). The setting is permanent for a key: to drop it, revoke the key and create another one.
• ⚠[MUST TELL USER] The API IP whitelist turns on as soon as the first address is added in the Business Portal (Developer section) and can no longer be turned off from the portal — you have to go through your Wave account manager. Calls from an unlisted IP get 403 ip-not-allowed: on hosting without a fixed outbound IP (serverless functions, most PaaS), do not add any IP before you have a fixed egress.

send_payout

• ⚠Every POST /v1/payout request must include a unique Idempotency-Key header (UUID v4 recommended, max 255 chars). Without this key, a retry after a network error can create a duplicate payout.
• ⚠If the payout returns status 'processing', do not mark it as failed — treat it as pending and monitor it via GET /v1/payout/{id}. Marking it as failed too early can push the user to retry, causing a duplicate.
• ⚠On a 5xx error, timeout or interrupted connection: retry with the SAME Idempotency-Key and exponential backoff. Wave guarantees idempotency.
• ⚠On an 'idempotency-mismatch' error (409): the same Idempotency-Key was used with a different body. Generate a new key and retry.
• ⚠Reversing a payout is limited to 3 days after creation. After that period, POST /v1/payout/{id}/reverse returns an error.
• ⚠receive_amount is a string without decimals for XOF — send "5000", not 5000 or "5000.00".
• ⚠If the API key was created with request signing (optional Business Portal setting), every call must carry Wave-Signature: t={timestamp},v1={HMAC-SHA256(timestamp + raw body)} computed with the signing secret (format wave_sn_AKS_…, shown only once) — empty body for a GET. Without it: 401 missing-signature; other codes: invalid-signature, invalid-signature-format, invalid-signature-timestamp, expired-signature-timestamp (timestamp more than 5 minutes in the past or more than 30 seconds in the future). The setting is permanent for a key: to drop it, revoke the key and create another one.
• ⚠[MUST TELL USER] The API IP whitelist turns on as soon as the first address is added in the Business Portal (Developer section) and can no longer be turned off from the portal — you have to go through your Wave account manager. Calls from an unlisted IP get 403 ip-not-allowed: on hosting without a fixed outbound IP (serverless functions, most PaaS), do not add any IP before you have a fixed egress.

verify_payment

• ⚠Always verify server-side before confirming an order — never rely solely on the success_url or the webhook. A user can tamper with the redirect.
• ⚠Check BOTH fields: checkout_status === 'complete' AND payment_status === 'succeeded'. A checkout_status 'complete' with payment_status 'cancelled' means that the payment failed.
• ⚠verify_payment is also the recovery mechanism if the webhook was not received (timeout, server unavailable, restart).
• ⚠If the API key was created with request signing (optional Business Portal setting), every call must carry Wave-Signature: t={timestamp},v1={HMAC-SHA256(timestamp + raw body)} computed with the signing secret (format wave_sn_AKS_…, shown only once) — empty body for a GET. Without it: 401 missing-signature; other codes: invalid-signature, invalid-signature-format, invalid-signature-timestamp, expired-signature-timestamp (timestamp more than 5 minutes in the past or more than 30 seconds in the future). The setting is permanent for a key: to drop it, revoke the key and create another one.
• ⚠[MUST TELL USER] The API IP whitelist turns on as soon as the first address is added in the Business Portal (Developer section) and can no longer be turned off from the portal — you have to go through your Wave account manager. Calls from an unlisted IP get 403 ip-not-allowed: on hosting without a fixed outbound IP (serverless functions, most PaaS), do not add any IP before you have a fixed egress.

verify_recipient

• ⚠Rate limit: 30 checks including a name comparison (name field provided) for the same number within a 5-minute window. Beyond that, this number is blocked for 60 minutes. Calls without name are not subject to this limit.
• ⚠NAME_NOT_KNOWN does not mean that the name is incorrect — it means that Wave has no legal information on this recipient (not KYC-2). Do not block a payout on that basis alone.
• ⚠The name comparison uses Jaro-Winkler with a 0.65 threshold — minor spelling variations (accents, abbreviations) can return MATCH.
• ⚠national_id_match requires specific activation by Wave. Without this activation, the field always returns null even if national_id is provided.
• ⚠If the API key was created with request signing (optional Business Portal setting), every call must carry Wave-Signature: t={timestamp},v1={HMAC-SHA256(timestamp + raw body)} computed with the signing secret (format wave_sn_AKS_…, shown only once) — empty body for a GET. Without it: 401 missing-signature; other codes: invalid-signature, invalid-signature-format, invalid-signature-timestamp, expired-signature-timestamp (timestamp more than 5 minutes in the past or more than 30 seconds in the future). The setting is permanent for a key: to drop it, revoke the key and create another one.
• ⚠[MUST TELL USER] The API IP whitelist turns on as soon as the first address is added in the Business Portal (Developer section) and can no longer be turned off from the portal — you have to go through your Wave account manager. Calls from an unlisted IP get 403 ip-not-allowed: on hosting without a fixed outbound IP (serverless functions, most PaaS), do not add any IP before you have a fixed egress.

webhook_payment_completed

• ⚠Wave also sends the checkout.session.payment_failed event when a payment fails. Implement a handler for this event to notify the user or release the reserved stock.
• ⚠Never fulfill an order based on the webhook alone. Call verify_payment (GET /v1/checkout/sessions/{id}) to confirm server-side — the webhook payload can be forged.
• ⚠Respond 2xx immediately, then process asynchronously: Wave retries only if your endpoint does not respond with 2xx (for 3 days, 5-second timeout). Once the 200 is sent, Wave will not retry: record the event (at least data.id) BEFORE responding, and respond 5xx if that write fails. Wave also warns that events can be lost, duplicated or arrive out of order: set up a catch-up job that queries verify_payment (or search_checkouts by client_reference) for orders still pending.
• ⚠Wave offers two security modes, chosen when the webhook is registered: Shared Secret (the secret in plain text in Authorization: Bearer <secret>) and Signing Secret (Wave-Signature header, recommended for production). With a Shared Secret webhook there is no Wave-Signature header: a handler that only checks the signature rejects every event. This example accepts both modes.
• ⚠Implement idempotency via event.id — Wave can deliver the same event several times. Check that the order is not already fulfilled before acting.
• ⚠Verify the Wave-Signature signature in production: HMAC-SHA256 of timestamp + raw body. Use the raw body, not the parsed JSON — some frameworks modify the body between receipt and parsing.
• ⚠[MUST TELL USER] Wave sends webhooks from 15 IP ranges. If your server filters incoming traffic, add these IPs to your firewall or the webhooks will fail silently. The list is public at https://docs.wave.com/webhook (IP Whitelisting section): you must allow all of them, otherwise some webhooks can be rejected at random.
• ⚠[MUST TELL USER] In local development, Wave cannot reach localhost. Use an HTTPS tunnel (e.g. `ngrok http 3000`) and configure the ngrok URL in the Business Portal before testing.