Create a transfer

curl --request POST \
  --url https://sandbox-api.sakawave.example/v1/transfers \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "sourceAccountId": "01K2Z3AB4D5E6F7G8H9JKMNPQR",
  "destinationId": "01K2Z3AB4F5G6H7J8KMNPQRSTV",
  "sourceCurrency": "NGN",
  "destinationCurrency": "NGN",
  "amountSide": "source",
  "sourceAmount": "2500000",
  "externalReference": "payout_20260814_001",
  "narration": "Sandbox tutorial transfer"
}
'

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    sourceAccountId: '01K2Z3AB4D5E6F7G8H9JKMNPQR',
    destinationId: '01K2Z3AB4F5G6H7J8KMNPQRSTV',
    sourceCurrency: 'NGN',
    destinationCurrency: 'NGN',
    amountSide: 'source',
    sourceAmount: '2500000',
    externalReference: 'payout_20260814_001',
    narration: 'Sandbox tutorial transfer'
  })
};

fetch('https://sandbox-api.sakawave.example/v1/transfers', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://sandbox-api.sakawave.example/v1/transfers"

payload = {
    "sourceAccountId": "01K2Z3AB4D5E6F7G8H9JKMNPQR",
    "destinationId": "01K2Z3AB4F5G6H7J8KMNPQRSTV",
    "sourceCurrency": "NGN",
    "destinationCurrency": "NGN",
    "amountSide": "source",
    "sourceAmount": "2500000",
    "externalReference": "payout_20260814_001",
    "narration": "Sandbox tutorial transfer"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

{
  "id": "01K2Z3AB4J5K6M7N8PQRSTVWXY",
  "externalReference": "payout_20260814_001",
  "transferReference": "SKWV-TRF-01K2Z3AB4J5K6M7N8PQRSTVWXY",
  "destinationType": "own_account",
  "sourceAccountId": "01K2Z3AB4D5E6F7G8H9JKMNPQR",
  "destinationId": "01K2Z3AB4F5G6H7J8KMNPQRSTV",
  "sourceCurrency": "NGN",
  "destinationCurrency": "NGN",
  "amountSide": "source",
  "sourceAmount": "25000.00",
  "destinationAmount": "25000.00",
  "fee": "50.00",
  "totalDebit": "25050.00",
  "routeId": null,
  "scheme": "internal",
  "fxQuoteId": null,
  "destination": {
    "displayName": "Treasury NGN",
    "institutionName": null,
    "accountNumberLast4": null
  },
  "status": "completed",
  "narration": "Sandbox tutorial transfer",
  "failureCode": null,
  "failureReason": null,
  "initiatedByUserId": null,
  "initiatedByApiKeyId": "01K2Z3AB4N5P6Q7R8STVWXYZAB",
  "approvedByUserId": null,
  "approvedAt": null,
  "completedAt": "2026-08-14T09:08:00.000Z",
  "createdAt": "2026-08-14T09:07:58.000Z",
  "updatedAt": "2026-08-14T09:08:00.000Z"
}

{
  "statusCode": 400,
  "message": "Must be a valid identifier.",
  "code": "validation_failed",
  "errors": [
    {
      "message": "Must be a valid identifier.",
      "field": "accountId",
      "code": "custom",
      "path": [
        "accountId"
      ]
    }
  ]
}

{
  "statusCode": 401,
  "code": "INVALID_API_KEY",
  "message": "Invalid or inactive API credentials."
}

{
  "statusCode": 403,
  "message": "International wallets for your customers are not available yet. Your own approval cannot be used for a customer wallet.",
  "code": "international_customer_wallet_not_supported",
  "currency": "USD"
}

{
  "statusCode": 404,
  "code": "resource_not_found",
  "message": "Resource not found."
}

{
  "statusCode": 409,
  "code": "resource_conflict",
  "message": "The request conflicts with the current resource state."
}

{
  "statusCode": 422,
  "message": "Payment detail validation failed.",
  "code": "payment_detail_invalid",
  "errors": [
    {
      "message": "Account number is required.",
      "field": "accountNumber",
      "code": "required",
      "path": [
        "fields",
        "accountNumber"
      ]
    }
  ]
}

{
  "statusCode": 429,
  "message": "Too many API requests. Try again later.",
  "code": "api_key_rate_limit_exceeded",
  "retryAfterSeconds": 17
}

{
  "statusCode": 500,
  "code": "internal_server_error",
  "message": "An unexpected error occurred."
}

{
  "statusCode": 503,
  "code": "provider_unavailable",
  "message": "We could not issue an account number just now. Try again shortly."
}

POST

transfers

Create a transfer

curl --request POST \
  --url https://sandbox-api.sakawave.example/v1/transfers \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "sourceAccountId": "01K2Z3AB4D5E6F7G8H9JKMNPQR",
  "destinationId": "01K2Z3AB4F5G6H7J8KMNPQRSTV",
  "sourceCurrency": "NGN",
  "destinationCurrency": "NGN",
  "amountSide": "source",
  "sourceAmount": "2500000",
  "externalReference": "payout_20260814_001",
  "narration": "Sandbox tutorial transfer"
}
'

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    sourceAccountId: '01K2Z3AB4D5E6F7G8H9JKMNPQR',
    destinationId: '01K2Z3AB4F5G6H7J8KMNPQRSTV',
    sourceCurrency: 'NGN',
    destinationCurrency: 'NGN',
    amountSide: 'source',
    sourceAmount: '2500000',
    externalReference: 'payout_20260814_001',
    narration: 'Sandbox tutorial transfer'
  })
};

