--- title: "Create Beneficiary" source_url: https://docs.rapyd.net/en/create-beneficiary.html lang: en --- # Create Beneficiary Create a beneficiary for use in payouts. The response provides a unique beneficiary ID, which you can use in place of the `beneficiary` object for [Create Payout](https://docs.rapyd.net/en/create-payout.md "Create Payout") This method triggers the [Beneficiary Created Webhook](https://docs.rapyd.net/en/beneficiary-created-webhook.md "Beneficiary Created Webhook") webhook. This webhook contains the same information as the response. > **Note:** > > - In addition to the required fields documented below, you must include all other fields listed for the beneficiary in the response to [Get Payout Required Fields](https://docs.rapyd.net/en/get-payout-required-fields.md "Get Payout Required Fields"), and you must conform to the regex provided. > > To create a beneficiary that you can use with multiple payout methods, include all fields that are required by each payout method. The client is responsible for including all required fields. > - The code samples include successful requests (200) and bad requests (400). > > - 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 - - 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**. - - country - Country of the beneficiary. Two-letter ISO 3166-1 ALPHA-2 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. The two-letter prefix must match the beneficiary country code. The prefix xx_ matches all countries. - - entity_type - Type of entity for the beneficiary. One of the following values: - **company** - **individual** - - first_name - First name of the beneficiary. Relevant when `entity_type` is **individual**. - - 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. ### 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. - /v1/payouts/beneficiary - Create Beneficiary - Individual - ```curl curl -X post 'https://sandboxapi.rapyd.net/v1/payouts/beneficiary' \ -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 '{ "category": "bank", "country": "US", "currency": "USD", "entity_type": "individual", "first_name": "John", "last_name": "Doe", "identification_type": "identification_id", "identification_value": "123456789", "default_payout_method_type": "us_general_bank", "merchant_reference_id": "JohnDoe", "payment_type": "priority", "address": "1 Main Street", "city": "Any Town", "state": "New State", "postcode": "12345", "account_number": "1234567", "bic_swift": "12345678XXX" }' ``` - ```json { "status": { "error_code": "", "status": "SUCCESS", "message": "", "response_code": "", "operation_id": "6a147936-0401-4dea-9787-13fed5e4fd45" }, "data": { "id": "beneficiary_94956e29ed5959a51afc6717787c00af", "last_name": "Doe", "first_name": "John", "country": "US", "entity_type": "individual", "address": "1 Main Street", "name": "John Doe", "postcode": "12345", "city": "Any Town", "state": "New State", "account_number": "1234567", "currency": "USD", "identification_type": "identification_id", "identification_value": "*********", "merchant_reference_id": "JohnDoe", "bic_swift": "12345678XXX", "payment_type": "priority", "category": "bank", "default_payout_method_type": "us_general_bank" } } ``` - Create Beneficiary - Company - ```curl curl -X post 'https://sandboxapi.rapyd.net/v1/payouts/beneficiary' \ -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 '{ "category": "bank", "company_name": "All Star Limousine", "country": "US", "currency": "USD", "entity_type": "company", "identification_type": "company_registered_number", "identification_value": "9876543210", "merchant_reference_id": "AllStarLimo", "account_number": "0987654321", "aba": "987654321" }' ``` - ```json { "status": { "error_code": "", "status": "SUCCESS", "message": "", "response_code": "", "operation_id": "c81fe963-eea2-4850-8949-1986eb3d0333" }, "data": { "id": "beneficiary_0ae68d2f718c4396450220dba4098973", "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" } } ``` - Create Beneficiary - Rapyd Wallet Confirmation Required - ```curl curl -X post 'https://sandboxapi.rapyd.net/v1/payouts/beneficiary' \ -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 '{ "category": "rapyd_ewallet", "currency": "USD", "confirmation_required": true, "ewallet": "ewallet_3801e782955b29955445586a2405a5db" }' ``` - ```json { "status": { "error_code": "", "status": "SUCCESS", "message": "", "response_code": "", "operation_id": "866250ec-3557-48ce-8fd1-7ccbcb44e0e2" }, "data": { "id": "beneficiary_a3bd93c5336d443c2e23cc47279bb959", "currency": "USD", "ewallet": "ewallet_3801e782955b29955445586a2405a5db", "confirmation_required": true, "category": "rapyd_ewallet" } } ``` - Create Beneficiary with Card ID - ```curl curl -X post 'https://sandboxapi.rapyd.net/v1/payouts/beneficiary' \ -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 '{ "category": "card", "country": "NG", "currency": "NGN", "entity_type": "individual", "first_name": "John", "last_name": "Doe", "identification_type": "work permit", "identification_value": "6658412", "merchant_reference_id": "JohnDoeOffice", "payment_type": "regular", "address": "123 Main Street", "city": "Anytown", "postcode": "12345", "card_id": "card_16913c402be05e4dae48d081643f8368" }' ``` - ```json { "status": { "error_code": "", "status": "SUCCESS", "message": "", "response_code": "", "operation_id": "42f18bde-b8de-4258-b222-ff98a1c5494c" }, "data": { "id": "beneficiary_30e73ee3eccdde746ab7cbf8d746b947", "last_name": "Doe", "first_name": "John", "country": "NG", "entity_type": "individual", "address": "123 Main Street", "name": "John Doe", "postcode": "12345", "city": "Anytown", "currency": "NGN", "identification_type": "work permit", "identification_value": "*******", "merchant_reference_id": "JohnDoeOffice", "bin_details": { "type": "DEBIT", "brand": "MASTERCARD", "level": "BUSINESS", "issuer": "HDFC BANK LIMITED", "country": "IN", "bin_number": "512939" }, "card_expiration_year": "28", "card_expiration_month": "08", "card_number": "5122", "payment_type": "regular", "category": "card" } } ``` - Create Beneficiary with Card Details - ```curl curl -X post 'https://sandboxapi.rapyd.net/v1/payouts/beneficiary' \ -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 '{ "category": "card", "country": "NG", "currency": "NGN", "entity_type": "individual", "first_name": "John", "last_name": "Doe", "identification_type": "identification_id", "identification_value": "123456789", "default_payout_method_type": "xx_mastercardglobal_card", "email": "jOHNdoe@Rapyd.net ", "card_number": "4111111111111111", "card_expiration_month": "11", "card_expiration_year": "34", "card_cvv": "123", "merchant_reference_id": "JohnDoe", "payment_type": "priority", "address": "123 Main Street", "city": "Anytown", "state": "New State", "postcode": "12345" }' ``` - ```json { "status": { "error_code": "", "status": "SUCCESS", "message": "", "response_code": "", "operation_id": "b7d5762f-c7da-4485-ab02-e00a46eeb44d" }, "data": { "id": "beneficiary_a0388cf7520394c427a6b09f4b83e691", "last_name": "Doe", "first_name": "John", "country": "NG", "entity_type": "individual", "address": "123 Main Street", "name": "John Doe", "postcode": "12345", "city": "Anytown", "state": "New State", "currency": "NGN", "email": "jOHNdoe@Rapyd.net ", "identification_type": "identification_id", "identification_value": "*********", "merchant_reference_id": "JohnDoe", "bin_details": { "type": "DEBIT", "brand": "VISA", "level": "CLASSIC", "issuer": "CONOTOXIA SP. Z O.O", "country": "PL", "bin_number": "411111" }, "card_expiration_year": "34", "card_expiration_month": "11", "card_number": "1111", "payment_type": "priority", "category": "card", "default_payout_method_type": "xx_mastercardglobal_card" } } ``` - Bad Request - Invalid Payout Category - ```curl curl -X post 'https://sandboxapi.rapyd.net/v1/payouts/beneficiary' \ -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 '{ "category": "pos", "country": "US", "currency": "USD", "entity_type": "individual", "first_name": "John", "last_name": "Doe", "identification_type": "identification_id", "identification_value": "123456789", "default_payout_method_type": "us_general_bank", "merchant_reference_id": "JohnDoe", "payment_type": "priority", "address": "1 Main Street", "city": "Any Town", "state": "New State", "postcode": "12345", "account_number": "1234567", "bic_swift": "12345678XXX" }' ``` - ```json { "status": { "error_code": "INVALID_PAYOUT_TYPE", "status": "ERROR", "message": "The request attempted an operation that requires a payout category, but the payout category was not found. The request was rejected. Corrective action: Set 'category' to one of the following values: 'bank', 'card', 'cash', 'ewallet', 'rapyd_ewallet'", "response_code": "INVALID_PAYOUT_TYPE", "operation_id": "729e7f72-6337-4652-a52e-082dc1e550fd" } } ``` - Bad Request - Invalid Payout Beneficiary Entity Type - ```curl curl -X post 'https://sandboxapi.rapyd.net/v1/payouts/beneficiary' \ -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 '{ "category": "bank", "country": "US", "currency": "USD", "entity_type": "personal", "first_name": "John", "last_name": "Doe", "identification_type": "identification_id", "identification_value": "123456789", "default_payout_method_type": "us_general_bank", "merchant_reference_id": "JohnDoe", "payment_type": "priority", "address": "1 Main Street", "city": "Any Town", "state": "New State", "postcode": "12345", "account_number": "1234567", "bic_swift": "12345678XXX" }' ``` - ```json { "status": { "error_code": "ERROR_INVALID_PAYOUT_BENEFICIARY_ENTITY_TYPE", "status": "ERROR", "message": "The request tried to create a beneficiary for a payout, but the entity type was not recognized. The request was rejected. Corrective action: Set the beneficiary entity type to 'company' or 'individual'.", "response_code": "ERROR_INVALID_PAYOUT_BENEFICIARY_ENTITY_TYPE", "operation_id": "881c53a1-8e4f-469e-9f8e-6073acef1748" } } ```