Create Payout Destination

curl --request POST \
  --url https://api.bachs.io/v1/payouts/destinations \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "My GTBank Savings",
  "currency": "NGN",
  "label": "Treasury NGN Account",
  "account_number": "0123456789",
  "bank_code": "058"
}
'

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    name: 'My GTBank Savings',
    currency: 'NGN',
    label: 'Treasury NGN Account',
    account_number: '0123456789',
    bank_code: '058'
  })
};

fetch('https://api.bachs.io/v1/payouts/destinations', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.bachs.io/v1/payouts/destinations"

payload = {
    "name": "My GTBank Savings",
    "currency": "NGN",
    "label": "Treasury NGN Account",
    "account_number": "0123456789",
    "bank_code": "058"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

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

print(response.text)

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.bachs.io/v1/payouts/destinations"

	payload := strings.NewReader("{\n  \"name\": \"My GTBank Savings\",\n  \"currency\": \"NGN\",\n  \"label\": \"Treasury NGN Account\",\n  \"account_number\": \"0123456789\",\n  \"bank_code\": \"058\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

{
  "id": "pd_7Kq2mNv4XbR9dLc0",
  "name": "My GTBank Savings",
  "type": "bank_account",
  "currency": "NGN",
  "status": "pending_review",
  "status_reason": null,
  "is_usable": false,
  "is_default": false,
  "account_number": "0123456789",
  "account_name": "JOHN DOE",
  "bank_code": "058",
  "bank_name": "Guaranty Trust Bank",
  "phone_number": null,
  "mobile_provider": null,
  "wallet_address": null,
  "network": null,
  "reviewed_at": null,
  "created_at": "2026-01-24T14:30:00.000Z",
  "updated_at": "2026-01-24T14:30:00.000Z"
}

{
  "detail": "Invalid request parameters",
  "error_code": "VALIDATION_ERROR",
  "errors": [
    {
      "field": "amount",
      "message": "Amount must be a positive decimal string",
      "type": "value_error"
    }
  ]
}

{
  "detail": "Invalid API key",
  "error_code": "UNAUTHORIZED"
}

{
  "detail": "API key does not have permission for this operation",
  "error_code": "FORBIDDEN"
}

{
  "detail": "Resource not found",
  "error_code": "NOT_FOUND"
}

{
  "detail": "Rate limit exceeded. Please retry after a few seconds.",
  "error_code": "TOO_MANY_REQUESTS"
}

{
  "detail": "An unexpected error occurred. Please try again later.",
  "error_code": "INTERNAL_SERVER_ERROR"
}

POST

payouts

destinations

Create Payout Destination

curl --request POST \
  --url https://api.bachs.io/v1/payouts/destinations \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "My GTBank Savings",
  "currency": "NGN",
  "label": "Treasury NGN Account",
  "account_number": "0123456789",
  "bank_code": "058"
}
'

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    name: 'My GTBank Savings',
    currency: 'NGN',
    label: 'Treasury NGN Account',
    account_number: '0123456789',
    bank_code: '058'
  })
};

