Update Payout Destination

curl --request PATCH \
  --url https://api.bachs.io/v1/payouts/destinations/{destination_id} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "Treasury NGN Account"
}
'

const options = {
  method: 'PATCH',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({name: 'Treasury NGN Account'})
};

fetch('https://api.bachs.io/v1/payouts/destinations/{destination_id}', 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/{destination_id}"

payload = { "name": "Treasury NGN Account" }
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.patch(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/{destination_id}"

	payload := strings.NewReader("{\n  \"name\": \"Treasury NGN Account\"\n}")

	req, _ := http.NewRequest("PATCH", 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": "Treasury NGN Account",
  "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-02-22T14: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"
}

Payout Destinations

Update Payout Destination

Update a destination: rename it, (de)promote it as a payout schedule’s default, or restate where money lands.

name and is_default alone are safe: neither touches review status, since the default can only ever be one of your own approved destinations. Sending any routing detail (currency, type, account, wallet or phone) restates the destination in full, the same shape as POST; omitted routing fields fall back to what is already stored. Changing an account number, bank code, wallet, network, or phone number this way sends the destination back for review, because the approval it holds was granted for the details it is being asked to leave behind.

Common errors:

400 VALIDATION_ERROR: neither name nor is_default sent, or an invalid payload for the destination type. Resolution: validate request fields and retry.
401 UNAUTHORIZED: API key is missing, invalid, or revoked. Resolution: use a valid API key in the Authorization header.
404 NOT_FOUND: destination_id was not found. Resolution: verify destination ID and retry.

PATCH

payouts

destinations

{destination_id}

Update Payout Destination

curl --request PATCH \
  --url https://api.bachs.io/v1/payouts/destinations/{destination_id} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "Treasury NGN Account"
}
'

const options = {
  method: 'PATCH',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({name: 'Treasury NGN Account'})
};

fetch('https://api.bachs.io/v1/payouts/destinations/{destination_id}', 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/{destination_id}"

payload = { "name": "Treasury NGN Account" }
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.patch(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/{destination_id}"

	payload := strings.NewReader("{\n  \"name\": \"Treasury NGN Account\"\n}")

	req, _ := http.NewRequest("PATCH", 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": "Treasury NGN Account",
  "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-02-22T14: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.

Path Parameters

destination_id

string

required

Body

application/json

The one update a destination allows. name and is_default alone are safe: a rename touches no routing column, and the default can only ever be one of your own approved destinations. Sending any field below restates the destination in full, the same shape as POST; omitted routing fields fall back to what is already stored. Changing an account number, bank code, wallet, network or phone number this way sends the destination back for review, because the approval it holds was granted for the details it is being asked to leave behind.

name

string | null

The new name for this destination.

Required string length: 1 - 255

Example:

"Treasury NGN Account"

is_default

boolean | null

Make this the destination a payout schedule pays out to for its currency. Setting it demotes the previous default; false clears it. Ignored if this request also changes where money lands and that change sends the destination back for review.

Example:

true

currency

string | null

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

Maximum string length: 10

Example:

null

type

string | null

Type of payout destination: bank_account, mobile_money, or crypto_wallet.

Example:

null

destination_type

string | null

Alias for type. type wins if both are sent.

Example:

null

account_number

string | null

Bank account number.

Maximum string length: 50

Example:

null

account_name

string | null

Account holder name. Unlike registration, an update trusts the name it is given.

Maximum string length: 255

Example:

null

bank_code

string | null

Bank code or routing number.

Maximum string length: 20

Example:

null

bank_name

string | null

Bank name.

Maximum string length: 255

Example:

null

phone_number

string | null

Phone number for the mobile money account.

Maximum string length: 20

Example:

null

mobile_provider

string | null

Mobile money provider (e.g., 'MTN', 'Vodafone').

Maximum string length: 50

Example:

null

wallet_address

string | null

Cryptocurrency wallet address.

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

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

Bank account number. Only populated for bank_account destinations.

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

Bank code or routing number. Only populated for bank_account destinations.

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"

General

Checkout Sessions

Connected Accounts

Products

Subscriptions

Customers

Customer sessions

Payments

Refunds

Payouts

Payout Destinations

Balance

Virtual accounts

Media

Misc

Transfers

Persons

Platform Fees

Reference

Update Payout Destination

Authorizations

Path Parameters

Body

Response