Update Beneficiary

curl --request PATCH \
  --url https://api.hopnow.io/v1/accounts/{account_id}/beneficiaries/{beneficiary_id} \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "display_name": "<string>",
  "email": "<string>",
  "phone": "<string>",
  "address": {
    "address_line": "<string>",
    "city": "<string>",
    "region": "<string>",
    "postal_code": "<string>",
    "country": "<string>"
  },
  "country_code": "<string>",
  "self_owned": true
}
'

import requests

url = "https://api.hopnow.io/v1/accounts/{account_id}/beneficiaries/{beneficiary_id}"

payload = {
    "display_name": "<string>",
    "email": "<string>",
    "phone": "<string>",
    "address": {
        "address_line": "<string>",
        "city": "<string>",
        "region": "<string>",
        "postal_code": "<string>",
        "country": "<string>"
    },
    "country_code": "<string>",
    "self_owned": True
}
headers = {
    "X-API-Key": "<api-key>",
    "Content-Type": "application/json"
}

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

print(response.text)

const options = {
  method: 'PATCH',
  headers: {'X-API-Key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    display_name: '<string>',
    email: '<string>',
    phone: '<string>',
    address: {
      address_line: '<string>',
      city: '<string>',
      region: '<string>',
      postal_code: '<string>',
      country: '<string>'
    },
    country_code: '<string>',
    self_owned: true
  })
};

fetch('https://api.hopnow.io/v1/accounts/{account_id}/beneficiaries/{beneficiary_id}', 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.hopnow.io/v1/accounts/{account_id}/beneficiaries/{beneficiary_id}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "PATCH",
  CURLOPT_POSTFIELDS => json_encode([
    'display_name' => '<string>',
    'email' => '<string>',
    'phone' => '<string>',
    'address' => [
        'address_line' => '<string>',
        'city' => '<string>',
        'region' => '<string>',
        'postal_code' => '<string>',
        'country' => '<string>'
    ],
    'country_code' => '<string>',
    'self_owned' => true
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "X-API-Key: <api-key>"
  ],
]);

$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.hopnow.io/v1/accounts/{account_id}/beneficiaries/{beneficiary_id}"

	payload := strings.NewReader("{\n  \"display_name\": \"<string>\",\n  \"email\": \"<string>\",\n  \"phone\": \"<string>\",\n  \"address\": {\n    \"address_line\": \"<string>\",\n    \"city\": \"<string>\",\n    \"region\": \"<string>\",\n    \"postal_code\": \"<string>\",\n    \"country\": \"<string>\"\n  },\n  \"country_code\": \"<string>\",\n  \"self_owned\": true\n}")

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

	req.Header.Add("X-API-Key", "<api-key>")
	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.patch("https://api.hopnow.io/v1/accounts/{account_id}/beneficiaries/{beneficiary_id}")
  .header("X-API-Key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"display_name\": \"<string>\",\n  \"email\": \"<string>\",\n  \"phone\": \"<string>\",\n  \"address\": {\n    \"address_line\": \"<string>\",\n    \"city\": \"<string>\",\n    \"region\": \"<string>\",\n    \"postal_code\": \"<string>\",\n    \"country\": \"<string>\"\n  },\n  \"country_code\": \"<string>\",\n  \"self_owned\": true\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.hopnow.io/v1/accounts/{account_id}/beneficiaries/{beneficiary_id}")

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

