Beneficiaries

Use Beneficiaries to register and manage payees before initiating payouts. Each registered payee is assigned a beneficiaryId, which is used to reference the payee when making a payout instead of submitting raw bank details.

The required beneficiary information varies by country, currency, entity type, and payment method. Use the Supported Corridors and Beneficiary Schema APIs to determine the required fields and supported clearing systems for the selected payment corridor, then create the beneficiary with the appropriate details.

Supported Corridors

Returns all supported currency, entity type, payment method, and clearing system combinations available for beneficiary registration.

{{baseUrl}}/hashdt/banking/api/v1/beneficiaries/options

Description

This API is used to retrieve the supported beneficiary registration corridors, including the beneficiary bank country, currency, entity type, and available payment methods. The returned values can be used with the Beneficiary Schema API to determine the required beneficiary details and supported clearing systems. Use the currency filter to narrow the results and retrieve more targeted corridor options.

📩 Request Headers

x-api-key string required

Shared X-API key

x-product-id string required

Shared Product ID

x-request-id string required

Idempotency key for request tracking

x-user-id string required

User identification key

Content-Type string required

Must be application/json

Authorization string required

Bearer access token

🔍 Query Parameters

currency string

Filter supported beneficiary corridors by currency using the 3-letter ISO 4217 currency code.

🧩 Examples

Request Example

cURL
Python
Java
NodeJs

curl --location --request GET \
--url '{{baseUrl}}/hashdt/banking/api/v1/beneficiaries/options' \
--header 'x-api-key: {{Shared X-API key}}' \
--header 'x-product-id: {{Shared ProductID}}' \
--header 'x-request-id: {{IdempotencyKey}}' \
--header 'x-user-id: {{UserID}}' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{AccessToken}}'

import requests
import json

url = "{{baseUrl}}/hashdt/banking/api/v1/beneficiaries/options"

payload = {}
headers = {
  'x-api-key': '{{Shared X-API key}}',
  'x-product-id': '{{Shared ProductID}}',
  'x-request-id': '{{IdempotencyKey}}',
  'x-user-id': '{{UserID}}',
  'Content-Type': 'application/json',
  'Authorization': 'Bearer {{AccessToken}}'
}

response = requests.request("GET", url, headers=headers, data=payload)

print(response.text)

OkHttpClient client = new OkHttpClient().newBuilder()
  .build();
MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create(mediaType, "");
Request request = new Request.Builder()
  .url("{{baseUrl}}/hashdt/banking/api/v1/beneficiaries/options")
  .method("GET", body)
  .addHeader("x-api-key", "{{Shared X-API key}}")
  .addHeader("x-product-id", "{{Shared ProductID}}")
  .addHeader("x-request-id", "{{IdempotencyKey}}")
  .addHeader("x-user-id", "{{UserID}}")
  .addHeader("Content-Type", "application/json")
  .addHeader("Authorization", "Bearer {{AccessToken}}")
  .build();
Response response = client.newCall(request).execute();

const axios = require('axios');

let config = {
  method: 'get',
  maxBodyLength: Infinity,
  url: '{{baseUrl}}/hashdt/banking/api/v1/beneficiaries/options',
  headers: { 
    'x-api-key': '{{Shared X-API key}}', 
    'x-product-id': '{{Shared ProductID}}', 
    'x-request-id': '{{IdempotencyKey}}', 
    'x-user-id': '{{UserID}}', 
    'Content-Type': 'application/json', 
    'Authorization': 'Bearer {{AccessToken}}'
  }
};

axios.request(config)
.then((response) => {
  console.log(JSON.stringify(response.data));
})
.catch((error) => {
  console.log(error);
});

Response Example

{
  "code": 200,
  "status": "SUCCESS",
  "message": "Success",
  "data": [
    {
      "currency": "usd",
      "country": "US",
      "entityType": "INDIVIDUAL",
      "paymentMethod": "LOCAL",
      "description": "Local-rail payout - individual beneficiary"
    },
    {
      "currency": "usd",
      "country": "US",
      "entityType": "INDIVIDUAL",
      "paymentMethod": "SWIFT",
      "description": "International (SWIFT) payout - individual beneficiary"
    },
    {
      "currency": "usd",
      "country": "US",
      "entityType": "COMPANY",
      "paymentMethod": "LOCAL",
      "description": "Local-rail payout - company beneficiary"
    },
    {
      "currency": "usd",
      "country": "US",
      "entityType": "COMPANY",
      "paymentMethod": "SWIFT",
      "description": "International (SWIFT) payout - company beneficiary"
    }
  ]
}

