---
title: "Validate Beneficiary"
source_url: https://docs.rapyd.net/en/validate-beneficiary.html
lang: en
---

# Validate Beneficiary

Validate the format of the details for a payout beneficiary.

You can validate a beneficiary multiple times for different payout methods.

You can enter a `beneficiary` object or a previously created beneficiary ID.

> **Note:**
>
> - In addition to the required fields for [Create Beneficiary](https://docs.rapyd.net/en/create-beneficiary.md "Create Beneficiary"), the `beneficiary` object must include all required fields for the beneficiary listed in the response to [Get Payout Required Fields](https://docs.rapyd.net/en/get-payout-required-fields.md "Get Payout Required Fields").
> - The code samples include successful requests (200) and bad requests (400).
>
>   - For error messages that appear due to bad requests (400), see:
>
>     - [General Errors](https://docs.rapyd.net/en/general-errors.md "General Errors")
>     - [Payout Errors](https://docs.rapyd.net/en/payout-errors.md "Payout Errors")
>   - For information about unauthorized request (401) and other authentication errors, see [Troubleshooting Authentication and Authorization Errors](https://docs.rapyd.net/en/troubleshooting-authentication-and-authorization-errors.md "Troubleshooting Authentication and Authorization Errors").

### Parameters

### Request Header Parameters

- - access_key
  - Unique access key provided by Rapyd for each authorized user.

    See [Developers](https://docs.rapyd.net/en/developers.md "Developers").
- - Content-Type
  - Indicates that the data appears in JSON format. Set to **application/json**.
- - idempotency
  - A unique key that prevents the platform from creating the same object twice.

    See [Idempotency](https://docs.rapyd.net/en/idempotency.md "Idempotency").
- - salt
  - Random string. Recommended length: 8-16 characters.
- - signature
  - Signature calculated for each request individually.

    See [Request Signatures](https://docs.rapyd.net/en/request-signatures.md "Request Signatures").
- - timestamp
  - Timestamp for the request, in [Unix time](https://docs.rapyd.net/en/glossary.md#UUID-945d98cf-adae-e1cf-2606-c7fae8b4a7e1_unix_time "Unix time") (seconds).

### Request Body Parameters

- - beneficiary
  - One of the following:

    - String starting with **beneficiary_**. The response to [Create Beneficiary](https://docs.rapyd.net/en/create-beneficiary.md "Create Beneficiary") provides the ID of the `beneficiary` object.
    - Object describing the beneficiary. Must include all fields in the [Beneficiary Object](https://docs.rapyd.net/en/beneficiary.md "Beneficiary"), and all fields in the response to [Get Payout Required Fields](https://docs.rapyd.net/en/get-payout-required-fields.md "Get Payout Required Fields").
- - payout_method_type
  - The type of payout method. The two-letter prefix must match the country code of the beneficiary.
- - amount
  - Maximum amount that the sender is paying, in units of the currency defined in `sender_currency`. Decimal.

    Required when `payout_amount` is not used.
- - sender_country
  - Country of the sender. Two-letter ISO 3166-1 ALPHA-2 code.
- - sender_currency
  - Currency that the sender is paying with. Three-letter ISO 4217 code.
- - sender_entity_type
  - Filters the type of entity for the sender. One of the following: Relevant to [List Payout Method Types](https://docs.rapyd.net/en/list-payout-method-types.md "List Payout Method Types").

    - **company**
    - **individual**

### Response Parameters

- - amount
  - Maximum payout amount to validate, in units of the currency defined in `sender_currency`.
- - beneficiary
  - ID of the `beneficiary` object. String starting with **beneficiary_**.
- - bin_details
  - Bank identification details. Relevant to cards..

    - - bin_number
      - [Bank identification number](https://docs.rapyd.net/en/glossary.md#UUID-945d98cf-adae-e1cf-2606-c7fae8b4a7e1_bin "Bank Identification Number") of the issuing bank.
    - - brand
      - The brand of the card.
    - - country
      - The country where the card was issued.
    - - issuer
      - Name of the bank that issued the card.
    - - level
      - The level of the card.
    - - type
      - The type of card.
- - category
  - The category of payout method type. One of the following:

    - **bank**
    - **card**
    - **cash**
    - **ewallet** - local eWallet (non-Rapyd)
    - **rapyd_ewallet** - Rapyd wallet. Must match the category of the payout method.
- - company_name
  - Name of the beneficiary company. Relevant when `entity_type` is **company**.
- - confirmation_required
  - Indicates whether the beneficiary must respond to accept or decline a payout. Relevant to the **rapyd_ewallet** payout method type.
- - country
  - Country of the beneficiary.
- - currency
  - Currency received by the beneficiary.
- - default_payout_method_type
  - The type of payout method for the beneficiary.
- - entity_type
  - Type of entity. One of the following values:

    - **company**
    - **individual**
- - ewallet
  - ID of the wallet that the money is transferred to. Relevant to payout to Rapyd Wallet.
- - first_name
  - First name of the beneficiary. Relevant when `entity_type` is **individual**.
- - id
  - ID of the 'beneficiary' object. String starting with **beneficiary_**.
- - identification_type
  - Type of identification document for the beneficiary. When `entity_type` is **company**, this field must be **company_registered_number**. When `entity_type` is **individual**, one of the following values:

    - **drivers_license**
    - **identification_id**
    - **international_passport**
    - **residence_permit**
    - **social_security**
    - **work_permit**
- - identification_value
  - Identification number on the document mentioned in `identification_type`.
- - last_name
  - Last name of the beneficiary. Relevant when `entity_type` is **individual**.
- - merchant_reference_id
  - Identifier defined by the client for reference purposes. Limit: 45 characters.
- - validated
  - Indicates whether the format of payout beneficiary details is valid for the payout method type.

- - .NET

    - ```csharp
      using System;
      using System.Text.Json;

      namespace RapydApiRequestSample
      {
          class Program
          {
              static void Main(string[] args)
              {
                  try
                  {
                      var requestObj = new
                      {
                          beneficiary = "beneficiary_d895d90d276869efe1e359386a1fb3e3",
                          payout_method_type = "us_ach_bank",
                          sender_country = "US",
                          sender_currency = "USD",
                          sender_entity_type = "company",
                          amount = 100
                      };

                      string request = JsonSerializer.Serialize(requestObj);

                      string result = RapydApiRequestSample.Utilities.MakeRequest("POST", "/v1/payouts/beneficiary/validate", request);

                      Console.WriteLine(result);
                  }
                  catch (Exception e)
                  {
                      Console.WriteLine("Error completing request: " + e.Message);
                  }
              }
          }
      }
      ```
- - JavaScript

    - ```javascript
      const makeRequest = require('<path-to-your-utility-file>/utilities').makeRequest;

      async function main() {
        try {
          const body = {
            beneficiary: 'beneficiary_d895d90d276869efe1e359386a1fb3e3',
            payout_method_type: 'us_ach_bank',
            sender_country: 'US',
            sender_currency: 'USD',
            sender_entity_type: 'company',
            amount: 100
          };
          const result = await makeRequest('POST', '/v1/payouts/beneficiary/validate', body);

          console.log(result);
        } catch (error) {
          console.error('Error completing request', error);
        }
      }
      ```
- - PHP

    - ```php
      <?php
      $path = $_SERVER['DOCUMENT_ROOT'];
      $path .= "/<path-to-your-utility-file>/utilities.php";
      include($path);
      $beneficiary = [
        "beneficiary" => "beneficiary_d895d90d276869efe1e359386a1fb3e3",
              "payout_method_type" => "us_ach_bank",
              "sender_country" => "US",
              "sender_currency" => "USD",
              "sender_entity_type" => "company",
              "amount" => 100
      ];

      try {
          $object = make_request('post', '/v1/payouts/beneficiary/validate', $beneficiary);
          var_dump($object);
      } catch(Exception $e) {
          echo "Error: $e";
      }
      ?>
      ```
- - Python

    - ```python
      from pprint import pprint

      from utilities import make_request

      # Validate Beneficiary
      beneficiary_id = 'beneficiary_d895d90d276869efe1e359386a1fb3e3' 
      beneficiary_info = {
          "beneficiary": beneficiary_id,
          "payout_method_type": "us_ach_bank",
          "sender_country": "US",
          "sender_currency": "USD",
          "sender_entity_type": "company",
          "amount": 100
      }

      results = make_request(method='post',
                             path='/v1/payouts/beneficiary/validate',
                             body=beneficiary_info)
      pprint(results)
      ```

- /v1/payouts/beneficiary/validate/

- Validate Beneficiary - ID
- ```curl
  curl -X post 'https://sandboxapi.rapyd.net/v1/payouts/beneficiary/validate' \
  -H 'access_key: your-access-key-here' \
  -H 'Content-Type: application/json' \
  -H 'idempotency: your-idempotency-parameter-here' \
  -H 'salt: your-random-string-here' \
  -H 'signature: your-calculated-signature-here' \
  -H 'timestamp: your-unix-timestamp-here' \
  --data-raw '{
      "beneficiary": "beneficiary_aa1289193cd5a04fb6de8612a9e00835",
      "amount": 100,
      "payout_method_type": "at_general_bank",
      "sender_country": "AT",
      "sender_currency": "EUR",
      "sender_entity_type": "company"
  }'
  ```
- ```json
  {
      "status": {
          "error_code": "",
          "status": "SUCCESS",
          "message": "",
          "response_code": "",
          "operation_id": "243fe1a3-7575-4cf8-9d77-a97148c931b4"
      },
      "data": {
          "validated": true,
          "beneficiary": {
              "id": "beneficiary_aa1289193cd5a04fb6de8612a9e00835",
              "last_name": "Doe",
              "first_name": "John",
              "country": "AT",
              "entity_type": "individual",
              "name": "John Doe",
              "currency": "EUR",
              "bin_details": {
                  "type": "DEBIT",
                  "brand": "VISA",
                  "level": "CLASSIC",
                  "issuer": "CONOTOXIA SP. Z O.O",
                  "country": "PL",
                  "bin_number": "411111"
              },
              "iban": "AT611904300234573201",
              "card_number": "1111",
              "payment_type": "regular",
              "category": "card",
              "default_payout_method_type": "at_general_bank"
          }
      }
  }
  ```

- Validate Beneficiary - Object
- ```curl
  curl -X post 'https://sandboxapi.rapyd.net/v1/payouts/beneficiary/validate' \
  -H 'access_key: your-access-key-here' \
  -H 'Content-Type: application/json' \
  -H 'idempotency: your-idempotency-parameter-here' \
  -H 'salt: your-random-string-here' \
  -H 'signature: your-calculated-signature-here' \
  -H 'timestamp: your-unix-timestamp-here' \
  --data-raw '{
      "payout_method_type": "au_general_bank",
      "sender_country": "AU",
      "sender_currency": "AUD",
      "sender_entity_type": "company",
      "amount": 100,
      "beneficiary": {
          "payment_type": "regular",
          "address": "456 Main Street",
          "city": "Melbourne",
          "first_name": "Jane",
          "last_name": "Doe",
          "postcode": "3000",
          "account_number": "123456789",
          "bsb_code": "154126",
          "identification_type": "work permit",
          "identification_value": "658412",
          "country": "AU",
          "entity_type": "individual",
          "currency": "AUD"
      }
  }'
  ```
- ```json
  {
      "status": {
          "error_code": "",
          "status": "SUCCESS",
          "message": "",
          "response_code": "",
          "operation_id": "99b48648-c2ce-4a06-9a9d-ca911ce034b2"
      },
      "data": {
          "validated": true,
          "beneficiary": {
              "last_name": "Doe",
              "first_name": "Jane",
              "country": "AU",
              "entity_type": "individual",
              "address": "456 Main Street",
              "name": "Jane Doe",
              "postcode": "3000",
              "city": "Melbourne",
              "account_number": "123456789",
              "currency": "AUD",
              "identification_type": "work permit",
              "identification_value": "******",
              "bsb_code": "154126",
              "payment_type": "regular"
          }
      }
  }
  ```

- Validate Beneficiary with IBAN
- ```curl
  curl -X post 'https://sandboxapi.rapyd.net/v1/payouts/beneficiary/validate' \
  -H 'access_key: your-access-key-here' \
  -H 'Content-Type: application/json' \
  -H 'idempotency: your-idempotency-parameter-here' \
  -H 'salt: your-random-string-here' \
  -H 'signature: your-calculated-signature-here' \
  -H 'timestamp: your-unix-timestamp-here' \
  --data-raw '{
      "beneficiary": {
          "category": "bank",
          "country": "AT",
          "currency": "EUR",
          "entity_type": "individual",
          "first_name": "John",
          "last_name": "Doe",
          "iban": "DE75512108001245126199"
      },
      "amount": 100,
      "payout_currency": "EUR",
      "payout_method_type": "at_general_bank",
      "sender_country": "AT",
      "sender_currency": "EUR",
      "sender_entity_type": "company"
  }'
  ```
- ```json
  {
      "status": {
          "error_code": "",
          "status": "SUCCESS",
          "message": "",
          "response_code": "",
          "operation_id": "044248e3-ede2-41ea-9b5f-1fa62bc4a473"
      },
      "data": {
          "validated": true,
          "beneficiary": {
              "last_name": "Doe",
              "first_name": "John",
              "country": "AT",
              "entity_type": "individual",
              "name": "John Doe",
              "currency": "EUR",
              "bank_name": "Societe Generale",
              "iban": "DE75512108001245126199",
              "category": "bank"
          }
      }
  }
  ```

- Validate Beneficiary with BIC/SWIFT
- ```curl
  curl -X post 'https://sandboxapi.rapyd.net/v1/payouts/beneficiary/validate' \
  -H 'access_key: your-access-key-here' \
  -H 'Content-Type: application/json' \
  -H 'idempotency: your-idempotency-parameter-here' \
  -H 'salt: your-random-string-here' \
  -H 'signature: your-calculated-signature-here' \
  -H 'timestamp: your-unix-timestamp-here' \
  --data-raw '{
      "payout_method_type": "au_general_bank",
      "sender_country": "AU",
      "sender_currency": "AUD",
      "sender_entity_type": "company",
      "amount": 100,
      "beneficiary": {
          "payment_type": "regular",
          "address": "456 Main Street",
          "city": "Melbourne",
          "first_name": "Jane",
          "last_name": "Doe",
          "postcode": "3000",
          "account_number": "123456789",
          "bsb_code": "154126",
          "identification_type": "work permit",
          "identification_value": "658412",
          "country": "AU",
          "entity_type": "individual",
          "currency": "AUD",
          "bic_swift": "BARCGB22"
      }
  }'
  ```
- ```json
  {
      "status": {
          "error_code": "",
          "status": "SUCCESS",
          "message": "",
          "response_code": "",
          "operation_id": "336f8677-84cf-4f23-a8b9-3b91eaa324e6"
      },
      "data": {
          "validated": true,
          "beneficiary": {
              "last_name": "Doe",
              "first_name": "Jane",
              "country": "AU",
              "entity_type": "individual",
              "address": "456 Main Street",
              "name": "Jane Doe",
              "postcode": "3000",
              "city": "Melbourne",
              "account_number": "123456789",
              "currency": "AUD",
              "identification_type": "work permit",
              "identification_value": "******",
              "bank_name": "Barclays Bank PLC",
              "bic_swift": "BARCGB22",
              "bsb_code": "154126",
              "payment_type": "regular"
          }
      }
  }
  ```

- Bad Request - Missing Input Fields
- ```curl
  curl -X post 'https://sandboxapi.rapyd.net/v1/payouts/beneficiary/validate' \
  -H 'access_key: your-access-key-here' \
  -H 'Content-Type: application/json' \
  -H 'idempotency: your-idempotency-parameter-here' \
  -H 'salt: your-random-string-here' \
  -H 'signature: your-calculated-signature-here' \
  -H 'timestamp: your-unix-timestamp-here' \
  --data-raw '{
      "beneficiary": {
          "payment_type": "regular",
          "iban": "DE75512108001245126199",
          "first_name": "John",
          "last_name": "Doe",
          "category": "bank",
          "country": "US",
          "currency": "USD",
          "entity_type": "individual",        
          "bic_swift": "BARCGB22"
      },
      "amount": 100,
      "payout_method_type": "at_general_bank",
      "sender_country": "AT",
      "sender_currency": "EUR",
      "sender_entity_type": "company"
  }'
  ```
- ```json
  {
      "status": {
          "error_code": "ERROR_VALIDATE_PAYOUT_BENEFICIARY",
          "status": "ERROR",
          "message": "The request tried to validate a beneficiary, but there was an error in the input fields. The request was rejected. Corrective action: Run 'Get Payout Required Fields'.",
          "response_code": "ERROR_VALIDATE_PAYOUT_BENEFICIARY",
          "operation_id": "17c74e08-b174-4e3a-87a5-aaab5c374c8f"
      }
  }
  ```

- Bad Request - Beneficiary Not Found
- ```curl
  curl -X post 'https://sandboxapi.rapyd.net/v1/payouts/beneficiary/validate' \
  -H 'access_key: your-access-key-here' \
  -H 'Content-Type: application/json' \
  -H 'idempotency: your-idempotency-parameter-here' \
  -H 'salt: your-random-string-here' \
  -H 'signature: your-calculated-signature-here' \
  -H 'timestamp: your-unix-timestamp-here' \
  --data-raw '{
      "beneficiary": "beneficiaryaa1289193cd5a04fb6de8612a9e00835",
      "amount": 100,
      "payout_method_type": "at_general_bank",
      "sender_country": "AT",
      "sender_currency": "EUR",
      "sender_entity_type": "company"
  }'
  ```
- ```json
  {
      "status": {
          "error_code": "ERROR_GET_BENEFICIARY",
          "status": "ERROR",
          "message": "The request attempted an operation that requires a payout beneficiary, but the beneficiary was not found. The request was rejected. Corrective action: Use the ID of a valid beneficiary.",
          "response_code": "ERROR_GET_BENEFICIARY",
          "operation_id": "d64efcd9-3a97-49be-8f4d-5e9421e99550"
      }
  }
  ```

### Related Information

- [IBAN Numbers for Testing](https://docs.rapyd.net/en/iban-numbers-for-testing.md "IBAN Numbers for Testing")
- [BIC/SWIFT Numbers for Testing](https://docs.rapyd.net/en/bic-swift-numbers-for-testing.md "BIC/SWIFT Numbers for Testing")