Create Beneficiary

This lets you create a beneficiary

POST /v3/beneficiary

Create Beneficiary

cURL

curl --request POST \
  --url https://service-sandbox.tazapay.com/v3/beneficiary \
  --header 'Authorization: Basic <encoded-value>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "account_id": "acc_cr83unf7j0t2odh9ioc0",
  "name": "test",
  "type": "individual",
  "email": "[e-mail]",
  "tax_id": "",
  "destination_details": {
    "type": "bank",
    "bank": {
      "country": "IN",
      "currency": "INR",
      "bank_codes": {
        "swift_code": "Test",
        "ifsc_code": "Test"
      },
      "bank_name": "hdfc",
      "account_number": "Test",
      "firc_required": true,
      "purpose_code": "Test"
    }
  },
  "address": {
    "line1": "Test",
    "line2": "Test",
    "city": "Test",
    "state": "Test",
    "country": "IN",
    "postal_code": "110017"
  },
  "phone": {
    "number": "",
    "calling_code": "91"
  },
  "nationality": "IN"
}
'

200

{
  "status": "success",
  "message": "",
  "data": {
    "address": {
      "city": "Test",
      "country": "IN",
      "line1": "Test",
      "line2": "Test",
      "postal_code": "110017",
      "state": "Test"
    },
    "created_at": "2024-10-03T11:03:40.326462Z",
    "destination": "bnk_crv7k337eoqgk10pqp40",
    "destination_details": {
      "bank": {
        "account_number": "Test",
        "account_type": "",
        "bank_codes": {
          "ifsc_code": "Test",
          "swift_code": "Test"
        },
        "bank_name": "hdfc",
        "branch_name": "",
        "country": "IN",
        "currency": "INR",
        "firc_required": true,
        "purpose_code": "Test"
      },
      "type": "bank"
    },
    "documents": [],
    "email": "[e-mail]",
    "id": "bnf_crv7k31h1l071n2fkbjg",
    "metadata": null,
    "name": "test",
    "object": "beneficiary",
    "phone": {
      "calling_code": "91",
      "number": "9362987920"
    },
    "tax_id": "",
    "type": "individual"
  }
}

Authorizations

Authorization · string · header · required

Basic authentication header of the form Basic <encoded-value>, where <encoded-value> is the base64-encoded string username:password.

Body

application/json

name · string · required

Beneficiary Name

type · enum<string> · required

business or individual

Available options: business, individual

email · string

Email Address

address · object

Address (Mandatory if destination_details.type is a wallet)

Show child attributes

phone · object

Phone

Show child attributes

destination_details · object

Destination Details

Show child attributes

destination · string

ID of the destination attached to the beneficiary

metadata · string<json>

Set of key-value pairs to attach to the beneficiary

tax_id · string

Tax ID of the beneficiary. (CPF or CPNJ is mandatory for payouts to Brazil)

documents · object

Documents to attach to the beneficiary

Show child attributes

national_identification_number · string

National ID of the individual

registration_number · string

Registration number of the business (Mandatory if destination_details.type is a wallet and type is business)

date_of_birth · string

Date of birth of individual, Format DD-MM-YYYY (Mandatory if destination_details.type is a wallet and type is individual)

nationality · string

ISO 3166-1 alpha-2 country code representing the beneficiary's nationality (e.g., US, GB, IN, FR). Optional field used for enhanced compliance screening.

party_classification · enum<string> · default: ""

Type of relationship between beneficiary and creator of beneficiary Possible values - self, third_party (Mandatory if destination_details.type is a wallet)

Available options: self, third_party

name_local · string

Name in local language

Response

200

application/json

200

Represents a payout beneficiary with personal, contact, and destination details.

address · object

Address details of the beneficiary.

Show child attributes

date_of_birth · string

Date of birth of the beneficiary in YYYY-MM-DD format.

Example:

"2003-04-04"

nationality · string

ISO 3166-1 alpha-2 country code representing the beneficiary's nationality.

Example:

"IN"

destination · string

Identifier or reference to the beneficiary's payment destination (bank account, wallet, etc.).

Example:

""

destination_details · object

Details about the payout destination, such as wallet or bank.

Show child attributes

documents · object[]

List of documents associated with the beneficiary (e.g., ID proof, address proof).

Example:

[]

email · string

Email address of the beneficiary.

Example:

"[e-mail]"

name · string

Full name of the beneficiary.

Example:

"Scott"

name_local · string

Local language representation of the beneficiary's name, if applicable.

Example:

""

national_identification_number · string

National identification number or equivalent ID.

Example:

""

party_classification · string

Classification of the beneficiary, such as 'self', 'third_party', etc.

Example:

"third_party"

phone · object

Contact phone information of the beneficiary.

Show child attributes

registration_number · string

Registration or incorporation number for business beneficiaries.

Example:

""

tax_id · string

Tax identification number for the beneficiary.

Example:

""

type · string

Specifies whether the beneficiary is an 'individual' or a 'business'.

Example:

"individual"