{
  "code": 400,
  "status": "error",
  "message": "Error Message"
}

Beneficiary Schema

Returns the required beneficiary fields and supported clearing systems for a specific payment corridor.

{{baseUrl}}/hashdt/banking/api/v1/beneficiaries/schema

Description

This API is used to retrieve the JSON Schema that defines the beneficiary details required for a specific country, currency, entity type, and payment method. The response also provides the available clearing systems through bank.extras.clearingSystem.

Call the API first without clearingSystem to retrieve the available rails. After a rail is selected, call it again with clearingSystem to retrieve the corridor-specific schema, including the required routingCodeType. The country parameter represents the payee's bank country and should be provided explicitly when the bank is located outside the currency's home country.

📩 Request Headers

x-api-key string required

Shared X-API key

x-product-id string required

Shared Product ID

x-request-id string required

Idempotency key for request tracking

x-user-id string required

User identification key

Content-Type string required

Must be application/json

Authorization string required

Bearer access token

🔍 Query Parameters

currency string required

Currency of the beneficiary account using the 3-letter ISO 4217 currency code.

entityType string required

Type of entity receiving the funds. Allowed values: INDIVIDUAL or COMPANY.

paymentMethod string required

Payment method or transfer rail used to send funds to the beneficiary. Allowed values: LOCAL or SWIFT.

country string

Country where the beneficiary's bank account is held, specified as a 2-letter ISO 3166-1 country code.

clearingSystem string

Clearing system or rail selected for the beneficiary. When provided, the response returns the routing code type required by the selected clearing system.

🧩 Examples

Request Example

cURL
Python
Java
NodeJs

curl --location --request GET \
--url '{{baseUrl}}/hashdt/banking/api/v1/beneficiaries/schema?currency=USD&entityType=INDIVIDUAL&paymentMethod=LOCAL' \
--header 'x-api-key: {{Shared X-API key}}' \
--header 'x-product-id: {{Shared ProductID}}' \
--header 'x-request-id: {{IdempotencyKey}}' \
--header 'x-user-id: {{UserID}}' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{AccessToken}}'

import requests
import json

url = "{{baseUrl}}/hashdt/banking/api/v1/beneficiaries/schema?currency=USD&entityType=INDIVIDUAL&paymentMethod=LOCAL"

payload = {}
headers = {
  'x-api-key': '{{Shared X-API key}}',
  'x-product-id': '{{Shared ProductID}}',
  'x-request-id': '{{IdempotencyKey}}',
  'x-user-id': '{{UserID}}',
  'Content-Type': 'application/json',
  'Authorization': 'Bearer {{AccessToken}}'
}

response = requests.request("GET", url, headers=headers, data=payload)

print(response.text)

OkHttpClient client = new OkHttpClient().newBuilder()
  .build();
MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create(mediaType, "");
Request request = new Request.Builder()
  .url("{{baseUrl}}/hashdt/banking/api/v1/beneficiaries/schema?currency=USD&entityType=INDIVIDUAL&paymentMethod=LOCAL")
  .method("GET", body)
  .addHeader("x-api-key", "{{Shared X-API key}}")
  .addHeader("x-product-id", "{{Shared ProductID}}")
  .addHeader("x-request-id", "{{IdempotencyKey}}")
  .addHeader("x-user-id", "{{UserID}}")
  .addHeader("Content-Type", "application/json")
  .addHeader("Authorization", "Bearer {{AccessToken}}")
  .build();
Response response = client.newCall(request).execute();

const axios = require('axios');

let config = {
  method: 'get',
  maxBodyLength: Infinity,
  url: '{{baseUrl}}/hashdt/banking/api/v1/beneficiaries/schema?currency=USD&entityType=INDIVIDUAL&paymentMethod=LOCAL',
  headers: { 
    'x-api-key': '{{Shared X-API key}}', 
    'x-product-id': '{{Shared ProductID}}', 
    'x-request-id': '{{IdempotencyKey}}', 
    'x-user-id': '{{UserID}}', 
    'Content-Type': 'application/json', 
    'Authorization': 'Bearer {{AccessToken}}'
  }
};

