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.
To set the customer’s default payment method, use 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.

This method triggers the 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. 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

Parameters

Request Header Parameters

Request Body Parameters

- addresses
- Array of 'address' objects associated with this customer. For details of the fields in the 'address' object, see Create Address.
- business_vat_id
- The tax ID number of the customer.
- coupon
- The ID of a coupon that is assigned to this customer.
- description
- A text description of the customer.
- email
- Customer's email address. Required for some payment methods.
- ewallet
- ID of the wallet that is linked to the customer. String starting with ewallet_. Each wallet can be associated with only one customer.
- 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.
- payment_method
- Required when creating a customer with a payment method. Contains the following parameters: type, fields. Some payment methods require additional parameters.
- 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.
- business_vat_id
- The tax ID number of the customer. Relevant when the customer is a business.
- category
- Category of payment method. Possible values:
  bank_redirect
  bank_transfer
  card
  card_to_card
  cash
  ewallet
  rapyd_ewallet
- 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.
- customer
- ID of the customer profile, a string starting with cus_.
- 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.
- email
- Customer's email address. 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.
- 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.
- 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.
- name
- The 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.
  not_applicable - The payment has completed or the next action is not relevant.
- 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.
  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.
  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.
  type
  The type of the card:
  credit
  debit
  prepaid
  category
  Category of payment method. Possible values:
  bank_redirect
  bank_transfer
  card
  card_to_card
  cash
  ewallet
  rapyd_ewallet
  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.
  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.
  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.
  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.

Code Samples

.NET

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

const makeRequest = require('<path-to-your-utility-file>/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
$path = $_SERVER['DOCUMENT_ROOT'];
$path .= "/<path-to-your-utility-file>/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

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 -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'
-d '{
    "business_vat_id": "123456789",
    "email": "johndoe@rapyd.net",
    "ewallet": "ewallet_ebfe4c4f4d36b076a21369fb0d055f3e",
    "invoice_prefix": "JD-",
    "metadata": {
    	"merchant_defined": true
    },
    "name": "John Doe",
    "phone_number": "+14155559993"
}
'

{
    "status": {
        "error_code": "",
        "status": "SUCCESS",
        "message": "",
        "response_code": "",
        "operation_id": "ac7f0144-b3c1-4af1-bd63-2a71d3606395"
    },
    "data": {
        "id": "cus_7ccd7fe7fd771f34faa6bd84d920aec4",
        "delinquent": false,
        "discount": null,
        "name": "John Doe",
        "default_payment_method": "",
        "description": "",
        "email": "johndoe@rapyd.net",
        "phone_number": "+14155559993",
        "invoice_prefix": "JD-",
        "addresses": [],
        "payment_methods": null,
        "subscriptions": null,
        "created_at": 1575472963,
        "metadata": {
            "merchant_defined": true
        },
        "business_vat_id": "123456789",
        "ewallet": "ewallet_ebfe4c4f4d36b076a21369fb0d055f3e"
    }
}

Create Customer with payment method

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'
-d '{
    "name": "John Doe",
    "business_vat_id": "123456666",
    "email": "johndoe@rapyd.net",
    "ewallet": "ewallet_13c6bdf0e6f18415b8b6754a76ce95b2",
    "invoice_prefix": "JD-",
    "metadata": {
        "merchant_defined": true
    },
    "payment_method": {
        "type": "ua_visa_card",
        "fields": {
            "number": "4111111111111111",
            "expiration_month": "10",
            "expiration_year": "23",
            "cvv": "123",
            "name": "John Doe"
        },
        "complete_payment_url": "https://complete.rapyd.net",
        "error_payment_url": "https://error.rapyd.net"
    },
    "phone_number": "+14155556666"
}
'

{
    "status": {
        "error_code": "",
        "status": "SUCCESS",
        "message": "",
        "response_code": "",
        "operation_id": "cffec000-2962-485e-832a-4bafee4c41fb"
    },
    "data": {
        "id": "cus_aa84d1532589f20702eaa64fde7e547e",
        "delinquent": false,
        "discount": null,
        "name": "John Doe",
        "default_payment_method": "card_4505175fae2baa6c8e9682357858cd71",
        "description": "",
        "email": "johndoe@rapyd.net",
        "phone_number": "+14155556666",
        "invoice_prefix": "JD-",
        "addresses": [],
        "payment_methods": {
            "data": [
                {
                    "id": "card_4505175fae2baa6c8e9682357858cd71",
                    "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": null,
                        "brand": null,
                        "country": null,
                        "bin_number": "411111"
                    },
                    "expiration_year": "23",
                    "expiration_month": "10",
                    "fingerprint_token": "ocfp_e599f990674473ce6283b245e9ad2467",
                    "redirect_url": "https://sandboxcheckout.rapyd.net/3ds-payment?token=payment_a22542357c26715c504558c8240b46b4"
                }
            ],
            "has_more": false,
            "total_count": 1,
            "url": "/v1/customers/cus_aa84d1532589f20702eaa64fde7e547e/payment_methods"
        },
        "subscriptions": null,
        "created_at": 1640099726,
        "metadata": {
            "merchant_defined": true
        },
        "business_vat_id": "123456666",
        "ewallet": "ewallet_13c6bdf0e6f18415b8b6754a76ce95b2",
        "complete_payment_url": "https://complete.rapyd.net",
        "error_payment_url": "https://error.rapyd.net"
    }
}

Create Customer with address

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'
-d '{
    "name": "John Doe",
    "email": "johndoe@rapyd.net",
    "payment_method": {
        "type": "sg_fast_bank",
        "fields": {}
    },
    "addresses": [
        {
            "name": "John Doe",
            "line_1": "123 Main Street",
            "city": "Anytown",
            "state": "NY",
            "country": "US",
            "zip": "12345",
            "phone_number": "+19175551234"
        }
    ]
}
'

{
    "status": {
        "error_code": "",
        "status": "SUCCESS",
        "message": "",
        "response_code": "",
        "operation_id": "f3c96aaa-8fec-41df-b505-bd7b772298cd"
    },
    "data": {
        "id": "cus_545b717371f27b2493d7e318ea7a8879",
        "delinquent": false,
        "discount": null,
        "name": "John Doe",
        "default_payment_method": "other_36790caf5472201f4989eff0cb7d3a45",
        "description": "",
        "email": "johndoe@rapyd.net",
        "phone_number": "",
        "invoice_prefix": "",
        "addresses": [
            {
                "id": "address_b3b76dac12842a954f3c18110d2144d2",
                "name": "John Doe",
                "line_1": "123 Main Street",
                "line_2": "",
                "line_3": "",
                "city": "Anytown",
                "state": "NY",
                "country": "US",
                "zip": "12345",
                "phone_number": "+19175551234",
                "metadata": {},
                "canton": "",
                "district": "",
                "created_at": 1668593933
            }
        ],
        "payment_methods": {
            "data": [
                {
                    "id": "other_36790caf5472201f4989eff0cb7d3a45",
                    "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_545b717371f27b2493d7e318ea7a8879/payment_methods"
        },
        "subscriptions": null,
        "created_at": 1668593933,
        "metadata": {},
        "business_vat_id": "",
        "ewallet": ""
    }
}

In this section:

Documentation