Create Extended Beneficiary
Create a beneficiary that includes all compliance related data for payouts.
The response provides a unique beneficiary ID, which you can use in place of the beneficiary object for Create Payout
This method triggers the Beneficiary Created Webhook webhook. This webhook contains the same information as the response.
Nota
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, and you must conform to the regex provided.
To create an extended 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), bad requests (400), and an unauthorized request (401). For all error messages that appear due to bad requests, see Payout Errors and General Errors.
/v1/payouts/extended_beneficiary
Create Extended Beneficiary - Individual
curl -X post 'https://sandboxapi.rapyd.net/v1/payouts/extended_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", "date_of_birth": "12/12/1999", "nationality": "US", "gender": "male", "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": "NewTown", "state": "New State", "postcode": "12345", "account_number": "1234567" }'{ "status": { "error_code": "", "status": "SUCCESS", "message": "", "response_code": "", "operation_id": "013d9492-dc77-4f6f-8dc8-f30424e27f41" }, "data": { "id": "beneficiary_210dac4f3b5d9843dfb381d5846fbed8", "last_name": "Doe", "first_name": "John", "country": "US", "entity_type": "individual", "address": "1 Main Street", "name": "John Doe", "date_of_birth": "12/12/1999", "postcode": "12345", "city": "NewTown", "state": "New State", "account_number": "1234567", "currency": "USD", "identification_type": "identification_id", "identification_value": "*********", "nationality": "US", "merchant_reference_id": "JohnDoe", "gender": "male", "payment_type": "priority", "category": "bank", "default_payout_method_type": "us_general_bank" } }
Create Extended Beneficiary - Company
curl -X post 'https://sandboxapi.rapyd.net/v1/payouts/extended_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", "date_of_incorporation": "11/11/1995", "country_of_incorporation": "US", "address": "425 12th avenue", "city": "anytown", "country": "US", "currency": "USD", "entity_type": "company", "identification_type": "company_registered_number", "identification_value": "9876543210", "merchant_reference_id": "AllStarLimo", "account_number": "0987654321", "aba": "987654321" }'{ "status": { "error_code": "", "status": "SUCCESS", "message": "", "response_code": "", "operation_id": "9849242a-fc10-4fec-8dc8-b8e2fff31c0a" }, "data": { "id": "beneficiary_bbfe53c25eb3f56cf2cabdcbcd2017ee", "country": "US", "entity_type": "company", "address": "425 12th avenue", "name": "All Star Limousine", "date_of_incorporation": "11/11/1995", "city": "anytown", "company_name": "All Star Limousine", "account_number": "0987654321", "currency": "USD", "identification_type": "company_registered_number", "identification_value": "**********", "merchant_reference_id": "AllStarLimo", "country_of_incorporation": "US", "aba": "987654321", "category": "bank" } }
Bad Request - Invalid Extended Beneficiary Field - ID Type (Individual)
curl -X post 'https://sandboxapi.rapyd.net/v1/payouts/extended_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", "date_of_birth": "12/12/1999", "nationality": "US", "gender": "male", "identification_type": "employment_permit", "identification_value": "123456789", "default_payout_method_type": "us_general_bank", "merchant_reference_id": "JohnDoe", "payment_type": "priority", "address": "1 Main Street", "city": "NewTown", "state": "New State", "postcode": "12345", "account_number": "1234567" }'{ "status": { "error_code": "INVALID_REQUIRED_FIELD - [IDENTIFICATION_TYPE]", "status": "ERROR", "message": "The request attempted a payout operation, but the value of one of the fields was not valid. The request was rejected. Corrective action: The name of the problematic field appears at the end of the error code. Provide a value that matches the regex defined in the response to 'Get Payout Required Fields'.", "response_code": "INVALID_REQUIRED_FIELD - [IDENTIFICATION_TYPE]", "operation_id": "ee34f230-6c8d-4c13-bf90-c2fe493024d6" } }
Bad Request - Missing Input Fields (Individual)
curl -X post 'https://sandboxapi.rapyd.net/v1/payouts/extended_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", "date_of_birth": "12/12/1999", "nationality": "US", "gender": "male", "identification_type": "identification_id", "identification_value": "", "default_payout_method_type": "us_general_bank", "merchant_reference_id": "JohnDoe", "payment_type": "priority", "address": "1 Main Street", "city": "NewTown", "state": "New State", "postcode": "12345", "account_number": "1234567" }'{ "status": { "error_code": "MISSING_FIELDS - [BENEFICIARY.IDENTIFICATION_VALUE]", "status": "ERROR", "message": "The request attempted an operation, but one or more required fields were missing. The request was rejected. Corrective action: Provide all of the fields that are listed at the end of the error code. For more information, see the API Reference.", "response_code": "MISSING_FIELDS - [BENEFICIARY.IDENTIFICATION_VALUE]", "operation_id": "01c90ee8-14fc-4f81-adb3-65155dc2efb1" } }
Unauthorized
curl -X post 'https://sandboxapi.rapyd.net/v1/payouts/extended_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", "date_of_birth": "12/12/1999", "nationality": "US", "gender": "male", "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": "NewTown", "state": "New State", "postcode": "12345", "account_number": "1234567" }'{ "status": { "error_code": "UNAUTHENTICATED_API_CALL", "status": "ERROR", "message": "The request was rejected due to an authentication issue. Corrective action: Check the status of your account in the 'Account Details' page of the Client Portal.", "response_code": "UNAUTHENTICATED_API_CALL", "operation_id": "822e6076-930e-4619-a4ce-fa8763b40d7d" } }