axios.request(config)
.then((response) => {
  console.log(JSON.stringify(response.data));
})
.catch((error) => {
  console.log(error);
});

Response Example

{
  "code": 200,
  "status": "SUCCESS",
  "message": "Success",
  "data": {
    "$schema": "https://json-schema.org/draft/2020-12/schema",
    "title": "INDIVIDUAL beneficiary — USD LOCAL (US)",
    "type": "object",
    "required": [
      "companyCode",
      "entityType",
      "currency",
      "firstName",
      "lastName",
      "bank",
      "extras",
      "address"
    ],
    "properties": {
      "email": {
        "type": "string",
        "title": "Email"
      },
      "displayName": {
        "type": "string",
        "title": "Nickname"
      },
      "companyCode": {
        "type": "string",
        "title": "Company code"
      },
      "entityType": {
        "enum": [
          "INDIVIDUAL"
        ],
        "type": "string",
        "title": "Entity type"
      },
      "currency": {
        "enum": [
          "USD"
        ],
        "type": "string",
        "title": "Currency"
      },
      "country": {
        "type": "string",
        "title": "Beneficiary country"
      },
      "firstName": {
        "type": "string",
        "title": "First name"
      },
      "lastName": {
        "type": "string",
        "title": "Last name"
      },
      "bank": {
        "type": "object",
        "properties": {
          "bankCountry": {
            "type": "string",
            "title": "Bank country"
          },
          "accountCurrency": {
            "type": "string",
            "title": "Account currency"
          },
          "accountHolder": {
            "type": "string",
            "title": "Account holder"
          },
          "extras": {
            "type": "object",
            "properties": {
              "clearingSystem": {
                "type": "string",
                "title": "Clearing system",
                "enum": [
                  "ACH",
                  "FEDWIRE",
                  "LOCAL"
                ]
              }
            },
            "required": [
              "clearingSystem"
            ]
          },
          "bankName": {
            "type": "string",
            "title": "Bank name"
          },
          "bankAddress": {
            "type": "string",
            "title": "Bank address"
          },
          "accountNumber": {
            "type": "string",
            "title": "Account number"
          },
          "iban": {
            "type": "string",
            "title": "IBAN"
          },
          "routingCodeType": {
            "type": "string",
            "title": "Routing code type",
            "enum": [
              "aba",
              "ach"
            ]
          },
          "routingCodeValue": {
            "type": "string",
            "title": "Routing code"
          },
          "swiftCode": {
            "type": "string",
            "title": "SWIFT / BIC"
          }
        },
        "required": [
          "bankCountry",
          "accountCurrency",
          "accountHolder",
          "extras"
        ],
        "anyOf": [
          {
            "required": [
              "accountNumber"
            ]
          },
          {
            "required": [
              "iban"
            ]
          }
        ]
      },
      "address": {
        "type": "object",
        "properties": {
          "country": {
            "type": "string",
            "title": "Country"
          },
          "city": {
            "type": "string",
            "title": "City"
          },
          "streetAddress": {
            "type": "string",
            "title": "Street address"
          },
          "postalCode": {
            "type": "string",
            "title": "Postal code"
          },
          "state": {
            "type": "string",
            "title": "State"
          },
          "nationality": {
            "type": "string",
            "title": "Nationality"
          }
        },
        "required": [
          "country"
        ]
      },
      "extras": {
        "type": "object",
        "properties": {
          "paymentMethod": {
            "enum": [
              "LOCAL"
            ],
            "type": "string",
            "title": "Payment method"
          }
        },
        "required": [
          "paymentMethod"
        ]
      }
    },
    "allOf": [
      {
        "if": {
          "properties": {
            "bank": {
              "properties": {
                "extras": {
                  "properties": {
                    "clearingSystem": {
                      "const": "ACH"
                    }
                  },
                  "required": [
                    "clearingSystem"
                  ]
                }
              },
              "required": [
                "extras"
              ]
            }
          },
          "required": [
            "bank"
          ]
        },
        "then": {
          "properties": {
            "bank": {
              "required": [
                "bankCountry",
                "accountCurrency",
                "accountHolder",
                "accountNumber",
                "routingCodeType",
                "routingCodeValue",
                "swiftCode",
                "bankName",
                "bankAddress"
              ],
              "properties": {
                "routingCodeType": {
                  "const": "ach"
                }
              }
            },
            "address": {
              "required": [
                "country",
                "city",
                "streetAddress",
                "postalCode",
                "state"
              ]
            }
          },
          "required": [
            "address"
          ]
        }
      },
      {
        "if": {
          "properties": {
            "bank": {
              "properties": {
                "extras": {
                  "properties": {
                    "clearingSystem": {
                      "const": "FEDWIRE"
                    }
                  },
                  "required": [
                    "clearingSystem"
                  ]
                }
              },
              "required": [
                "extras"
              ]
            }
          },
          "required": [
            "bank"
          ]
        },
        "then": {
          "properties": {
            "bank": {
              "required": [
                "bankCountry",
                "accountCurrency",
                "accountHolder",
                "accountNumber",
                "routingCodeType",
                "routingCodeValue",
                "swiftCode",
                "bankName",
                "bankAddress"
              ],
              "properties": {
                "routingCodeType": {
                  "const": "aba"
                }
              }
            },
            "address": {
              "required": [
                "country",
                "city",
                "streetAddress",
                "postalCode",
                "state"
              ]
            }
          },
          "required": [
            "address"
          ]
        }
      }
    ]
  }
}