fetch('https://sandbox-api.sakawave.example/v1/transfers', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://sandbox-api.sakawave.example/v1/transfers"

payload = {
    "sourceAccountId": "01K2Z3AB4D5E6F7G8H9JKMNPQR",
    "destinationId": "01K2Z3AB4F5G6H7J8KMNPQRSTV",
    "sourceCurrency": "NGN",
    "destinationCurrency": "NGN",
    "amountSide": "source",
    "sourceAmount": "2500000",
    "externalReference": "payout_20260814_001",
    "narration": "Sandbox tutorial transfer"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

{
  "id": "01K2Z3AB4J5K6M7N8PQRSTVWXY",
  "externalReference": "payout_20260814_001",
  "transferReference": "SKWV-TRF-01K2Z3AB4J5K6M7N8PQRSTVWXY",
  "destinationType": "own_account",
  "sourceAccountId": "01K2Z3AB4D5E6F7G8H9JKMNPQR",
  "destinationId": "01K2Z3AB4F5G6H7J8KMNPQRSTV",
  "sourceCurrency": "NGN",
  "destinationCurrency": "NGN",
  "amountSide": "source",
  "sourceAmount": "25000.00",
  "destinationAmount": "25000.00",
  "fee": "50.00",
  "totalDebit": "25050.00",
  "routeId": null,
  "scheme": "internal",
  "fxQuoteId": null,
  "destination": {
    "displayName": "Treasury NGN",
    "institutionName": null,
    "accountNumberLast4": null
  },
  "status": "completed",
  "narration": "Sandbox tutorial transfer",
  "failureCode": null,
  "failureReason": null,
  "initiatedByUserId": null,
  "initiatedByApiKeyId": "01K2Z3AB4N5P6Q7R8STVWXYZAB",
  "approvedByUserId": null,
  "approvedAt": null,
  "completedAt": "2026-08-14T09:08:00.000Z",
  "createdAt": "2026-08-14T09:07:58.000Z",
  "updatedAt": "2026-08-14T09:08:00.000Z"
}

{
  "statusCode": 400,
  "message": "Must be a valid identifier.",
  "code": "validation_failed",
  "errors": [
    {
      "message": "Must be a valid identifier.",
      "field": "accountId",
      "code": "custom",
      "path": [
        "accountId"
      ]
    }
  ]
}

{
  "statusCode": 401,
  "code": "INVALID_API_KEY",
  "message": "Invalid or inactive API credentials."
}

{
  "statusCode": 403,
  "message": "International wallets for your customers are not available yet. Your own approval cannot be used for a customer wallet.",
  "code": "international_customer_wallet_not_supported",
  "currency": "USD"
}

{
  "statusCode": 404,
  "code": "resource_not_found",
  "message": "Resource not found."
}

{
  "statusCode": 409,
  "code": "resource_conflict",
  "message": "The request conflicts with the current resource state."
}

{
  "statusCode": 422,
  "message": "Payment detail validation failed.",
  "code": "payment_detail_invalid",
  "errors": [
    {
      "message": "Account number is required.",
      "field": "accountNumber",
      "code": "required",
      "path": [
        "fields",
        "accountNumber"
      ]
    }
  ]
}

{
  "statusCode": 429,
  "message": "Too many API requests. Try again later.",
  "code": "api_key_rate_limit_exceeded",
  "retryAfterSeconds": 17
}

{
  "statusCode": 500,
  "code": "internal_server_error",
  "message": "An unexpected error occurred."
}

{
  "statusCode": 503,
  "code": "provider_unavailable",
  "message": "We could not issue an account number just now. Try again shortly."
}

Idempotency

externalReference is unique within your business and is the idempotency key. Persist it before sending the request, and reuse it on every retry of the same intended payment. Reusing it returns the existing transfer as it stands, without comparing the rest of the payload. Two consequences to design around:

A different payment sent under a reference you have already used returns the old transfer and moves no money. Never reuse a reference for a different payment.
A transfer that failed keeps its reference. Retrying with the same reference returns the failed transfer, not a new attempt. To genuinely retry a failed payment, mint a new reference — and resolve a fresh destination for it.

A failed create still creates a transfer. If execution fails — most often insufficient_funds — the response is an error, and a transfer row exists in failed status holding that externalReference.

What comes back

Status	Meaning
`pending`	Accepted and submitted. Settlement is asynchronous; wait for a webhook.
`completed`	Already settled, typical for an internal book transfer.
`awaiting_approval`	Your business requires a human approval for this transfer.

A transfer awaiting approval cannot be approved through this API. Approval and rejection are dashboard actions. If your business has an approval policy switched on, API-initiated transfers stop here until someone approves them.

The transient submitting status is never published to a webhook, and you will rarely see it in a response.

Amounts

You send minor units as strings — "2500000" — and get back display decimals — "25000.00". totalDebit is sourceAmount plus fee, and is what actually leaves the account.

Error codes

Status	`code`	Cause
`400`	`validation_failed`	A field failed validation, or an unknown field was sent.
`409`	`insufficient_funds`	The account does not hold `totalDebit`. A transfer row is created in `failed` status.
`409`	`transfer_source_account_ineligible`	The source account is missing, inactive, not debitable, a customer wallet, or in a different currency.
`409`	`transfer_destination_expired`	The destination has expired or has already been spent. Resolve a fresh one.
`409`	`transfer_destination_unavailable`	The destination was spent between preview and execution.
`409`	`same_transfer_account`	Source and destination resolve to the same account.
`409`	`accounts_held_separately`	The USDC account cannot convert, or two USDC accounts hold their balances apart.
`409`	`transfer_amount_invalid`	The wrong amount was sent for `amountSide`, or both were.
`409`	`fx_quote_required`	The currencies differ and no `fxQuoteId` was supplied.
`409`	`fx_quote_unavailable`	The quote expired or was spent before the transfer ran.
`409`	`fx_quote_mismatch`	The quote does not match this transfer.
`409`	`transfer_amount_below_route_minimum`	Below the route minimum, returned in `minimumAmount`.
`409`	`transfer_amount_above_route_maximum`	Above the route maximum, returned in `maximumAmount`.
`403`	`— (`reason: currency_not_available`)`	The source account is not NGN and your tier is below 3. Carries `currentTier` and `requiredTier`, and no `code`.
`422`	`— (`reason: daily_outflow_limit_exceeded`)`	The tier daily outflow allowance for this currency is spent. Carries `limit`, `spentToday`, and `remaining` in minor units, and no `code`.
`503`	`provider_unavailable`	The settlement provider could not be reached.
`401`	`INVALID_API_KEY`	The key is missing, invalid, inactive, expired, from the other environment, or blocked by its IP allowlist.
`429`	`api_key_rate_limit_exceeded`	The per-minute limit for this key was exceeded. Transfers, quotes, destinations, and recipients share one 120-per-minute allowance.

Authorizations

Authorization

string

header

required

A secret API key, sent as Authorization: Bearer sk_test_… in sandbox or Bearer sk_live_… in live.

Body

application/json

sourceAccountId

string

required

Must be active, debitable, in sourceCurrency, and not a customer wallet.

Required string length: 26

Pattern: ^[0-7][0-9A-HJKMNP-TV-Z]{25}$

Example:

"01K2Z3AB4C5D6E7F8G9HJKMNPQ"

destinationId

string

required

An unexpired, unspent destination.

Required string length: 26

Pattern: ^[0-7][0-9A-HJKMNP-TV-Z]{25}$

Example:

"01K2Z3AB4C5D6E7F8G9HJKMNPQ"

sourceCurrency

enum<string>

required

Available options:

NGN,

USD,

GBP,

EUR,

GHS,

ZAR,

UGX,

CAD,

MXN,

AED,

USDC

destinationCurrency

enum<string>

required

Available options:

NGN,

USD,

GBP,

EUR,

GHS,

ZAR,

UGX,

CAD,

MXN,

AED,

AUD,

SGD,

HKD,

KES,

TZS,

BRL,

CNY,

XAF,

PHP,

USDC

amountSide

enum<string>

required

Available options:

source,

destination

externalReference

string

required

Required string length: 1 - 120

sourceAmount

string

A positive integer number of minor units.

Pattern: ^[1-9]\d*$

Example:

"2500000"

destinationAmount

string

A positive integer number of minor units.

Pattern: ^[1-9]\d*$

Example:

"2500000"

fxQuoteId

string

Required when the currencies differ, and rejected as a mismatch if it was quoted for a different account, destination, side, or amount.

Required string length: 26

Pattern: ^[0-7][0-9A-HJKMNP-TV-Z]{25}$

Example:

"01K2Z3AB4C5D6E7F8G9HJKMNPQ"

narration

string

Maximum string length: 500

Response

Successful response.

string

required

A 26-character ULID.

Required string length: 26

Pattern: ^[0-7][0-9A-HJKMNP-TV-Z]{25}$

Example:

"01K2Z3AB4C5D6E7F8G9HJKMNPQ"

externalReference

string

required

transferReference

string

required

destinationType

enum<string>

required

Available options:

own_account,

sakawave_tag,

external

sourceAccountId

string

required

A 26-character ULID.

Required string length: 26

Pattern: ^[0-7][0-9A-HJKMNP-TV-Z]{25}$

Example:

"01K2Z3AB4C5D6E7F8G9HJKMNPQ"

destinationId

string

required

A 26-character ULID.

Required string length: 26

Pattern: ^[0-7][0-9A-HJKMNP-TV-Z]{25}$

Example:

"01K2Z3AB4C5D6E7F8G9HJKMNPQ"

sourceCurrency

enum<string>

required

Available options:

NGN,

USD,

GBP,

EUR,

GHS,

ZAR,

UGX,

CAD,

MXN,

AED,

USDC

destinationCurrency

enum<string>

required

Available options:

NGN,

USD,

GBP,

EUR,

GHS,

ZAR,

UGX,

CAD,

MXN,

AED,

AUD,

SGD,

HKD,

KES,

TZS,

BRL,

CNY,

XAF,

PHP,

USDC

amountSide

enum<string>

required

Available options:

source,

destination

sourceAmount

string

required

A decimal display amount returned by transfer APIs. Preserve it as a string.

Pattern: ^-?\d+(?:\.\d+)?$

Example:

"25000.00"

destinationAmount

string

required

A decimal display amount returned by transfer APIs. Preserve it as a string.

Pattern: ^-?\d+(?:\.\d+)?$

Example:

"25000.00"

fee

string

required

A decimal display amount returned by transfer APIs. Preserve it as a string.

Pattern: ^-?\d+(?:\.\d+)?$

Example:

"25000.00"

totalDebit

string

required

A decimal display amount returned by transfer APIs. Preserve it as a string.

Pattern: ^-?\d+(?:\.\d+)?$

Example:

"25000.00"

routeId

string | null

required

A 26-character ULID.

Required string length: 26

Pattern: ^[0-7][0-9A-HJKMNP-TV-Z]{25}$

Example:

"01K2Z3AB4C5D6E7F8G9HJKMNPQ"

scheme

string

required

fxQuoteId

string | null

required

A 26-character ULID.

Required string length: 26

Pattern: ^[0-7][0-9A-HJKMNP-TV-Z]{25}$

Example:

"01K2Z3AB4C5D6E7F8G9HJKMNPQ"

destination

object | null

required

Show child attributes

status

enum<string>

required

Available options:

awaiting_approval,

submitting,

pending,

completed,

failed,

reversed,

rejected

narration

string | null

required

failureCode

string | null

required

failureReason

string | null

required

initiatedByUserId

string | null

required

A 26-character ULID.

Required string length: 26

Pattern: ^[0-7][0-9A-HJKMNP-TV-Z]{25}$

Example:

"01K2Z3AB4C5D6E7F8G9HJKMNPQ"

initiatedByApiKeyId

string | null

required

A 26-character ULID.

Required string length: 26

Pattern: ^[0-7][0-9A-HJKMNP-TV-Z]{25}$

Example:

"01K2Z3AB4C5D6E7F8G9HJKMNPQ"

approvedByUserId

string | null

required

A 26-character ULID.

Required string length: 26

Pattern: ^[0-7][0-9A-HJKMNP-TV-Z]{25}$

Example:

"01K2Z3AB4C5D6E7F8G9HJKMNPQ"

approvedAt

string<date-time> | null

required

Example:

"2026-08-14T09:00:00.000Z"

completedAt

string<date-time> | null

required

Example:

"2026-08-14T09:00:00.000Z"

createdAt

string<date-time>

required

Example:

"2026-08-14T09:00:00.000Z"

updatedAt

string<date-time>

required

Example:

"2026-08-14T09:00:00.000Z"

Currencies and countries

Customers

Accounts

Transfer destinations

FX quotes

Transfers

Cards

Bill payments

eSIM

Transactions

Create a transfer

Idempotency

What comes back

Amounts

Error codes

Authorizations

Body

Response

​Idempotency

​What comes back

​Amounts

​Error codes

Authorizations

Body

Response

Idempotency

What comes back

Amounts

Error codes