Register a payout bank account

curl --request POST \
  --url https://api.venlyfinance.com/v1/parties/{partyId}/payout-bank-accounts \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data @- <<EOF
{
  "rail": "US_ACH",
  "fiatCurrency": "USD",
  "label": "Jane's checking account",
  "accountHolderName": "Jane Doe",
  "railDetails": {
    "accountNumber": "123456789012",
    "abaRoutingNumber": "021000021",
    "accountType": "CHECKING"
  },
  "bankName": "Example National Bank",
  "bankAddress": {
    "street1": "270 Park Avenue",
    "city": "New York",
    "region": "NY",
    "postalCode": "10017",
    "country": "US"
  }
}
EOF

import requests

url = "https://api.venlyfinance.com/v1/parties/{partyId}/payout-bank-accounts"

payload = {
    "rail": "US_ACH",
    "fiatCurrency": "USD",
    "label": "Jane's checking account",
    "accountHolderName": "Jane Doe",
    "railDetails": {
        "accountNumber": "123456789012",
        "abaRoutingNumber": "021000021",
        "accountType": "CHECKING"
    },
    "bankName": "Example National Bank",
    "bankAddress": {
        "street1": "270 Park Avenue",
        "city": "New York",
        "region": "NY",
        "postalCode": "10017",
        "country": "US"
    }
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

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

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    rail: 'US_ACH',
    fiatCurrency: 'USD',
    label: 'Jane\'s checking account',
    accountHolderName: 'Jane Doe',
    railDetails: {
      accountNumber: '123456789012',
      abaRoutingNumber: '021000021',
      accountType: 'CHECKING'
    },
    bankName: 'Example National Bank',
    bankAddress: {
      street1: '270 Park Avenue',
      city: 'New York',
      region: 'NY',
      postalCode: '10017',
      country: 'US'
    }
  })
};

