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
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 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), 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/beneficiary
Create Beneficiary - Individual
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" }'{ "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 -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" }'{ "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 -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" }'{ "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 -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" }'{ "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 -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" }'{ "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 -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" }'{ "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 -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" }'{ "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" } }
Unauthorized
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" }'{ "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": "90fe896d-13a6-4c40-9935-eee988a71557" } }