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

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

Maximum string length: 50

Example:

null

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_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:

null

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.

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

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

Media

Misc

Transfers

Persons

Platform Fees

Reference

Update Payout Destination

Authorizations

Path Parameters

Body

Response