request = Net::HTTP::Patch.new(url)
request["X-API-Key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"display_name\": \"<string>\",\n  \"email\": \"<string>\",\n  \"phone\": \"<string>\",\n  \"address\": {\n    \"address_line\": \"<string>\",\n    \"city\": \"<string>\",\n    \"region\": \"<string>\",\n    \"postal_code\": \"<string>\",\n    \"country\": \"<string>\"\n  },\n  \"country_code\": \"<string>\",\n  \"self_owned\": true\n}"

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

PATCH

accounts

{account_id}

beneficiaries

{beneficiary_id}

Update Beneficiary

curl --request PATCH \
  --url https://api.hopnow.io/v1/accounts/{account_id}/beneficiaries/{beneficiary_id} \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "display_name": "<string>",
  "email": "<string>",
  "phone": "<string>",
  "address": {
    "address_line": "<string>",
    "city": "<string>",
    "region": "<string>",
    "postal_code": "<string>",
    "country": "<string>"
  },
  "country_code": "<string>",
  "self_owned": true
}
'

import requests

url = "https://api.hopnow.io/v1/accounts/{account_id}/beneficiaries/{beneficiary_id}"

payload = {
    "display_name": "<string>",
    "email": "<string>",
    "phone": "<string>",
    "address": {
        "address_line": "<string>",
        "city": "<string>",
        "region": "<string>",
        "postal_code": "<string>",
        "country": "<string>"
    },
    "country_code": "<string>",
    "self_owned": True
}
headers = {
    "X-API-Key": "<api-key>",
    "Content-Type": "application/json"
}

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

print(response.text)

const options = {
  method: 'PATCH',
  headers: {'X-API-Key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    display_name: '<string>',
    email: '<string>',
    phone: '<string>',
    address: {
      address_line: '<string>',
      city: '<string>',
      region: '<string>',
      postal_code: '<string>',
      country: '<string>'
    },
    country_code: '<string>',
    self_owned: true
  })
};

fetch('https://api.hopnow.io/v1/accounts/{account_id}/beneficiaries/{beneficiary_id}', 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.hopnow.io/v1/accounts/{account_id}/beneficiaries/{beneficiary_id}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "PATCH",
  CURLOPT_POSTFIELDS => json_encode([
    'display_name' => '<string>',
    'email' => '<string>',
    'phone' => '<string>',
    'address' => [
        'address_line' => '<string>',
        'city' => '<string>',
        'region' => '<string>',
        'postal_code' => '<string>',
        'country' => '<string>'
    ],
    'country_code' => '<string>',
    'self_owned' => true
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "X-API-Key: <api-key>"
  ],
]);

$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.hopnow.io/v1/accounts/{account_id}/beneficiaries/{beneficiary_id}"

	payload := strings.NewReader("{\n  \"display_name\": \"<string>\",\n  \"email\": \"<string>\",\n  \"phone\": \"<string>\",\n  \"address\": {\n    \"address_line\": \"<string>\",\n    \"city\": \"<string>\",\n    \"region\": \"<string>\",\n    \"postal_code\": \"<string>\",\n    \"country\": \"<string>\"\n  },\n  \"country_code\": \"<string>\",\n  \"self_owned\": true\n}")

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

	req.Header.Add("X-API-Key", "<api-key>")
	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.patch("https://api.hopnow.io/v1/accounts/{account_id}/beneficiaries/{beneficiary_id}")
  .header("X-API-Key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"display_name\": \"<string>\",\n  \"email\": \"<string>\",\n  \"phone\": \"<string>\",\n  \"address\": {\n    \"address_line\": \"<string>\",\n    \"city\": \"<string>\",\n    \"region\": \"<string>\",\n    \"postal_code\": \"<string>\",\n    \"country\": \"<string>\"\n  },\n  \"country_code\": \"<string>\",\n  \"self_owned\": true\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.hopnow.io/v1/accounts/{account_id}/beneficiaries/{beneficiary_id}")

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

