--- title: "Retrieve Beneficiary" source_url: https://docs.rapyd.net/en/retrieve-beneficiary.html lang: en --- # Retrieve Beneficiary Retrieve details of a payout beneficiary. > **Note:** > > - The response includes additional fields for the specific payout method. For details about the additional fields, run [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**. - - 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 Path Parameters - - beneficiary - ID of the `beneficiary` object. String starting with **beneficiary_**. ### Response Parameters - - address - Beneficiary's street address including the build number. For example: 123 East 32nd street. - - amount - Maximum payout amount to validate, in units of the currency defined in `sender_currency`. Decimal. - - 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. false - - country - Country of the beneficiary. Two-letter ISO 3166-1 ALPHA-2 code. The two-letter prefix of the payout method type must match the beneficiary country code. - - currency - Currency received by the beneficiary. Three-letter ISO 4217 code. > **Note:** > > Four-letter codes are supported for stablecoin (USDC). - - 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. String starting with **ewallet_**. 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. - - .NET - ```csharp using System; namespace RapydApiRequestSample { class Program { static void Main(string[] args) { try { string beneficiaryId = "beneficiary_8ba699483c80b7fb9f7e658be3275703"; string result = RapydApiRequestSample.Utilities.MakeRequest("GET", $"/v1/payouts/beneficiary/{beneficiaryId}"); Console.WriteLine(result); } catch (Exception e) { Console.WriteLine("Error completing request: " + e.Message); } } } } ``` - - JavaScript - ```javascript const makeRequest = require('/utilities').makeRequest; async function main() { try { const result = await makeRequest( 'GET', '/v1/payouts/beneficiary/beneficiary_8ba699483c80b7fb9f7e658be3275703' ); console.log(result); } catch (error) { console.error('Error completing request', error); } } ``` - - PHP - ```php /utilities.php"; include($path); try { $object = make_request('get', '/v1/payouts/beneficiary/beneficiary_8ba699483c80b7fb9f7e658be3275703'); var_dump($object); } catch(Exception $e) { echo "Error: $e"; } ?> ``` - - Python - ```python from pprint import pprint from utilities import make_request beneficiary_id = 'beneficiary_8ba699483c80b7fb9f7e658be3275703' results = make_request(method='get', path=f'/v1/payouts/beneficiary/{beneficiary_id}') pprint(results) ``` - /v1/payouts/beneficiary/:beneficiary - Retrieve Beneficiary - Individual - ```curl curl -X get 'https://sandboxapi.rapyd.net/v1/payouts/beneficiary/beneficiary_cb009f46c8dcd85004c8054541287723' \ -H 'access_key: your-access-key-here' \ -H 'Content-Type: application/json' \ -H 'salt: your-random-string-here' \ -H 'signature: your-calculated-signature-here' \ -H 'timestamp: your-unix-timestamp-here' ``` - ```json { "status": { "error_code": "", "status": "SUCCESS", "message": "", "response_code": "", "operation_id": "98ac2d04-ede3-46de-8f48-58d6c4899ba0" }, "data": { "id": "beneficiary_cb009f46c8dcd85004c8054541287723", "last_name": "Doe", "first_name": "John", "country": "US", "entity_type": "individual", "address": "1 Main Street", "name": "John Doe", "postcode": "12345", "city": "Anytown", "state": "Illinois", "account_number": "1234567", "currency": "USD", "identification_type": "identification_id", "identification_value": "*********", "merchant_reference_id": "JohnDoe", "gender": "other", "bic_swift": "12345678XXX", "payment_type": "priority", "category": "bank", "default_payout_method_type": "us_general_bank" } } ``` - Retrieve Beneficiary - Company - ```curl curl -X get 'https://sandboxapi.rapyd.net/v1/payouts/beneficiary/beneficiary_ec63141037199ae470c60f9ac8426056' \ -H 'access_key: your-access-key-here' \ -H 'Content-Type: application/json' \ -H 'salt: your-random-string-here' \ -H 'signature: your-calculated-signature-here' \ -H 'timestamp: your-unix-timestamp-here' ``` - ```json { "status": { "error_code": "", "status": "SUCCESS", "message": "", "response_code": "", "operation_id": "7acfd391-fdf8-4c53-88b6-117dcb64c03d" }, "data": { "id": "beneficiary_ec63141037199ae470c60f9ac8426056", "country": "US", "entity_type": "company", "name": "All Star Limousine", "company_name": "All Star Limousine", "account_number": "0987654321", "currency": "USD", "identification_type": "company_registered_number", "identification_value": "**********", "merchant_reference_id": "AllStarLimo", "aba": "987654321", "category": "bank" } } ``` - Bad Request - Beneficiary Not Found - ```curl curl -X get 'https://sandboxapi.rapyd.net/v1/payouts/beneficiary/beneficiarycb009f46c8dcd85004c8054541287723' \ -H 'access_key: your-access-key-here' \ -H 'Content-Type: application/json' \ -H 'salt: your-random-string-here' \ -H 'signature: your-calculated-signature-here' \ -H 'timestamp: your-unix-timestamp-here' ``` - ```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": "72b9234d-35c8-486c-92ca-12b6f61211cc" } } ```