--- title: "Create Customer" source_url: https://docs.rapyd.net/en/create-customer.html lang: en --- # Create Customer Create a customer profile to save the payment methods a customer can use. - To add payment methods, use [Add Payment Method to Customer](https://docs.rapyd.net/en/add-payment-method-to-customer.md "Add Payment Method to Customer"). - To set the customer’s default payment method, use [Update Customer](https://docs.rapyd.net/en/update-customer.md "Update Customer"). The response provides a unique Customer ID, which is required for all other operations for this customer. > **Note:** > > - If the customer has more than one address, use `Create Customer` to add the primary address and `Update Customer` to add more addresses. > - In the sandbox, creating a customer with a **card** payment method type requires 3DS authentication by the cardholder. See [Simulating 3DS Authentication](https://docs.rapyd.net/en/simulating-3ds-authentication.md "Simulating 3DS Authentication"). > - For information on the customer in an account funding transaction (AFT), see [Creating an AFT Payment](https://docs.rapyd.net/en/creating-an-aft-payment.md "Creating an AFT Payment"). > - 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") > - [Customer Errors](https://docs.rapyd.net/en/customer-errors.md "Customer 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"). This method triggers the [Customer Created Webhook](https://docs.rapyd.net/en/customer-created-webhook.md "Customer Created Webhook"). This webhook contains the same information as the response. When a customer is created with a **card** payment method type, this method triggers the [Card Added Successfully Webhook](https://docs.rapyd.net/en/card-added-successfully-webhook.md "Card Added Successfully Webhook"). If 3DS is not required, the webhook is sent together with the response, otherwise, it is sent following 3DS authentication. The following asynchronous webhook provides information about later changes to the customer: - [Card Added Failure Webhook](https://docs.rapyd.net/en/card-added-failure-webhook.md "Card Added Failure Webhook") ### 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 - - addresses - Array of 'address' objects associated with this customer. For details of the fields in the 'address' object, see [Create Address](https://docs.rapyd.net/en/create-address.md "Create Address"). - - birth_country - Country where the customer was born. Two-letter ISO 3166-1 ALPHA-2 code for the country. To determine the code for a country, see [List Countries](https://docs.rapyd.net/en/list-countries.md "List Countries"). English characters only. Relevant to an account funding transaction (AFT). - - business_vat_id - The tax ID number of the customer. - - coupon - The ID of a coupon that is assigned to this customer. - - date_of_birth - Date of birth of the customer. Format: **DD/MM/YYYY** Required for an account funding transaction (AFT). - - description - A text description of the customer. - - email - Customer's email address. Required for some payment methods. Recommended for an account funding transaction (AFT). Maximum 512 characters. - - ewallet - ID of the wallet that is linked to the customer. String starting with **ewallet_**. Each wallet can be associated with only one customer. - - holder_id - A generic identifier for the account holder associated with this customer. No country-specific format or validation is applied. - - invoice_prefix - A custom string that is prefixed to all invoices for this customer. - - metadata - A JSON object defined by the client. - - name - The name of the individual customer or the business name. - - nationality - The citizenship of the customer. Two-letter ISO 3166-1 ALPHA-2 code for the country. To determine the code for a country, see [List Countries](https://docs.rapyd.net/en/list-countries.md "List Countries"). English characters only. Relevant to an account funding transaction (AFT). - - occupation - Occupation of the customer. Maximum: 35 characters. Relevant to an account funding transaction (AFT). - - payment_method - Required when creating a customer with a payment method. Contains the following parameters: `type`, `fields`. Some payment methods require additional parameters. - - payment_method_options - Required when creating a customer with a payment method. Additional fields required for the payment method. These values might vary from one use to the next, so they are not saved as part of the payment method object. If your organization manages 3DS authentication then it is recommended to add the 3DS parameters and `currency` parameter to this object. See also the related 'Create Customer with 3DS data & specific currency' sample on this page. - - phone_number - Customer's primary phone number in E.164 format. ### Response Parameters - - addresses - Describes the addresses associated with this customer. For details of the fields in the 'address' object, see [Create Address](https://docs.rapyd.net/en/create-address.md "Create Address"). - - birth_country - Country where the customer was born. Two-letter ISO 3166-1 ALPHA-2 code for the country. - - business_vat_id - The tax ID number of the customer. Relevant when the customer is a business. - - category - Category of payment method. One of the following: - **bank_redirect** - **bank_transfer** - **card** - **card_redirect** - **cash** - **ewallet** - **ewallet_redirect** - - coupon - The ID of a discount coupon that is assigned to this customer. The coupon must use the same currency as the customer's default payment method. - - created_at - Time of creation of this customer, in [Unix time](https://docs.rapyd.net/en/glossary.md#UUID-945d98cf-adae-e1cf-2606-c7fae8b4a7e1_unix_time "Unix time"). - - customer - ID of the customer profile, a string starting with **cus_**. - - date_of_birth - Date of birth of the customer. Format: **DD/MM/YYYY** - - default_payment_method - The payment method that is used when the `payment` object or subscription does not specify a payment method. The value must also appear in the `payment_methods` list. The payment method is referenced by its `name` field. - - delinquent - Indicates whether there is currently a failure of an automatic payment that is part of a subscription, or an invoice that was not paid when due. - - description - A text description of the customer. - - discount - Contains information about the coupon that applies to the customer. To add a discount to a customer, see [Update Customer](https://docs.rapyd.net/en/update-customer.md "Update Customer"). - - email - Customer's email address. - - ewallet - ID of the wallet that is linked to the customer. String starting with **ewallet_**. Each wallet can be associated with only one customer. - - fields - Contains the fields that are for the specific payment method. To determine what fields are required for the payment method, see [Get Payment Method Required Fields](https://docs.rapyd.net/en/get-payment-method-required-fields.md "Get Payment Method Required Fields"). - - holder_id - A generic identifier for the account holder associated with this customer. - - id - ID of the customer profile. String starting with **cus_**. - - invoice_prefix - A custom string that is prefixed to all invoices for this customer. - - metadata - A JSON object defined by the client. See [Metadata](https://docs.rapyd.net/en/metadata.md "Metadata"). - - name - The name of the customer. - - nationality - The citizenship of the customer. Two-letter ISO 3166-1 ALPHA-2 code for the country. - - next_action - Indicates the next action for completing the payment. One of the following values: - **3d_verification** - The next action is 3DS authentication. Relevant only to card payments. - **pending_capture** - The next action is pending the capture of the amount. Relevant only to card payments when the amount is not zero. - **pending_confirmation** - The next action is pending the confirmation for the payment. Relevant to all payment methods excluding card payment. - **pending_offline_capture** - The next action is pending an offline capture, where the payment settles to a **closed** (**CLO**) status via the clearing process. A payment in this state can be successfully refunded, **but cannot be canceled**. Currently, relevant only to Shva Arena card payments. - **not_applicable** - The payment has completed or the next action is not relevant. - - occupation - Occupation of the customer. - - payment_methods - An object containing the following fields: - - data - A list of up to three payment methods. - - acs_check - Results of the Access Control Server (ACS) check. Possible values: - **pass** - **fail** - **unavailable** - **unchecked** Relevant to cards. - - address - Address of the customer. - - canton - Name of the canton administrative subdivision, as used in banking. - - city - City portion of the address. - - country - The two-letter ISO 3166-1 ALPHA-2 code for the country. - - created_at - Time of creation of the object, in [Unix time](https://docs.rapyd.net/en/glossary.md#UUID-945d98cf-adae-e1cf-2606-c7fae8b4a7e1_unix_time "Unix time"). - - district - Name of the district administrative subdivision, as used in banking. - - id - ID of the `address` object. - - line_1 - Line 1 of the address, such as a building number and street name. - - line_2 - Line 2 of the address, such as a suite or apartment number, or the name of a named building. - - line_3 - Line 3 of the address. - - metadata - A JSON object defined by the client. See [Metadata](https://docs.rapyd.net/en/metadata.md "Metadata"). - - name - The name of a contact person or an "in care of" person at this address. For a **personal** wallet contact, alphabetic characters and spaces. - - phone_number - Phone number associated with this specific address in E.164 format. Must be unique. - - state - State or province portion of the address. - - zip - Postal code portion of the address. - - bin_details - Bank identification details. Includes the following fields: - - bin_number - BIN number of the bank. - - brand - The brand of the card. For example, **Visa**. - - country - Country of the bank that issued the card. - - issuer - Business name of the bank that issued the card. - - level - Type of card as categorized by the issuer. - - type - The type of the card: - **credit** - **debit** - **prepaid** - - category - Category of payment method. One of the following: - **bank_redirect** - **bank_transfer** - **card** - **card_redirect** - **cash** - **ewallet** - **ewallet_redirect** - - cvv_check - Verification of the card’s CVV. Valid values: - **pass** - **fail** - **unavailable** - **unchecked** - - fingerprint_token - Hash of the card number, expiration date and CVV. Relevant to cards. - - id - ID of the Payment Method object. String starting with **card_** or **other_**. - - image - A URL to the image of the icon for the type of payment method. - - last4 - Last 4 digits of the card. Relevant to card payment methods. - - metadata - A JSON object defined by the client. See [Metadata](https://docs.rapyd.net/en/metadata.md "Metadata"). - - name - Full name of the customer. - - next_action - Indicates the next action for completing the payment. One of the following values: - **3d_verification** - The next action is 3DS authentication. Relevant only to card payments. - **pending_capture** - The next action is pending the capture of the amount. Relevant only to card payments when the amount is not zero. - **pending_confirmation** - The next action is pending the confirmation for the payment. Relevant to all payment methods excluding card payment. - **pending_offline_capture** - The next action is pending an offline capture, where the payment settles to a **closed** (**CLO**) status via the clearing process. A payment in this state can be successfully refunded, **but cannot be canceled**. Currently, relevant only to Shva Arena card payments. - **not_applicable** - The payment has completed or the next action is not relevant. - - supporting_documentation - Reserved. - - type - Name of the payment method type. For example, **us_mastercard_card**. To get a list of payment methods for a country, use [List Payment Methods by Country](https://docs.rapyd.net/en/list-payment-methods-by-country.md "List Payment Methods by Country"). - - webhook_url - Reserved. - - has_more - Indicates whether there are more than three payment methods for this customer. - - total_count - Total number of payment methods for this customer. - - url - URL for requesting all of the payment methods for this customer. - - phone_number - Customer's primary phone number in E.164 format. The merchant is responsible for verifying that the number is correct. - - subscriptions - Describes the subscriptions associated with this customer. Array of objects. For details of the fields in the 'subscriptions' object, see [Create Subscription](https://docs.rapyd.net/en/create-subscription.md "Create Subscription"). ### Code Samples - - .NET - ```csharp using System; using System.Text.Json; namespace RapydApiRequestSample { class Program { static void Main(string[] args) { try { var metadata = new { merchant_defined = true }; var requestObj = new { business_vat_id = "123456789", email = "johndoe@rapyd.net", ewallet = "ewallet_ebfe4c4f4d36b076a21369fb0d055f3e", invoice_prefix = "JD-", metadata, name = "John Doe", phone_number = "+14155559993" }; string request = JsonSerializer.Serialize(requestObj); string result = RapydApiRequestSample.Utilities.MakeRequest("POST", "/v1/customers", request); 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 body = { business_vat_id: '123456789', email: 'johndoe@rapyd.net', ewallet: 'ewallet_ebfe4c4f4d36b076a21369fb0d055f3e', invoice_prefix: 'JD-', metadata: { merchant_defined: true }, name: 'John Doe', phone_number: '+14155559993' }; const result = await makeRequest('POST', '/v1/customers', body); console.log(result); } catch (error) { console.error('Error completing request', error); } } ``` - - PHP - ```php /utilities.php"; include($path); $body = [ "business_vat_id" => "123456789", "email" => "johndoe@rapyd.net", "ewallet" => "ewallet_ebfe4c4f4d36b076a21369fb0d055f3e", "invoice_prefix" => "JD-", "name" => "John Doe", "phone_number" => "+14155559993", "metadata" => array( "merchant_defined" => true ) ]; try { $object = make_request('post', '/v1/customers', $body); var_dump($object); } catch (Exception $e) { echo "Error => $e"; } ?> ``` - - Python - ```python from pprint import pprint from utilities import make_request customer = { "business_vat_id": "123456789", "email": "johndoe@rapyd.net", "ewallet": "ewallet_ebfe4c4f4d36b076a21369fb0d055f3e", "invoice_prefix": "JD-", "metadata": { "merchant_defined": True }, "name": "John Doe", "phone_number": "+14155559993" } result = make_request(method='post', path='/v1/customers', body=customer) pprint(result) ``` - /v1/customers - Create Customer without payment method - ```curl curl -X post 'https://sandboxapi.rapyd.net/v1/customers' \ -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 '{ "name": "John Doe" }' ``` - ```json { "status": { "error_code": "", "status": "SUCCESS", "message": "", "response_code": "", "operation_id": "bfbcefac-0a85-426a-b942-c024d164a83c" }, "data": { "id": "cus_20f228d17f8da13c9f3eaaa5651124bb", "delinquent": false, "discount": null, "name": "John Doe", "default_payment_method": "", "description": "", "email": "", "phone_number": "", "invoice_prefix": "", "addresses": [], "payment_methods": null, "subscriptions": null, "created_at": 1755767989, "metadata": {}, "business_vat_id": "", "ewallet": "", "occupation": "", "birth_country": "", "date_of_birth": "", "nationality": "" } } ``` - Create Customer with payment method - ```curl curl -X post 'https://sandboxapi.rapyd.net/v1/customers' \ -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 '{ "name": "John Doe", "payment_method": { "type": "ua_visa_card", "fields": { "number": "4111111111111111", "expiration_month": "12", "expiration_year": "30", "cvv": "123", "name": "John Doe" }, "complete_payment_url": "https://complete.rapyd.net", "error_payment_url": "https://error.rapyd.net" } }' ``` - ```json { "status": { "error_code": "", "status": "SUCCESS", "message": "", "response_code": "", "operation_id": "ff53308c-6d5a-44c7-806b-b7061101adb4" }, "data": { "id": "cus_419ddbc908646d598c041dbbfc4ddea0", "delinquent": false, "discount": null, "name": "John Doe", "default_payment_method": "card_51e2e8527a48261db25e87b4c2e33902", "description": "", "email": "", "phone_number": "", "invoice_prefix": "", "addresses": [], "payment_methods": { "data": [ { "id": "card_51e2e8527a48261db25e87b4c2e33902", "type": "ua_visa_card", "category": "card", "metadata": null, "image": "https://iconslib.rapyd.net/checkout/ua_visa_card.png", "webhook_url": "", "supporting_documentation": "", "next_action": "3d_verification", "name": "John Doe", "last4": "1111", "acs_check": "unchecked", "cvv_check": "unchecked", "bin_details": { "type": "DEBIT", "brand": "VISA", "level": "CLASSIC", "issuer": "CONOTOXIA SP. Z O.O", "country": "PL", "bin_number": "411111" }, "expiration_year": "30", "expiration_month": "12", "fingerprint_token": "ocfp_e599f990674473ce6283b245e9ad2467", "redirect_url": "https://sandboxcheckout.rapyd.net/3ds-payment?token=payment_b10f8f64f77230c2daee25ac33c1ad14" } ], "has_more": false, "total_count": 1, "url": "/v1/customers/cus_419ddbc908646d598c041dbbfc4ddea0/payment_methods" }, "subscriptions": null, "created_at": 1761720292, "metadata": {}, "business_vat_id": "", "ewallet": "", "occupation": "", "birth_country": "", "date_of_birth": "", "nationality": "", "network_reference_id": "194072", "complete_payment_url": "https://complete.rapyd.net", "error_payment_url": "https://error.rapyd.net" } } ``` - Create Customer with 3DS data & specific currency - ```curl curl -X post 'https://sandboxapi.rapyd.net/v1/customers' \ -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 '{ "name": "John Doe", "email": "john.doe@rapyd.net", "payment_method": { "type": "is_visa_card", "fields": { "name": "John Doe", "number": "4111111111111111", "expiration_month": "05", "expiration_year": "35", "cvv": "222" }, "complete_payment_url": "https://www.example21367.com/complete", "error_payment_url": "https://www.example21367.com/error" }, "payment_method_options": { "3d_version": "2.2.0", "cavv": "AddddFVmd4iZAKq7zA3u/wAAA=", "eci": "05", "xid": null, "ds_trans_id": "4567a4f1-faa4-49e-39a-3cc977989398", "currency": "EUR" } }' ``` - ```json { "status": { "error_code": "", "status": "SUCCESS", "message": "", "response_code": "", "operation_id": "59e1c437-faec-4147-9ef3-175fdb910894" }, "data": { "id": "cus_85579bd2098d5baf407f7f08313f5318", "delinquent": false, "discount": null, "name": "John Doe", "default_payment_method": "card_169329a41beed1e8fedb9e9bbc10d6b6", "description": "", "email": "john.doe@rapyd.net", "phone_number": "", "invoice_prefix": "", "addresses": [], "payment_methods": { "data": [ { "id": "card_169329a41beed1e8fedb9e9bbc10d6b6", "type": "is_visa_card", "category": "card", "metadata": null, "image": "https://iconslib.rapyd.net/checkout/is_visa_card.png", "webhook_url": "", "supporting_documentation": "", "next_action": "3d_verification", "name": "John Doe", "last4": "1111", "acs_check": "unchecked", "cvv_check": "unchecked", "bin_details": { "type": "DEBIT", "brand": "VISA", "level": "CLASSIC", "issuer": "CONOTOXIA SP. Z O.O", "country": "PL", "bin_number": "411111" }, "expiration_year": "35", "expiration_month": "05", "fingerprint_token": "ocfp_e599f990674473ce6283b245e9ad2467", "redirect_url": "https://sandboxcheckout.rapyd.net/3ds-payment?token=payment_e389585efaac5bfc9372336b7aedf2dd" } ], "has_more": false, "total_count": 1, "url": "/v1/customers/cus_85579bd2098d5baf407f7f08313f5318/payment_methods" }, "subscriptions": null, "created_at": 1756276912, "metadata": {}, "business_vat_id": "", "ewallet": "", "occupation": "", "birth_country": "", "date_of_birth": "", "nationality": "", "network_reference_id": "872182", "complete_payment_url": "https://www.example21367.com/complete", "error_payment_url": "https://www.example21367.com/error" } } ``` - Create Customer with address - ```curl curl -X post 'https://sandboxapi.rapyd.net/v1/customers' \ -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 '{ "name": "John Doe", "email": "johndoe@rapyd.net", "payment_method": { "type": "sg_fast_bank", "fields": {} }, "addresses": [ { "name": "John Doe", "line_1": "123 First Street", "city": "Anytown", "country": "US", "zip": "12345", "phone_number": "+19175551234" } ] }' ``` - ```json { "status": { "error_code": "", "status": "SUCCESS", "message": "", "response_code": "", "operation_id": "234f7103-680d-4e3e-8ff6-20ef39624962" }, "data": { "id": "cus_7aa97a3e2630b19a26b3fcb59fc9c4f8", "delinquent": false, "discount": null, "name": "John Doe", "default_payment_method": "other_acf7bb3d7871998830c2e2d1d65f6639", "description": "", "email": "johndoe@rapyd.net", "phone_number": "", "invoice_prefix": "", "addresses": [ { "id": "address_f87d65d9f9d58f7464b11a8a1ec89e3a", "name": "John Doe", "line_1": "123 First Street", "line_2": "", "line_3": "", "city": "Anytown", "state": "", "country": "US", "zip": "12345", "phone_number": "+19175551234", "metadata": {}, "canton": "", "district": "", "created_at": 1761720480 } ], "payment_methods": { "data": [ { "id": "other_acf7bb3d7871998830c2e2d1d65f6639", "type": "sg_fast_bank", "category": "bank_transfer", "metadata": {}, "image": "https://iconslib.rapyd.net/checkout/sg_fast_bank.png", "webhook_url": "", "supporting_documentation": "", "next_action": "not_applicable", "bic_swift": "", "account_last4": "" } ], "has_more": false, "total_count": 1, "url": "/v1/customers/cus_7aa97a3e2630b19a26b3fcb59fc9c4f8/payment_methods" }, "subscriptions": null, "created_at": 1761720480, "metadata": {}, "business_vat_id": "", "ewallet": "", "occupation": "", "birth_country": "", "date_of_birth": "", "nationality": "" } } ``` - Bad Request - Customer Name Missing - ```curl curl -X post 'https://sandboxapi.rapyd.net/v1/customers' \ -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 '{ "name": "" }' ``` - ```json { "status": { "error_code": "INVALID_CUSTOMER_NAME", "status": "ERROR", "message": "The request tried to create a customer, but the name was missing. The request was rejected. Corrective action: In the 'name' field, provide the customer's full name.", "response_code": "INVALID_CUSTOMER_NAME", "operation_id": "ef420e75-9ea7-4b65-8511-c4164024f6b0" } } ``` - Bad Request - Wallet Belongs to Different Customer - ```curl curl -X post 'https://sandboxapi.rapyd.net/v1/customers' \ -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 '{ "name": "John Doe", "ewallet": "ewallet_4a297ad16911b8a27736fdae225a6caa" }' ``` - ```json { "status": { "error_code": "ERROR_CREATE_CUSTOMER_EWALLET_ALREADY_IN_USE", "status": "ERROR", "message": "The request tried to add a wallet to a customer, but the proposed wallet belongs to a different customer. The request was rejected. Corrective action: For 'ewallet', use the ID of a wallet that does not already belong to a customer.", "response_code": "ERROR_CREATE_CUSTOMER_EWALLET_ALREADY_IN_USE", "operation_id": "6d837d37-a969-4837-af15-5f2b7a9b9ce7" } } ```