{
  "code": 400,
  "status": "error",
  "message": "Error Message"
}

Create Beneficiary

Registers a beneficiary for payouts.

{{baseUrl}}/hashdt/banking/api/v1/beneficiaries

Description

This API is used to register a beneficiary with the bank for future payouts. The request must include exactly the fields specified by the Beneficiary Schema API for the selected payment corridor. Requirements may vary based on the beneficiary's country, currency, entity type, and payment method.
Optional fields should be omitted when not applicable rather than sent as empty strings. Once successfully registered, the API returns a beneficiary_id, which is used to identify the beneficiary when initiating payouts.

📩 Request Headers

x-api-key string required

Shared X-API key

x-product-id string required

Shared Product ID

x-request-id string required

Idempotency key for request tracking

x-user-id string required

User identification key

Content-Type string required

Must be application/json

Authorization string required

Bearer access token

📦 Request Body

companyCode string required

Shared Company Code.

entityType string required

Type of beneficiary entity. Allowed values: INDIVIDUAL or COMPANY

displayName string required

Display name used to identify the beneficiary.

firstName string

First name of the individual beneficiary.

lastName string

Last name of the individual beneficiary.

companyName string

Name of the company associated with the beneficiary.

email string

Email address associated with the beneficiary.

currency string required

Currency in which the beneficiary will receive funds, using the 3-letter ISO 4217 currency code.

country string

Country of the beneficiary, using the 2-letter ISO 3166-1 country code.

address object

Beneficiary's address details.

country string

Country of the beneficiary's address, using the 2-letter ISO 3166-1 country code.

nationality string

Nationality of the beneficiary, using the 2-letter ISO 3166-1 country code.

city string

City of the beneficiary's address.

streetAddress string

Street address of the beneficiary.

postalCode string

Postal or ZIP code of the beneficiary's address.

state string

State or province of the beneficiary's address.

bank object required

Bank account and banking details of the beneficiary.

bankName string

Name of the beneficiary's bank.

bankAddress string

Address of the beneficiary's bank.

bankCountry string

Country where the beneficiary's bank is located, using the 2-letter ISO 3166-1 country code.

accountHolder string

Name of the account holder as registered with the beneficiary's bank.

accountCurrency string

Currency of the beneficiary's bank account, using the 3-letter ISO 4217 currency code.

accountNumber string

Bank account number of the beneficiary.

iban string

International Bank Account Number (IBAN) of the beneficiary's bank account, when required for the selected payment corridor.

swiftCode string

SWIFT/BIC code of the beneficiary's bank, when required for the selected payment corridor.

routingCodeType string

Type of the primary bank routing code required for the selected payment corridor.

routingCodeValue string

Value of the primary bank routing code.

routingCodeType2 string

Type of the secondary bank routing code, when required for the selected payment corridor.

routingCodeValue2 string

Value of the secondary bank routing code.

extras object

Additional bank details required for the selected payment corridor.

clearingSystem string

Clearing system selected for the beneficiary's payment route.

extras object

Additional payment details for the beneficiary.

paymentMethod string

