Create Beneficiary

curl --request POST \
  --url https://api.hopnow.io/v1/accounts/{account_id}/beneficiaries \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "beneficiary_type": "<string>",
  "title": "<string>",
  "first_name": "<string>",
  "middle_name": "<string>",
  "last_name": "<string>",
  "display_name": "<string>",
  "company_name": "<string>",
  "email": "<string>",
  "phone": "<string>",
  "address": {
    "address_line": "<string>",
    "city": "<string>",
    "region": "<string>",
    "postal_code": "<string>",
    "country": "<string>"
  },
  "tax_id": "<string>",
  "country_code": "<string>",
  "note": "<string>"
}
'

import requests

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

payload = {
    "beneficiary_type": "<string>",
    "title": "<string>",
    "first_name": "<string>",
    "middle_name": "<string>",
    "last_name": "<string>",
    "display_name": "<string>",
    "company_name": "<string>",
    "email": "<string>",
    "phone": "<string>",
    "address": {
        "address_line": "<string>",
        "city": "<string>",
        "region": "<string>",
        "postal_code": "<string>",
        "country": "<string>"
    },
    "tax_id": "<string>",
    "country_code": "<string>",
    "note": "<string>"
}
headers = {
    "X-API-Key": "<api-key>",
    "Content-Type": "application/json"
}

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

print(response.text)

const options = {
  method: 'POST',
  headers: {'X-API-Key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    beneficiary_type: '<string>',
    title: '<string>',
    first_name: '<string>',
    middle_name: '<string>',
    last_name: '<string>',
    display_name: '<string>',
    company_name: '<string>',
    email: '<string>',
    phone: '<string>',
    address: {
      address_line: '<string>',
      city: '<string>',
      region: '<string>',
      postal_code: '<string>',
      country: '<string>'
    },
    tax_id: '<string>',
    country_code: '<string>',
    note: '<string>'
  })
};