fetch('https://api.venlyfinance.com/v1/parties/{partyId}/payout-bank-accounts', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.venlyfinance.com/v1/parties/{partyId}/payout-bank-accounts",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'rail' => 'US_ACH',
    'fiatCurrency' => 'USD',
    'label' => 'Jane\'s checking account',
    'accountHolderName' => 'Jane Doe',
    'railDetails' => [
        'accountNumber' => '123456789012',
        'abaRoutingNumber' => '021000021',
        'accountType' => 'CHECKING'
    ],
    'bankName' => 'Example National Bank',
    'bankAddress' => [
        'street1' => '270 Park Avenue',
        'city' => 'New York',
        'region' => 'NY',
        'postalCode' => '10017',
        'country' => 'US'
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

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

func main() {

	url := "https://api.venlyfinance.com/v1/parties/{partyId}/payout-bank-accounts"

	payload := strings.NewReader("{\n  \"rail\": \"US_ACH\",\n  \"fiatCurrency\": \"USD\",\n  \"label\": \"Jane's checking account\",\n  \"accountHolderName\": \"Jane Doe\",\n  \"railDetails\": {\n    \"accountNumber\": \"123456789012\",\n    \"abaRoutingNumber\": \"021000021\",\n    \"accountType\": \"CHECKING\"\n  },\n  \"bankName\": \"Example National Bank\",\n  \"bankAddress\": {\n    \"street1\": \"270 Park Avenue\",\n    \"city\": \"New York\",\n    \"region\": \"NY\",\n    \"postalCode\": \"10017\",\n    \"country\": \"US\"\n  }\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))

}

HttpResponse<String> response = Unirest.post("https://api.venlyfinance.com/v1/parties/{partyId}/payout-bank-accounts")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"rail\": \"US_ACH\",\n  \"fiatCurrency\": \"USD\",\n  \"label\": \"Jane's checking account\",\n  \"accountHolderName\": \"Jane Doe\",\n  \"railDetails\": {\n    \"accountNumber\": \"123456789012\",\n    \"abaRoutingNumber\": \"021000021\",\n    \"accountType\": \"CHECKING\"\n  },\n  \"bankName\": \"Example National Bank\",\n  \"bankAddress\": {\n    \"street1\": \"270 Park Avenue\",\n    \"city\": \"New York\",\n    \"region\": \"NY\",\n    \"postalCode\": \"10017\",\n    \"country\": \"US\"\n  }\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.venlyfinance.com/v1/parties/{partyId}/payout-bank-accounts")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"rail\": \"US_ACH\",\n  \"fiatCurrency\": \"USD\",\n  \"label\": \"Jane's checking account\",\n  \"accountHolderName\": \"Jane Doe\",\n  \"railDetails\": {\n    \"accountNumber\": \"123456789012\",\n    \"abaRoutingNumber\": \"021000021\",\n    \"accountType\": \"CHECKING\"\n  },\n  \"bankName\": \"Example National Bank\",\n  \"bankAddress\": {\n    \"street1\": \"270 Park Avenue\",\n    \"city\": \"New York\",\n    \"region\": \"NY\",\n    \"postalCode\": \"10017\",\n    \"country\": \"US\"\n  }\n}"

response = http.request(request)
puts response.read_body

{
  "success": true,
  "result": {
    "id": "a1b2c3d4-e5f6-4708-9a1b-2c3d4e5f6071",
    "partyId": "7e3b9c2a-1f4d-4a8b-9c11-2d6e8f0a1b22",
    "rail": "US_ACH",
    "fiatCurrency": "USD",
    "label": "Jane's checking account",
    "accountHolderName": "Jane Doe",
    "details": {
      "accountNumberLast4": "9012",
      "abaRoutingNumber": "021000021",
      "accountType": "CHECKING"
    },
    "bankName": "Example National Bank",
    "bankAddress": {
      "street1": "270 Park Avenue",
      "city": "New York",
      "region": "NY",
      "postalCode": "10017",
      "country": "US"
    },
    "status": "PENDING",
    "createdAt": "2026-07-14T09:12:44Z",
    "updatedAt": "2026-07-14T09:12:44Z"
  }
}

{
  "success": false,
  "errors": [
    {
      "code": "invalid-request",
      "message": "The request contains invalid parameters."
    }
  ],
  "result": {}
}

{
  "success": false,
  "errors": [
    {
      "code": "unauthenticated",
      "message": "Please authenticate to perform this action."
    }
  ]
}

{
  "success": false,
  "errors": [
    {
      "code": "invalid-request",
      "message": "The request contains invalid parameters."
    }
  ],
  "result": {}
}

{
  "success": false,
  "errors": [
    {
      "code": "invalid-request",
      "message": "The request contains invalid parameters."
    }
  ],
  "result": {}
}

POST

parties

{partyId}

payout-bank-accounts

curl --request POST \
  --url https://api.venlyfinance.com/v1/parties/{partyId}/payout-bank-accounts \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data @- <<EOF
{
  "rail": "US_ACH",
  "fiatCurrency": "USD",
  "label": "Jane's checking account",
  "accountHolderName": "Jane Doe",
  "railDetails": {
    "accountNumber": "123456789012",
    "abaRoutingNumber": "021000021",
    "accountType": "CHECKING"
  },
  "bankName": "Example National Bank",
  "bankAddress": {
    "street1": "270 Park Avenue",
    "city": "New York",
    "region": "NY",
    "postalCode": "10017",
    "country": "US"
  }
}
EOF

import requests

url = "https://api.venlyfinance.com/v1/parties/{partyId}/payout-bank-accounts"

payload = {
    "rail": "US_ACH",
    "fiatCurrency": "USD",
    "label": "Jane's checking account",
    "accountHolderName": "Jane Doe",
    "railDetails": {
        "accountNumber": "123456789012",
        "abaRoutingNumber": "021000021",
        "accountType": "CHECKING"
    },
    "bankName": "Example National Bank",
    "bankAddress": {
        "street1": "270 Park Avenue",
        "city": "New York",
        "region": "NY",
        "postalCode": "10017",
        "country": "US"
    }
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

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

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    rail: 'US_ACH',
    fiatCurrency: 'USD',
    label: 'Jane\'s checking account',
    accountHolderName: 'Jane Doe',
    railDetails: {
      accountNumber: '123456789012',
      abaRoutingNumber: '021000021',
      accountType: 'CHECKING'
    },
    bankName: 'Example National Bank',
    bankAddress: {
      street1: '270 Park Avenue',
      city: 'New York',
      region: 'NY',
      postalCode: '10017',
      country: 'US'
    }
  })
};