Payment method used to send funds to the beneficiary. Allowed values: LOCAL or SWIFT.

🧩 Examples

Request Example

cURL
Python
Java
NodeJs

curl --location --request POST \
--url '{{baseUrl}}/hashdt/banking/api/v1/beneficiaries' \
--header 'x-api-key: {{Shared X-API key}}' \
--header 'x-product-id: {{Shared ProductID}}' \
--header 'x-request-id: {{IdempotencyKey}}' \
--header 'x-user-id: {{UserID}}' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{AccessToken}}' \
--data-raw '{
  "companyCode": "{{Shared Company Code}}",
  "entityType": "INDIVIDUAL",
  "displayName": "Jane Doe",
  "firstName": "Jane",
  "lastName": "Doe",
  "email": "jane.doe@example.com",
  "currency": "USD",
  "country": "US",
  "address": {
    "country": "US",
    "nationality": "US",
    "city": "New York",
    "streetAddress": "123 Madison Avenue",
    "postalCode": "10016",
    "state": "New York"
  },
  "bank": {
    "bankName": "Example Bank",
    "bankAddress": "100 Example Street, New York, NY",
    "bankCountry": "US",
    "accountHolder": "Jane Doe",
    "accountCurrency": "USD",
    "accountNumber": "1234567890",
    "swiftCode": "EXMPUS33",
    "extras": {
      "clearingSystem": "SWIFT"
    }
  },
  "extras": {
    "paymentMethod": "SWIFT"
  }
}'

import requests
import json

url = "{{baseUrl}}/hashdt/banking/api/v1/beneficiaries"

payload = json.dumps({
  "companyCode": "{{Shared Company Code}}",
  "entityType": "INDIVIDUAL",
  "displayName": "Jane Doe",
  "firstName": "Jane",
  "lastName": "Doe",
  "email": "jane.doe@example.com",
  "currency": "USD",
  "country": "US",
  "address": {
    "country": "US",
    "nationality": "US",
    "city": "New York",
    "streetAddress": "123 Madison Avenue",
    "postalCode": "10016",
    "state": "New York"
  },
  "bank": {
    "bankName": "Example Bank",
    "bankAddress": "100 Example Street, New York, NY",
    "bankCountry": "US",
    "accountHolder": "Jane Doe",
    "accountCurrency": "USD",
    "accountNumber": "1234567890",
    "swiftCode": "EXMPUS33",
    "extras": {
      "clearingSystem": "SWIFT"
    }
  },
  "extras": {
    "paymentMethod": "SWIFT"
  }
})
headers = {
  'x-api-key': '{{Shared X-API key}}',
  'x-product-id': '{{Shared ProductID}}',
  'x-request-id': '{{IdempotencyKey}}',
  'x-user-id': '{{UserID}}',
  'Content-Type': 'application/json',
  'Authorization': 'Bearer {{AccessToken}}'
}

response = requests.request("POST", url, headers=headers, data=payload)

print(response.text)

OkHttpClient client = new OkHttpClient().newBuilder()
  .build();
MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create(mediaType, "{\r\n  \"companyCode\": \"{{Shared Company Code}}\",\r\n  \"entityType\": \"INDIVIDUAL\",\r\n  \"displayName\": \"Jane Doe\",\r\n  \"firstName\": \"Jane\",\r\n  \"lastName\": \"Doe\",\r\n  \"email\": \"jane.doe@example.com\",\r\n  \"currency\": \"USD\",\r\n  \"country\": \"US\",\r\n  \"address\": {\r\n    \"country\": \"US\",\r\n    \"nationality\": \"US\",\r\n    \"city\": \"New York\",\r\n    \"streetAddress\": \"123 Madison Avenue\",\r\n    \"postalCode\": \"10016\",\r\n    \"state\": \"New York\"\r\n  },\r\n  \"bank\": {\r\n    \"bankName\": \"Example Bank\",\r\n    \"bankAddress\": \"100 Example Street, New York, NY\",\r\n    \"bankCountry\": \"US\",\r\n    \"accountHolder\": \"Jane Doe\",\r\n    \"accountCurrency\": \"USD\",\r\n    \"accountNumber\": \"1234567890\",\r\n    \"swiftCode\": \"EXMPUS33\",\r\n    \"extras\": {\r\n      \"clearingSystem\": \"SWIFT\"\r\n    }\r\n  },\r\n  \"extras\": {\r\n    \"paymentMethod\": \"SWIFT\"\r\n  }\r\n}");
Request request = new Request.Builder()
  .url("{{baseUrl}}/hashdt/banking/api/v1/beneficiaries")
  .method("POST", body)
  .addHeader("x-api-key", "{{Shared X-API key}}")
  .addHeader("x-product-id", "{{Shared ProductID}}")
  .addHeader("x-request-id", "{{IdempotencyKey}}")
  .addHeader("x-user-id", "{{UserID}}")
  .addHeader("Content-Type", "application/json")
  .addHeader("Authorization", "Bearer {{AccessToken}}")
  .build();