fetch('https://api.bachs.io/v1/payouts/destinations', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.bachs.io/v1/payouts/destinations"

payload = {
    "name": "My GTBank Savings",
    "currency": "NGN",
    "label": "Treasury NGN Account",
    "account_number": "0123456789",
    "bank_code": "058"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

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

print(response.text)

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.bachs.io/v1/payouts/destinations"

	payload := strings.NewReader("{\n  \"name\": \"My GTBank Savings\",\n  \"currency\": \"NGN\",\n  \"label\": \"Treasury NGN Account\",\n  \"account_number\": \"0123456789\",\n  \"bank_code\": \"058\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

{
  "id": "pd_7Kq2mNv4XbR9dLc0",
  "name": "My GTBank Savings",
  "type": "bank_account",
  "currency": "NGN",
  "status": "pending_review",
  "status_reason": null,
  "is_usable": false,
  "is_default": false,
  "account_number": "0123456789",
  "account_name": "JOHN DOE",
  "bank_code": "058",
  "bank_name": "Guaranty Trust Bank",
  "phone_number": null,
  "mobile_provider": null,
  "wallet_address": null,
  "network": null,
  "reviewed_at": null,
  "created_at": "2026-01-24T14:30:00.000Z",
  "updated_at": "2026-01-24T14:30:00.000Z"
}

{
  "detail": "Invalid request parameters",
  "error_code": "VALIDATION_ERROR",
  "errors": [
    {
      "field": "amount",
      "message": "Amount must be a positive decimal string",
      "type": "value_error"
    }
  ]
}

{
  "detail": "Invalid API key",
  "error_code": "UNAUTHORIZED"
}

{
  "detail": "API key does not have permission for this operation",
  "error_code": "FORBIDDEN"
}

{
  "detail": "Resource not found",
  "error_code": "NOT_FOUND"
}

{
  "detail": "Rate limit exceeded. Please retry after a few seconds.",
  "error_code": "TOO_MANY_REQUESTS"
}

{
  "detail": "An unexpected error occurred. Please try again later.",
  "error_code": "INTERNAL_SERVER_ERROR"
}

Authorizations

Authorization

string

header

required

Bearer token authentication. Pass your API key as Authorization: Bearer sk_.... See Authentication for keys, scopes, and sandbox vs production.

Scopes

payouts:write

Body

application/json

Register where money should land. Accepts both the field names this surface has always used and newer aliases, so a caller never has to know which generation of the API it is talking to. Where a legacy name and its alias overlap, the newer name wins.

currency

string

required

Currency code this destination accepts (e.g., 'NGN', 'USD', 'USDT_TRC20').

Maximum string length: 10

Example:

"NGN"

name

string | null

User-friendly name for this destination.

Maximum string length: 255

Example:

"My GTBank Savings"

label

string | null

Alias for name. name wins if both are sent.

Maximum string length: 255

Example:

null

type

string | null

Type of payout destination: bank_account, mobile_money, or crypto_wallet. Inferred from currency when omitted.

Example:

"bank_account"

destination_type

string | null

Alias for type. type wins if both are sent.

Example:

null

account_number

string | null

Account number for bank routes that use one. EUR SEPA uses iban; CAD Interac to email uses interac_email.

Maximum string length: 50

Example:

"0123456789"

bank_code

string | null

Supported local bank code from List Banks for the destination country. International schemes use their currency-specific routing fields.

Maximum string length: 20

Example:

"058"

account_name

string | null

Account holder name required for international bank routing. For NGN, the bank resolves the name and ignores a supplied value.

Maximum string length: 255

Example:

"Example account holder"

bank_name

string | null

Bank name for international bank routing. For NGN, it is resolved from the bank.

Maximum string length: 255

Example:

"Example bank"

phone_number

string | null

Phone number for the mobile money account. Required for mobile_money destinations.

Maximum string length: 20

Example:

null

mobile_provider

string | null

Mobile money provider (e.g., 'MTN', 'Vodafone'). Required for mobile_money destinations.

Maximum string length: 50

Example:

null

wallet_address

string | null

Cryptocurrency wallet address. Required for crypto_wallet destinations.

Maximum string length: 255

Example:

null

network

string | null

Blockchain network. Optional when the currency already names its network (e.g. USDT_TRC20).

Maximum string length: 50

Example:

null

metadata

object | null

Additional custom metadata to associate with this destination.

Example:

null

sort_code

string | null

GBP sort code, six digits; spaces and dashes are normalized.

Maximum string length: 12

iban

string | null

IBAN for a EUR SEPA bank destination.

Maximum string length: 50

swift_bic

string | null

Bank BIC, 8 or 11 characters, for EUR SEPA. This does not select SWIFT; SWIFT payouts are not currently offered.

Maximum string length: 20

routing_number

string | null

Nine-digit US ABA routing number for USD ACH, Wire or RTP.

Maximum string length: 15

bank_address

object | null

US bank branch address required for USD bank destinations. This is separate from the account holder address.

Show child attributes

institution_number

string | null

Three-digit Canadian institution number for EFT or Interac to a bank account.

Maximum string length: 8

transit_number

string | null

Five-digit Canadian transit number for EFT or Interac to a bank account.

Maximum string length: 10

interac_email

string | null

Destination email for CAD Interac using interac_email.

Maximum string length: 255

scheme

string | null

Choose ach, wire or rtp for USD; eft, interac_account or interac_email for CAD. Leave out for GBP and EUR. SWIFT payouts are not currently offered.

Response

Success

Response containing payout destination details (bank account, mobile money, or crypto wallet).

string

required

Unique identifier for this payout destination. Use this ID when creating payouts.

Example:

"pd_7Kq2mNv4XbR9dLc0"

name

string

required

User-friendly name for this destination. Helps you identify destinations in your system.

Example:

"My GTBank Savings"

type

enum<string>

required

Type of payout destination: bank_account, mobile_money, or crypto_wallet. Determines which fields are populated.

Available options:

bank_account,

mobile_money,

crypto_wallet

Example:

"bank_account"

currency

string

required

Currency code this destination accepts (e.g., 'NGN', 'USD', 'USDT_TRC20'). Payouts to this destination must use this currency.

Example:

"NGN"

status

enum<string>

required

Review status. pending_review: awaiting review, not usable yet. approved: cleared for payouts. rejected: permanently unusable, register a new destination instead.

Available options:

pending_review,

approved,

rejected

Example:

"approved"

status_reason

string | null

Free-text reason set by review, populated when the destination is rejected. Null while pending or approved.

Example:

null

is_usable

boolean

Whether this destination can be used for a payout right now. True only when status is approved and the destination has not been deactivated.

Example:

true

is_default

boolean

Whether a payout schedule pays out to this destination for its currency. Set it with PATCH /v1/payouts/destinations/{destination_id}.

Example:

false

account_number

string | null

Account number for bank routes that use one. EUR SEPA uses iban; CAD Interac to email uses interac_email.

Example:

"0123456789"

account_name

string | null

Account holder name as resolved from the bank. Only populated for bank_account destinations.

Example:

"JOHN DOE"

bank_code

string | null

Supported local bank code from List Banks for the destination country. International schemes use their currency-specific routing fields.

Example:

"058"

bank_name

string | null

Full name of the bank. Only populated for bank_account destinations.

Example:

"Guaranty Trust Bank"

phone_number

string | null

Phone number associated with the mobile money account. Only populated for mobile_money destinations.

Example:

null

mobile_provider

string | null

Mobile money provider (e.g., 'MTN', 'Vodafone'). Only populated for mobile_money destinations.

Example:

null

wallet_address

string | null

Cryptocurrency wallet address. Only populated for crypto_wallet destinations.

Example:

null

network

string | null

Blockchain network (e.g., 'TRC20', 'ERC20'). Only populated for crypto_wallet destinations. May be included in currency code (e.g., 'USDT_TRC20').

Example:

null

reviewed_at

string<date-time> | null

ISO 8601 timestamp when this destination was last reviewed by an admin. Null until reviewed.

Example:

null

created_at

string<date-time> | null

ISO 8601 timestamp when this destination was created.

Example:

"2026-01-24T14:30:00.000Z"

updated_at

string<date-time> | null

ISO 8601 timestamp when this destination was last updated.

Example:

"2026-01-24T14:30:00.000Z"

sort_code

string | null

GBP sort code, six digits; spaces and dashes are normalized.

Maximum string length: 12

iban

string | null

IBAN for a EUR SEPA bank destination.

Maximum string length: 50

swift_bic

string | null

Bank BIC, 8 or 11 characters, for EUR SEPA. This does not select SWIFT; SWIFT payouts are not currently offered.

Maximum string length: 20

routing_number

string | null

Nine-digit US ABA routing number for USD ACH, Wire or RTP.

Maximum string length: 15

bank_address

object | null

US bank branch address required for USD bank destinations. This is separate from the account holder address.

Show child attributes

institution_number

string | null

Three-digit Canadian institution number for EFT or Interac to a bank account.

Maximum string length: 8

transit_number

string | null

Five-digit Canadian transit number for EFT or Interac to a bank account.

Maximum string length: 10

interac_email

string | null

Destination email for CAD Interac using interac_email.

Maximum string length: 255

scheme

string | null

Choose ach, wire or rtp for USD; eft, interac_account or interac_email for CAD. Leave out for GBP and EUR. SWIFT payouts are not currently offered.

General

Checkout Sessions

Connected Accounts

Products

Subscriptions

Customers

Customer sessions

Payments

Refunds

Disputes

Payouts

Payout Destinations

Balance

Virtual accounts

Your account

Files

Media

Misc

Transfers

Persons

Platform Fees

Reference

Create Payout Destination

Authorizations

Scopes

Body

Response