Skip to main content

Documentation

Create Customer

Create a customer profile to save the payment methods a customer can use.

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:

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.

    • 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
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 3DS data & specific currency

  • 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": "john.doe@rapyd.net",
    "payment_method": {
        "type": "is_visa_card",
        "fields": {
            "name": "John Doe",
            "number": "4111111111111111",
            "expiration_month": "05",
            "expiration_year": "25",
            "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"
    }
}
'
  • {
    "status": {
        "error_code": "",
        "status": "SUCCESS",
        "message": "",
        "response_code": "",
        "operation_id": "5c4ef984-a77a-4a49-b662-52233cfb3306"
    },
    "data": {
        "id": "cus_3fb1b8ab52690e9ff2ac48920f892828",
        "delinquent": false,
        "discount": null,
        "name": "John Doe",
        "default_payment_method": "card_5f05364d29908e6a2e73ff7405f9b2cc",
        "description": "",
        "email": "john.doe@rapyd.net",
        "phone_number": "",
        "invoice_prefix": "",
        "addresses": [],
        "payment_methods": {
            "data": [
                {
                    "id": "card_5f05364d29908e6a2e73ff7405f9b2cc",
                    "type": "is_visa_card",
                    "category": "card",
                    "metadata": null,
                    "image": "https://iconslib.rapyd.net/checkout/is_visa_card.png",
                    "webhook_url": "",
                    "supporting_documentation": "",
                    "next_action": "not_applicable",
                    "name": "John Doe",
                    "last4": "1111",
                    "acs_check": "unchecked",
                    "cvv_check": "unchecked",
                    "bin_details": {
                        "type": "DEBIT",
                        "brand": "VISA",
                        "level": "CREDIT",
                        "issuer": "JPMORGAN CHASE BANK, N.A.",
                        "country": "US",
                        "bin_number": "411111"
                    },
                    "expiration_year": "25",
                    "expiration_month": "05",
                    "fingerprint_token": "ocfp_e599f990674473ce6283b245e9ad2467",
                    "redirect_url": "https://sandboxcheckout.rapyd.net/3ds-payment?token=payment_353babc4043ae66f18638b4b864d7c5a"
                }
            ],
            "has_more": false,
            "total_count": 1,
            "url": "/v1/customers/cus_3fb1b8ab52690e9ff2ac48920f892828/payment_methods"
        },
        "subscriptions": null,
        "created_at": 1720694094,
        "metadata": {},
        "business_vat_id": "",
        "ewallet": "",
        "network_reference_id": 740357,
        "complete_payment_url": "https://www.example21367.com/complete",
        "error_payment_url": "https://www.example21367.com/error"
    }
}

  • 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:

The number of seconds elapsed since the beginning of the Unix epoch, which was 00:00:00 GMT on January 1, 1970. 10-digit integer.