Response response = client.newCall(request).execute();

const axios = require('axios');
let data = JSON.stringify({
  "companyCode": "{{Shared Company Code}}",
  "entityType": "INDIVIDUAL",
  "displayName": "Jane Doe",
  "firstName": "Jane",
  "lastName": "Doe",
  "email": "jane.doe@example.com",
  "currency": "USD",
  "country": "US",
  "address": {
    "country": "US",
    "nationality": "US",
    "city": "New York",
    "streetAddress": "123 Madison Avenue",
    "postalCode": "10016",
    "state": "New York"
  },
  "bank": {
    "bankName": "Example Bank",
    "bankAddress": "100 Example Street, New York, NY",
    "bankCountry": "US",
    "accountHolder": "Jane Doe",
    "accountCurrency": "USD",
    "accountNumber": "1234567890",
    "swiftCode": "EXMPUS33",
    "extras": {
      "clearingSystem": "SWIFT"
    }
  },
  "extras": {
    "paymentMethod": "SWIFT"
  }
});

let config = {
  method: 'post',
  maxBodyLength: Infinity,
  url: '{{baseUrl}}/hashdt/banking/api/v1/beneficiaries',
  headers: { 
    'x-api-key': '{{Shared X-API key}}', 
    'x-product-id': '{{Shared ProductID}}', 
    'x-request-id': '{{IdempotencyKey}}', 
    'x-user-id': '{{UserID}}', 
    'Content-Type': 'application/json', 
    'Authorization': 'Bearer {{AccessToken}}'
  },
  data : data
};

axios.request(config)
.then((response) => {
  console.log(JSON.stringify(response.data));
})
.catch((error) => {
  console.log(error);
});

Response Example

{
  "code": 201,
  "status": "SUCCESS",
  "message": "Created",
  "data": {
    "beneficiaryId": "60f0aba6-9067-4ba7-8038-a2d7d6a66918",
    "externalReference": "c11a25e9-5192-40c6-8e07-764b5f40095b",
    "status": "ACTIVE"
  }
}

{
  "code": 400,
  "status": "error",
  "message": "Error Message"
}

All Beneficiaries

Retrieves the user's registered beneficiaries, ordered from newest to oldest.

{{baseUrl}}/hashdt/banking/api/v1/beneficiaries

Description

This API is used to retrieve the user's beneficiary directory with pagination support. The response includes the beneficiary records in items, along with pagination details such as page, size, and total, where total represents the complete number of registered beneficiaries.

📩 Request Headers

x-api-key string required

Shared X-API key

x-product-id string required

Shared Product ID

x-request-id string required

Idempotency key for request tracking

x-user-id string required

User identification key

Content-Type string required

Must be application/json

Authorization string required

Bearer access token

🔍 Query Parameters

currency string

Currency of the beneficiary account using the 3-letter ISO 4217 currency code.

paymentMethod string

Payment method or transfer rail used to send funds to the beneficiary. Allowed values: LOCAL or SWIFT.

page integer

Page number for pagination. Defaults to 0.

size integer

Number of items per page. Defaults to 50.

🧩 Examples

Request Example

cURL
Python
Java
NodeJs

curl --location --request GET \
--url '{{baseUrl}}/hashdt/banking/api/v1/beneficiaries' \
--header 'x-api-key: {{Shared X-API key}}' \
--header 'x-product-id: {{Shared ProductID}}' \
--header 'x-request-id: {{IdempotencyKey}}' \
--header 'x-user-id: {{UserID}}' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{AccessToken}}'

import requests
import json

url = "{{baseUrl}}/hashdt/banking/api/v1/beneficiaries"

