Register Payee Address

Register a new address for a payee. The required address parameters vary by currency and network type. See the Network Requirements section below for details.

Auth:Bearer <api_key>

Tags:Banking

Request

cURL

curl -X POST https://publicapi.sandbox.hercle.financial/api/v1/payees/{payeeId}/addresses \
  -H "Authorization: Bearer eyJhb..." \
  -H "Content-Type: application/json" \
  -d '{"key": "value"}'

Path Parameters

Name	Type	Required	Description
payeeId	string	Yes	The ID of the payee to add the address for Example: `123e4567-e89b-12d3-a456-426614174000`

Headers

Name	Type	Required	Description
Authorization	string	Yes	Bearer token for authentication
Content-Type	string	Yes	Content type of the request body

Request Body

Schema

object

name*:string

// Name associated with the address

asset*:string

// Asset associated with the address (e.g., USD, EUR)

address*:string

// The payment address

addressParams*:array

// Additional parameters required for the address. Requirements vary by network: ** EUR - Sepa: ** • bic (required): Bank Identifier Code (SWIFT code) ** GBP - Faster Payments: ** • sortcode (required): Sort code of the bank ** USD - INTERNATIONAL_WIRE: ** • accountnumber (required): Bank account number • bic (required): Bank Identifier Code (SWIFT code) • aba (required): American Banking Association routing number • bankname (required): Name of the bank • bankaddressline1 (required): First line of bank's address • bankaddresscity (required): Bank's city • bankaddresspostalcode (required): Bank's postal code • bankcountry (required): Bank's country code ** USD - DOMESTIC_WIRE: ** • accountnumber (required): Bank account number • wire (required): Wire routing number • bankname (required): Name of the bank ** USD - ACH / ACH_SAME_DAY: ** • accountnumber (required): Bank account number • aba (required): ACH routing number • accounttype (required): Account type (CHECKING or SAVINGS)

[item]:object

network*:string

// Network type for the transfer. Available options by currency: ** EUR: ** Sepa (Single Euro Payments Area transfer) ** GBP: ** Faster Payments (Instant transfer within the UK) ** USD: ** INTERNATIONAL_WIRE, DOMESTIC_WIRE, ACH, ACH_SAME_DAY

confirmationStrategy:string

// Strategy for confirming the address. When set to EMAIL, a confirmation link containing the token is sent to the registered email address. When set to API, the token is returned directly in the response.

comment:string

// Optional comment for the address

Example

{
  "name": "John Doe",
  "asset": "EUR",
  "address": "IT60X0542811101000000123456",
  "addressParams": [
    {
      "id": "bic",
      "value": "ABCDITMMXXX"
    }
  ],
  "network": "Sepa",
  "confirmationStrategy": "EMAIL",
  "comment": "My primary EUR address"
}

Response

Success Response Schema

Field	Type	Description
`id`	string	Unique identifier for the payee address
`payeeId`	string	Payee identifier this address belongs to
`name`	string	Name associated with the address
`asset`	string	Asset code (e.g., EUR, USD)
`address`	string	The payment or blockchain address
`addressParams`	array	Additional address parameters
`addressParams[].id`	string	Parameter identifier
`addressParams[].value`	string	Parameter value
`network`	string	Network name (e.g., Sepa, Swift)
`status`	number	Status of the address `0`→ created `1`→ pending `2`→ refused
`confirmationStrategy`	string	Strategy for confirming the address. When set to EMAIL, a confirmation link containing the token is sent to the registered email address. When set to API, the token is returned directly in the response. Allowed values: `EMAIL` `API`
`confirmationToken`	string	Token used for confirming the address. Only returned when confirmationStrategy is API. When confirmationStrategy is EMAIL, the token is included in the confirmation link sent to the email address.
`comment`	string	Optional comment for the address

Responses

201 application/json

{
  "id": "123e4567-e89b-12d3-a456-426614174001",
  "payeeId": "123e4567-e89b-12d3-a456-426614174000",
  "name": "John Doe",
  "asset": "EUR",
  "address": "IT60X0542811101000000123456",
  "addressParams": [
    {
      "id": "bic",
      "value": "ABCDITMMXXX"
    }
  ],
  "network": "Sepa",
  "status": 1,
  "confirmationStrategy": "EMAIL",
  "confirmationToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9",
  "comment": "My primary EUR address"
}

API Tester

Test this endpoint directly against the sandbox environment

API Key

Get your API key from Hercle Sandbox

Path Parameters

payeeId

Required

The ID of the payee to add the address for

Request Body

Request URL

https://publicapi.sandbox.hercle.financial/api/v1/payees/{payeeId}/addresses