request = Net::HTTP::Patch.new(url)
request["X-API-Key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"display_name\": \"<string>\",\n  \"email\": \"<string>\",\n  \"phone\": \"<string>\",\n  \"address\": {\n    \"address_line\": \"<string>\",\n    \"city\": \"<string>\",\n    \"region\": \"<string>\",\n    \"postal_code\": \"<string>\",\n    \"country\": \"<string>\"\n  },\n  \"country_code\": \"<string>\",\n  \"self_owned\": true\n}"

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

Updates the contact and payout-country details of a beneficiary. Every field is optional; send only the ones you want to change. Name and type fields cannot be changed after creation. beneficiary_type, title, first_name, middle_name, last_name and company_name are not part of this request body. To correct a name, create a new beneficiary. Requires an API key with write access on the payments scope.

Path Parameters

string

required

The account’s external ID (starts with acct_)

string

required

The beneficiary’s external ID (starts with bene_)

Request Body

A field set to null, or left out entirely, leaves the stored value unchanged. Fields cannot be cleared back to null.

string

Display name (max 255 characters)

string

Email address (max 255 characters). It must contain an @, the same check create applies.

string

Phone number with country code (max 50 characters)

object

Beneficiary address. The address is replaced wholesale, so send every field you want to keep, and address_line, city and country must each be present and non-empty, the same check create applies. Omitting address entirely leaves the stored one untouched.

Show Address fields

string

required

Complete street address

string

required

City name (max 100 characters)

string

State, province, or region (max 100 characters)

string

Postal code (max 20 characters)

string

required

ISO 3166-1 alpha-2 country code

string

Payout country as an ISO 3166-1 alpha-2 code. A country Hop does not deliver to is rejected with 422. See Rejected countries.

boolean

Whether the beneficiary is the account holder’s own bank account at another institution. Only a self-owned beneficiary can be paid from the trading account (a withdrawal); third-party beneficiaries are paid from a virtual account (a payout). See Create Payout.

Response

Returns the updated beneficiary object, the same shape as Get Beneficiary.

Errors

Status	`code`	When
`422`	`VALIDATION_ERROR`	The body carries a field this endpoint does not accept; `validation_errors` names it
`404`	`RESOURCE_NOT_FOUND`	No such beneficiary, it belongs to another account, or it has been deleted
`422`	`VALIDATION_ERROR`	The body failed schema validation, for example an unsupported `country_code` or a value over its maximum length; `validation_errors` lists each field
`422`	`INVALID_FIELD_FORMAT`	`email` does not contain an `@`; `details` carry the value and the expected format
`422`	`MISSING_REQUIRED_FIELD`	An `address` was sent with `address_line`, `city` or `country` empty; `details.field` names it

Request Example

{
  "email": "john.smith@example.com",
  "phone": "+1987654321",
  "address": {
    "address_line": "500 Market St",
    "city": "San Francisco",
    "region": "CA",
    "postal_code": "94105",
    "country": "US"
  }
}

Response Example

{
  "id": "bene_9gt1ummgx127biovlurm9mq2",
  "object": "beneficiary",
  "account_id": "acct_ka44qsvpo8q3wtzuwfqf0h6u",
  "beneficiary_type": "individual",
  "title": null,
  "first_name": "John",
  "middle_name": null,
  "last_name": "Doe",
  "display_name": "John Doe",
  "company_name": null,
  "email": "john.smith@example.com",
  "phone": "+1987654321",
  "address": {
    "address_line": "500 Market St",
    "city": "San Francisco",
    "region": "CA",
    "postal_code": "94105",
    "country": "US"
  },
  "country_code": "US",
  "status": "active",
  "verified": false,
  "self_owned": false,
  "payout_destinations": [],
  "created": "2026-01-15T10:00:00Z",
  "updated": "2026-01-16T10:00:00Z",
  "created_by": "ak_0ub5w2xr8yl3qks6tcdn7m4v",
  "updated_by": "ak_0ub5w2xr8yl3qks6tcdn7m4v"
}

Getting started

API basics

Endpoints

Webhooks

Update Beneficiary

Path Parameters

Request Body

Response

Errors

Request Example

Response Example

​Path Parameters

​Request Body

​Response

​Errors

​Request Example

​Response Example

Path Parameters

Request Body

Response

Errors

Request Example

Response Example