payload = {}
headers = {
  'x-api-key': '{{Shared X-API key}}',
  'x-product-id': '{{Shared ProductID}}',
  'x-request-id': '{{IdempotencyKey}}',
  'x-user-id': '{{UserID}}',
  'Content-Type': 'application/json',
  'Authorization': 'Bearer {{AccessToken}}'
}

response = requests.request("GET", url, headers=headers, data=payload)

print(response.text)

OkHttpClient client = new OkHttpClient().newBuilder()
  .build();
MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create(mediaType, "");
Request request = new Request.Builder()
  .url("{{baseUrl}}/hashdt/banking/api/v1/beneficiaries")
  .method("GET", body)
  .addHeader("x-api-key", "{{Shared X-API key}}")
  .addHeader("x-product-id", "{{Shared ProductID}}")
  .addHeader("x-request-id", "{{IdempotencyKey}}")
  .addHeader("x-user-id", "{{UserID}}")
  .addHeader("Content-Type", "application/json")
  .addHeader("Authorization", "Bearer {{AccessToken}}")
  .build();
Response response = client.newCall(request).execute();

const axios = require('axios');

let config = {
  method: 'get',
  maxBodyLength: Infinity,
  url: '{{baseUrl}}/hashdt/banking/api/v1/beneficiaries',
  headers: { 
    'x-api-key': '{{Shared X-API key}}', 
    'x-product-id': '{{Shared ProductID}}', 
    'x-request-id': '{{IdempotencyKey}}', 
    'x-user-id': '{{UserID}}', 
    'Content-Type': 'application/json', 
    'Authorization': 'Bearer {{AccessToken}}'
  }
};

axios.request(config)
.then((response) => {
  console.log(JSON.stringify(response.data));
})
.catch((error) => {
  console.log(error);
});

Response Example

{
  "code": 200,
  "status": "SUCCESS",
  "message": "Success",
  "data": {
    "items": [
      {
        "beneficiaryId": "60f0aba6-9067-4ba7-8038-a2d7d6a66918",
        "externalReference": "c11a25e9-5192-40c6-8e07-764b5f40095b",
        "entityType": "INDIVIDUAL",
        "name": "Jane Doe",
        "currency": "USD",
        "country": "US",
        "paymentMethod": "SWIFT",
        "capabilityId": "beneficiary.create.usd",
        "status": "ACTIVE",
        "createdAt": "2026-08-25T07:13:39Z",
        "updatedAt": "2026-08-25T07:13:39Z"
      },
      {
        "beneficiaryId": "34e8d797-18f8-40ef-b1fd-5b76922ec6e7",
        "externalReference": "13bc0380-bf4d-47aa-8f80-6aac88a72346",
        "entityType": "COMPANY",
        "name": "Lion City Supplies",
        "currency": "SGD",
        "country": "SG",
        "paymentMethod": "LOCAL",
        "capabilityId": "beneficiary.create.sgd",
        "status": "ACTIVE",
        "createdAt": "2026-08-10T08:55:17Z",
        "updatedAt": "2026-08-10T08:55:17Z"
      }
    ],
    "page": 0,
    "size": 50,
    "total": 2
  }
}

{
  "code": 400,
  "status": "error",
  "message": "Error Message"
}

Beneficiary Details

Retrieves the details of a specific registered beneficiary.

{{baseUrl}}/hashdt/banking/api/v1/beneficiaries/:beneficiaryID

Description

This API is used to retrieve the complete details of a registered beneficiary using its beneficiaryID. The response provides the beneficiary's identification, account, banking, and payment information associated with the beneficiary.

🔗 Path Parameters

beneficiaryID string required

Unique identifier for beneficiary.

📩 Request Headers

x-api-key string required

Shared X-API key

x-product-id string required

Shared Product ID

x-request-id string required

Idempotency key for request tracking

x-user-id string required

User identification key

Content-Type string required

Must be application/json

Authorization string required

Bearer access token

🧩 Examples

Request Example

cURL
Python
Java
NodeJs

curl --location --request GET \
--url '{{baseUrl}}/hashdt/banking/api/v1/beneficiaries/:beneficiaryID' \
--header 'x-api-key: {{Shared X-API key}}' \
--header 'x-product-id: {{Shared ProductID}}' \
--header 'x-request-id: {{IdempotencyKey}}' \
--header 'x-user-id: {{UserID}}' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{AccessToken}}'