fetch('https://api.hopnow.io/v1/accounts/{account_id}/beneficiaries', 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",
  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([
    'beneficiary_type' => '<string>',
    'title' => '<string>',
    'first_name' => '<string>',
    'middle_name' => '<string>',
    'last_name' => '<string>',
    'display_name' => '<string>',
    'company_name' => '<string>',
    'email' => '<string>',
    'phone' => '<string>',
    'address' => [
        'address_line' => '<string>',
        'city' => '<string>',
        'region' => '<string>',
        'postal_code' => '<string>',
        'country' => '<string>'
    ],
    'tax_id' => '<string>',
    'country_code' => '<string>',
    'note' => '<string>'
  ]),
  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"

	payload := strings.NewReader("{\n  \"beneficiary_type\": \"<string>\",\n  \"title\": \"<string>\",\n  \"first_name\": \"<string>\",\n  \"middle_name\": \"<string>\",\n  \"last_name\": \"<string>\",\n  \"display_name\": \"<string>\",\n  \"company_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  \"tax_id\": \"<string>\",\n  \"country_code\": \"<string>\",\n  \"note\": \"<string>\"\n}")

	req, _ := http.NewRequest("POST", 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.post("https://api.hopnow.io/v1/accounts/{account_id}/beneficiaries")
  .header("X-API-Key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"beneficiary_type\": \"<string>\",\n  \"title\": \"<string>\",\n  \"first_name\": \"<string>\",\n  \"middle_name\": \"<string>\",\n  \"last_name\": \"<string>\",\n  \"display_name\": \"<string>\",\n  \"company_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  \"tax_id\": \"<string>\",\n  \"country_code\": \"<string>\",\n  \"note\": \"<string>\"\n}")
  .asString();

require 'uri'
require 'net/http'

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

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

request = Net::HTTP::Post.new(url)
request["X-API-Key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"beneficiary_type\": \"<string>\",\n  \"title\": \"<string>\",\n  \"first_name\": \"<string>\",\n  \"middle_name\": \"<string>\",\n  \"last_name\": \"<string>\",\n  \"display_name\": \"<string>\",\n  \"company_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  \"tax_id\": \"<string>\",\n  \"country_code\": \"<string>\",\n  \"note\": \"<string>\"\n}"

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

{
  "id": "<string>",
  "object": "<string>",
  "account_id": "<string>",
  "beneficiary_type": "<string>",
  "title": "<string>",
  "first_name": "<string>",
  "middle_name": "<string>",
  "last_name": "<string>",
  "display_name": "<string>",
  "company_name": "<string>",
  "email": "<string>",
  "phone": "<string>",
  "address": {
    "address_line": "<string>",
    "city": "<string>",
    "region": "<string>",
    "postal_code": "<string>",
    "country": "<string>"
  },
  "tax_id": "<string>",
  "country_code": "<string>",
  "note": "<string>",
  "status": "<string>",
  "verified": true,
  "payout_destinations": [
    {}
  ],
  "created": "<string>",
  "updated": "<string>"
}

POST

accounts

{account_id}

beneficiaries

Create Beneficiary

curl --request POST \
  --url https://api.hopnow.io/v1/accounts/{account_id}/beneficiaries \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "beneficiary_type": "<string>",
  "title": "<string>",
  "first_name": "<string>",
  "middle_name": "<string>",
  "last_name": "<string>",
  "display_name": "<string>",
  "company_name": "<string>",
  "email": "<string>",
  "phone": "<string>",
  "address": {
    "address_line": "<string>",
    "city": "<string>",
    "region": "<string>",
    "postal_code": "<string>",
    "country": "<string>"
  },
  "tax_id": "<string>",
  "country_code": "<string>",
  "note": "<string>"
}
'

import requests

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

payload = {
    "beneficiary_type": "<string>",
    "title": "<string>",
    "first_name": "<string>",
    "middle_name": "<string>",
    "last_name": "<string>",
    "display_name": "<string>",
    "company_name": "<string>",
    "email": "<string>",
    "phone": "<string>",
    "address": {
        "address_line": "<string>",
        "city": "<string>",
        "region": "<string>",
        "postal_code": "<string>",
        "country": "<string>"
    },
    "tax_id": "<string>",
    "country_code": "<string>",
    "note": "<string>"
}
headers = {
    "X-API-Key": "<api-key>",
    "Content-Type": "application/json"
}

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

print(response.text)

const options = {
  method: 'POST',
  headers: {'X-API-Key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    beneficiary_type: '<string>',
    title: '<string>',
    first_name: '<string>',
    middle_name: '<string>',
    last_name: '<string>',
    display_name: '<string>',
    company_name: '<string>',
    email: '<string>',
    phone: '<string>',
    address: {
      address_line: '<string>',
      city: '<string>',
      region: '<string>',
      postal_code: '<string>',
      country: '<string>'
    },
    tax_id: '<string>',
    country_code: '<string>',
    note: '<string>'
  })
};

fetch('https://api.hopnow.io/v1/accounts/{account_id}/beneficiaries', 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",
  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([
    'beneficiary_type' => '<string>',
    'title' => '<string>',
    'first_name' => '<string>',
    'middle_name' => '<string>',
    'last_name' => '<string>',
    'display_name' => '<string>',
    'company_name' => '<string>',
    'email' => '<string>',
    'phone' => '<string>',
    'address' => [
        'address_line' => '<string>',
        'city' => '<string>',
        'region' => '<string>',
        'postal_code' => '<string>',
        'country' => '<string>'
    ],
    'tax_id' => '<string>',
    'country_code' => '<string>',
    'note' => '<string>'
  ]),
  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"

	payload := strings.NewReader("{\n  \"beneficiary_type\": \"<string>\",\n  \"title\": \"<string>\",\n  \"first_name\": \"<string>\",\n  \"middle_name\": \"<string>\",\n  \"last_name\": \"<string>\",\n  \"display_name\": \"<string>\",\n  \"company_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  \"tax_id\": \"<string>\",\n  \"country_code\": \"<string>\",\n  \"note\": \"<string>\"\n}")

	req, _ := http.NewRequest("POST", 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.post("https://api.hopnow.io/v1/accounts/{account_id}/beneficiaries")
  .header("X-API-Key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"beneficiary_type\": \"<string>\",\n  \"title\": \"<string>\",\n  \"first_name\": \"<string>\",\n  \"middle_name\": \"<string>\",\n  \"last_name\": \"<string>\",\n  \"display_name\": \"<string>\",\n  \"company_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  \"tax_id\": \"<string>\",\n  \"country_code\": \"<string>\",\n  \"note\": \"<string>\"\n}")
  .asString();

require 'uri'
require 'net/http'

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

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

request = Net::HTTP::Post.new(url)
request["X-API-Key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"beneficiary_type\": \"<string>\",\n  \"title\": \"<string>\",\n  \"first_name\": \"<string>\",\n  \"middle_name\": \"<string>\",\n  \"last_name\": \"<string>\",\n  \"display_name\": \"<string>\",\n  \"company_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  \"tax_id\": \"<string>\",\n  \"country_code\": \"<string>\",\n  \"note\": \"<string>\"\n}"

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

{
  "id": "<string>",
  "object": "<string>",
  "account_id": "<string>",
  "beneficiary_type": "<string>",
  "title": "<string>",
  "first_name": "<string>",
  "middle_name": "<string>",
  "last_name": "<string>",
  "display_name": "<string>",
  "company_name": "<string>",
  "email": "<string>",
  "phone": "<string>",
  "address": {
    "address_line": "<string>",
    "city": "<string>",
    "region": "<string>",
    "postal_code": "<string>",
    "country": "<string>"
  },
  "tax_id": "<string>",
  "country_code": "<string>",
  "note": "<string>",
  "status": "<string>",
  "verified": true,
  "payout_destinations": [
    {}
  ],
  "created": "<string>",
  "updated": "<string>"
}

Path Parameters

string

required

The account’s external ID (starts with acc_)

Request Body

string

default:"individual"

Type of beneficiary: individual or business

string

Title (e.g., Mr, Ms, Dr) - max 20 characters

string

required

First name (max 100 characters)

string

Middle name (max 100 characters)

string

required

Last name (max 100 characters)

string

required

Display name for the beneficiary (max 255 characters)

string

Company name (required for business beneficiaries, max 255 characters)

string

required

Email address (max 255 characters)

string

required

Phone number with country code (max 50 characters)

object

required

Beneficiary address

Show Address fields

string

required

Complete street address

string

required

City name (max 100 characters)

string

required

State/Province/Region (max 100 characters)

string

required

Postal code (max 20 characters)

string

required

ISO 3166-1 alpha-2 country code

string

Tax identification number (max 50 characters)

string

required

Payout country code (ISO 3166-1 alpha-2)

string

Internal notes or comments

Response

string

Beneficiary identifier (starts with bene_)

string

Always returns "beneficiary"

string

Parent account external ID

string

Beneficiary type: individual or business

string

Title (e.g., Mr, Ms, Dr)

string

First name

string

Middle name

string

Last name

string

Display name

string

Company name

string

Email address

string

Phone number

object

Beneficiary address

Show Address Fields

string

Street address

string

City name

string

State/Province/Region

string

Postal code

string

ISO 3166-1 alpha-2 country code

string

Tax identification number

string

Payout country code

string

Internal notes or comments

string

Beneficiary status: active, disabled, or inactive

boolean

Whether beneficiary has been verified

array

Array of payout destination objects

string

ISO 8601 timestamp when created

string

ISO 8601 timestamp when last updated

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.doe@example.com",
  "phone": "+1234567890",
  "address": {
    "address_line": "123 Main St",
    "city": "New York",
    "region": "NY",
    "postal_code": "10001",
    "country": "US"
  },
  "country_code": "US",
  "status": "active",
  "verified": false,
  "payout_destinations": [],
  "created": "2024-01-15T10:00:00Z",
  "updated": "2024-01-15T10:00:00Z"
}

Delete Wallet List Beneficiaries

Getting Started

Guides

Webhooks

API Reference

Endpoints

Create Beneficiary

Path Parameters

Request Body

Response

Response Example

​Path Parameters

​Request Body

​Response

​Response Example

Path Parameters

Request Body

Response

Response Example