fetch('https://api.venlyfinance.com/v1/parties/{partyId}/payout-bank-accounts', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.venlyfinance.com/v1/parties/{partyId}/payout-bank-accounts",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'rail' => 'US_ACH',
    'fiatCurrency' => 'USD',
    'label' => 'Jane\'s checking account',
    'accountHolderName' => 'Jane Doe',
    'railDetails' => [
        'accountNumber' => '123456789012',
        'abaRoutingNumber' => '021000021',
        'accountType' => 'CHECKING'
    ],
    'bankName' => 'Example National Bank',
    'bankAddress' => [
        'street1' => '270 Park Avenue',
        'city' => 'New York',
        'region' => 'NY',
        'postalCode' => '10017',
        'country' => 'US'
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

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

func main() {

	url := "https://api.venlyfinance.com/v1/parties/{partyId}/payout-bank-accounts"

	payload := strings.NewReader("{\n  \"rail\": \"US_ACH\",\n  \"fiatCurrency\": \"USD\",\n  \"label\": \"Jane's checking account\",\n  \"accountHolderName\": \"Jane Doe\",\n  \"railDetails\": {\n    \"accountNumber\": \"123456789012\",\n    \"abaRoutingNumber\": \"021000021\",\n    \"accountType\": \"CHECKING\"\n  },\n  \"bankName\": \"Example National Bank\",\n  \"bankAddress\": {\n    \"street1\": \"270 Park Avenue\",\n    \"city\": \"New York\",\n    \"region\": \"NY\",\n    \"postalCode\": \"10017\",\n    \"country\": \"US\"\n  }\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))

}

HttpResponse<String> response = Unirest.post("https://api.venlyfinance.com/v1/parties/{partyId}/payout-bank-accounts")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"rail\": \"US_ACH\",\n  \"fiatCurrency\": \"USD\",\n  \"label\": \"Jane's checking account\",\n  \"accountHolderName\": \"Jane Doe\",\n  \"railDetails\": {\n    \"accountNumber\": \"123456789012\",\n    \"abaRoutingNumber\": \"021000021\",\n    \"accountType\": \"CHECKING\"\n  },\n  \"bankName\": \"Example National Bank\",\n  \"bankAddress\": {\n    \"street1\": \"270 Park Avenue\",\n    \"city\": \"New York\",\n    \"region\": \"NY\",\n    \"postalCode\": \"10017\",\n    \"country\": \"US\"\n  }\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.venlyfinance.com/v1/parties/{partyId}/payout-bank-accounts")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"rail\": \"US_ACH\",\n  \"fiatCurrency\": \"USD\",\n  \"label\": \"Jane's checking account\",\n  \"accountHolderName\": \"Jane Doe\",\n  \"railDetails\": {\n    \"accountNumber\": \"123456789012\",\n    \"abaRoutingNumber\": \"021000021\",\n    \"accountType\": \"CHECKING\"\n  },\n  \"bankName\": \"Example National Bank\",\n  \"bankAddress\": {\n    \"street1\": \"270 Park Avenue\",\n    \"city\": \"New York\",\n    \"region\": \"NY\",\n    \"postalCode\": \"10017\",\n    \"country\": \"US\"\n  }\n}"

response = http.request(request)
puts response.read_body

{
  "success": true,
  "result": {
    "id": "a1b2c3d4-e5f6-4708-9a1b-2c3d4e5f6071",
    "partyId": "7e3b9c2a-1f4d-4a8b-9c11-2d6e8f0a1b22",
    "rail": "US_ACH",
    "fiatCurrency": "USD",
    "label": "Jane's checking account",
    "accountHolderName": "Jane Doe",
    "details": {
      "accountNumberLast4": "9012",
      "abaRoutingNumber": "021000021",
      "accountType": "CHECKING"
    },
    "bankName": "Example National Bank",
    "bankAddress": {
      "street1": "270 Park Avenue",
      "city": "New York",
      "region": "NY",
      "postalCode": "10017",
      "country": "US"
    },
    "status": "PENDING",
    "createdAt": "2026-07-14T09:12:44Z",
    "updatedAt": "2026-07-14T09:12:44Z"
  }
}

{
  "success": false,
  "errors": [
    {
      "code": "invalid-request",
      "message": "The request contains invalid parameters."
    }
  ],
  "result": {}
}

{
  "success": false,
  "errors": [
    {
      "code": "unauthenticated",
      "message": "Please authenticate to perform this action."
    }
  ]
}

{
  "success": false,
  "errors": [
    {
      "code": "invalid-request",
      "message": "The request contains invalid parameters."
    }
  ],
  "result": {}
}

{
  "success": false,
  "errors": [
    {
      "code": "invalid-request",
      "message": "The request contains invalid parameters."
    }
  ],
  "result": {}
}

Requires scope: manage:pay-outs — see Required scopes. Allow-lists a beneficiary bank account so it can receive pay-outs. The owning party comes from the path, never the body.

This is the only endpoint that accepts raw rail credentials. The sensitive one — the account number on US_ACH, the IBAN on SEPA — is encrypted at rest immediately and is never returned: this response and every read path expose only accountNumberLast4 or ibanLast4. Routing numbers and BICs are public bank identifiers and are returned in full.

bankAddress is the beneficiary bank’s postal address, not the recipient’s. All components are required, and country must be a valid ISO 3166-1 alpha-2 code. Two rails: US_ACH requires fiatCurrency: USD and ACH railDetails; SEPA requires fiatCurrency: EUR and an iban (with an optional bic). Supply beneficiaryPhoneNumber on every registration — some destinations refuse a beneficiary without it, and a bank account cannot be edited afterwards. beneficiaryEmail is optional and never sent to the payment provider. A new account starts PENDING and becomes ACTIVE once activated for pay-outs. See Pay-outs. Next: pair it with a deposit asset by creating a payout route.

Errors

The codes this endpoint can return, in addition to the standard errors. Branch on code, never the message.

HTTP	`code`	When
`400`	`invalid-rail`	unsupported rail
`400`	`invalid-currency`	currency is inconsistent with the rail (`US_ACH` requires `USD`, `SEPA` requires `EUR`)
`400`	`missing-field`	a required field is absent
`400`	`invalid-account-number`	the account number is not 4–17 digits
`400`	`invalid-routing-number`	the ABA routing number failed its checksum
`400`	`invalid-account-type`	`accountType` is not `CHECKING` or `SAVINGS`
`400`	`invalid-iban`	the IBAN is missing, malformed, fails its check digit, or is not from a SEPA country
`400`	`invalid-bic`	the BIC is not 8 or 11 characters
`400`	`invalid-bank-address`	a bank-address component is missing or `country` is not a valid ISO 3166-1 alpha-2 code

Authorizations

Authorization

string

header

required

OAuth2 client credentials flow. Token endpoints:

Headers

x-tenant-id

string<uuid>

Which tenant the request is scoped to, among those your token grants. Omit it when the token grants exactly one tenant; it is required when the token grants more than one. A supplied value must exactly match a tenant the token grants.

Absent when required, blank, malformed, or naming a tenant the token does not grant — each gets the same generic 403 forbidden, which reveals neither whether a tenant exists nor which ones you may use. Send the header once: a repeated header is rejected the same way.

Example:

"3fa85f64-5717-4562-b3fc-2c963f66afa6"

Path Parameters

partyId

string<uuid>

required

Unique party identifier

Body

application/json

Allow-lists a beneficiary bank account as a pay-out destination. The owning party comes from the path, never the body.

rail

enum<string>

required

The fiat rail a payout bank account settles over. The rail decides which credentials the bank account carries and which fiat currency it must use.

US_ACH — US ACH transfer. Requires fiatCurrency: USD; railDetails carries the ACH account and routing numbers.
SEPA — SEPA credit transfer. Requires fiatCurrency: EUR; railDetails carries an IBAN and an optional BIC.

Available options:

US_ACH,

SEPA

fiatCurrency

string

required

ISO 4217 currency. Must be consistent with the rail — US_ACH requires USD, SEPA requires EUR. A mismatch yields 400 invalid-currency.

Maximum string length: 3

Example:

"USD"

label

string

required

Human-readable label for this destination

Maximum string length: 255

accountHolderName

string

required

Name on the beneficiary bank account

Maximum string length: 255

railDetails

object

required

Raw rail credentials, in the variant matching the request's rail: US_ACH takes the ACH account and routing fields, SEPA takes the IBAN and optional BIC. Send exactly the variant matching the rail. A request missing the matching variant's required fields is rejected with that rail's validation error — invalid-account-number / invalid-routing-number / invalid-account-type, or invalid-iban / invalid-bic.

Option 1
Option 2

Show child attributes

bankName

string

required

Maximum string length: 255

bankAddress

object

required

Structured postal address of the beneficiary's bank — not the recipient's own address. All components are required on registration, and country must be a valid ISO 3166-1 alpha-2 code; anything missing or invalid yields 400 invalid-bank-address.

Show child attributes

beneficiaryEmail

string<email>

Beneficiary contact email, kept on the bank account as your own record of who the destination pays. It is not sent to the payment provider — where a provider needs an address, it receives a Venly-controlled one, so the provider's operational and pricing mail never reaches your beneficiary. Optional; omitting it never refuses a registration.

Maximum string length: 255

Example:

"finance@acme.com"

beneficiaryPhoneNumber

string

Beneficiary contact phone in E.164 form (leading +, no spaces or punctuation). Unlike the email, it is forwarded to the payment provider verbatim and not normalised, so a non-E.164 number is rejected here rather than failing the route registration later. Some destinations refuse a beneficiary without it — a USD route fails terminally with beneficiary-data-incomplete — and a bank account cannot be edited after registration, so supply it on every bank account you register.

Maximum string length: 16

Pattern: ^\+[1-9][0-9]{7,14}$

Example:

"+12125550123"

Response

Bank account registered (masked)

success

boolean

Indicates whether the request was successful

result

object

Masked view of an allow-listed payout bank account.

Show child attributes

Overview

Recipes

Onboarding & Verification

Core Concepts

Parties

Accounts

Virtual Bank Accounts

Supported Assets

Wallets

Transfers

Fiat to Crypto Payment Sessions

Pay-Ins

Payout Bank Accounts

Payout Routes

Payouts

Permits

Allowances

Webhooks

API Credentials

Billing

Company

Reference

Register a payout bank account

Errors

Authorizations

Headers

Path Parameters

Body

Response

​Errors

Authorizations

Headers

Path Parameters

Body

Response

Errors