import requests
import json

url = "{{baseUrl}}/hashdt/banking/api/v1/beneficiaries/:beneficiaryID"

payload = {}
headers = {
  'x-api-key': '{{Shared X-API key}}',
  'x-product-id': '{{Shared ProductID}}',
  'x-request-id': '{{IdempotencyKey}}',
  'x-user-id': '{{UserID}}',
  'Content-Type': 'application/json',
  'Authorization': 'Bearer {{AccessToken}}'
}

response = requests.request("GET", url, headers=headers, data=payload)

print(response.text)

OkHttpClient client = new OkHttpClient().newBuilder()
  .build();
MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create(mediaType, "");
Request request = new Request.Builder()
  .url("{{baseUrl}}/hashdt/banking/api/v1/beneficiaries/:beneficiaryID")
  .method("GET", body)
  .addHeader("x-api-key", "{{Shared X-API key}}")
  .addHeader("x-product-id", "{{Shared ProductID}}")
  .addHeader("x-request-id", "{{IdempotencyKey}}")
  .addHeader("x-user-id", "{{UserID}}")
  .addHeader("Content-Type", "application/json")
  .addHeader("Authorization", "Bearer {{AccessToken}}")
  .build();
Response response = client.newCall(request).execute();

const axios = require('axios');

let config = {
  method: 'get',
  maxBodyLength: Infinity,
  url: '{{baseUrl}}/hashdt/banking/api/v1/beneficiaries/:beneficiaryID',
  headers: { 
    'x-api-key': '{{Shared X-API key}}', 
    'x-product-id': '{{Shared ProductID}}', 
    'x-request-id': '{{IdempotencyKey}}', 
    'x-user-id': '{{UserID}}', 
    'Content-Type': 'application/json', 
    'Authorization': 'Bearer {{AccessToken}}'
  }
};

axios.request(config)
.then((response) => {
  console.log(JSON.stringify(response.data));
})
.catch((error) => {
  console.log(error);
});

Response Example

{
  "code": 200,
  "status": "SUCCESS",
  "message": "Success",
  "data": {
    "beneficiaryId": "60f0aba6-9067-4ba7-8038-a2d7d6a66918",
    "externalReference": "c11a25e9-5192-40c6-8e07-764b5f40095b",
    "entityType": "INDIVIDUAL",
    "name": "Jane Doe",
    "firstName": "Jane",
    "lastName": "Doe",
    "companyName": null,
    "email": "jane.doe@example.com",
    "currency": "USD",
    "country": "US",
    "paymentMethod": "SWIFT",
    "capabilityId": "beneficiary.create.usd",
    "status": "ACTIVE",
    "address": {
      "country": "US",
      "city": "New York",
      "streetAddress": "123 Madison Avenue",
      "postalCode": "10016",
      "state": "New York",
      "nationality": "US"
    },
    "bank": {
      "bankName": "Example Bank",
      "bankAddress": "100 Example Street, New York, NY",
      "bankCountry": "US",
      "accountHolder": "Jane Doe",
      "accountCurrency": "USD",
      "accountNumberMasked": "****7890",
      "ibanMasked": null,
      "swiftCode": "EXMPUS33",
      "routingCodeType": null,
      "routingCodeValue": null,
      "routingCodeType2": null,
      "routingCodeValue2": null,
      "extras": {
        "clearingSystem": "SWIFT"
      }
    },
    "createdAt": "2026-08-25T07:13:39Z",
    "updatedAt": "2026-08-25T07:13:39Z"
  }
}

{
  "code": 400,
  "status": "error",
  "message": "Error Message"
}

Supported Corridors​

Description

📩 Request Headers

🔍 Query Parameters

Request Example

Response Example

Beneficiary Schema​

Description

📩 Request Headers

🔍 Query Parameters

Request Example

Response Example

Create Beneficiary​

Description

📩 Request Headers

📦 Request Body

Request Example

Response Example

All Beneficiaries​

Description

📩 Request Headers

🔍 Query Parameters

Request Example

Response Example

Beneficiary Details​

Description

🔗 Path Parameters

📩 Request Headers

Request Example

Response Example

Supported Corridors

Beneficiary Schema

Create Beneficiary

All Beneficiaries

Beneficiary Details