The Customer object contains information about a customer, including contact details. You can also use it to create a customer token from a card or APM token. The customer token stores the payment details for repeated use in the future. (By contrast, you can only use a card or APM token to make a single payment.) When you have created at least one valid token for the customer, you can use the id value of the Customer object itself as a payment source that will reference the token. See the guide page about creating a customer token for full details about creating and using the token.

Customer object

List of fields

📘
While the customer object may seem to contain many parameters, only a handful are useful to merchants. Other may be used under specific scenarios as ProcessOut is fully transparent with the data it gathers. The following list contains most parameters that may be useful to merchants

Field	Type	Description
id	string readonly	String value that uniquely identifies the customer.
default_token_id (Expandable)	string	Default token for the customer. This is used as the payment token when you supply the customer’s ID as a payment source.
tokens	[]object	Tokens that belong to the customer (which can be cards or other payment methods). See Tokens object
transactions	[]object	Transactions that were started by the customer (which can be in any transaction state). See Transaction object
email	string	Customer’s email address. Must be a valid email
first_name	string	First name of the customer. Maximum 80 characters long
last_name	string	Last name of the customer. Maximum 80 characters long
address1	string	First line of the customer’s address. Maximum 80 characters long
address2	string	Second line of the customer’s address. Maximum 80 characters long
city	string	City of the customer’s address. Maximum 80 characters long
state	string	State or county of the customer’s address. Maximum 80 characters long
zip	string	ZIP code of the customer’s address. Maximum 16 characters long
country_code	string	Country code of the customer’s address (`US`, `FR`…).
phone	object	Phone number of the customer.
legal_document	string	Legal document number (required in some countries). Maximum 255 characters long; example for a CPF document in Brazil: 853.513.468-93
ip_address	string	IP address of the customer. Must be a valid IPv4 or IPv6 address
sex	string	Sex of the customer. Can be `male` or `female`.
date_of_birth	datetime	Customer’s date of birth.
is_business	boolean	Denotes whether or not the customer represents a business.
metadata	object	Metadata related to the customer, in the form of key-value pairs (string - string).
registered_at	datetime	Date when the customer was registered on your platform. This defaults to the same date as `created_at` if you omit it.
sandbox	boolean readonly	Denotes whether or not this customer was created in the sandbox testing environment.
created_at	datetime	Date and time when this customer was created.
project_id (Expandable)	string readonly	Project that the customer belongs to.

📘
The billing address of the Customer will be overwritten with the billing address of the invoice, if it is set during transaction processing. In order of priority, ProcessOut uses the invoice billing address, then the Card billing address, before falling back to the Customer billing address if no other address is available.

Phone object

Field	Type	Description
number	string	Phone number without the dialing code. Maximum 14 characters long
dialing_code	string	International dialing code (Note: “+” will be treated as “00”)

JSON object

Customer object

{
    "customer": {
        "id": "cust_D5BDaQQ8XL4xoUfKRjpBQjoEIwMA6asA",
        "project_id": "proj_IFCgGTmyClrgTOzsschN1y7GJttHVQ7S",
        "tokens": null,
        "subscriptions": null,
        "transactions": null,
        "balance": "0",
        "currency": null,
        "email": "[email protected]",
        "first_name": "Matéo",
        "last_name": "Garnier",
        "address1": "6873 Place du 8 Février 1962",
        "address2": "Cedex 7",
        "city": "Marseille",
        "state": "Orne",
        "zip": "80735",
        "country_code": "FR",
        "ip_address": "1.1.1.1",
        "phone": {
            "number": "684758495",
            "dialing_code": "0033"
        },
        "legal_document": "1122.434.234",
        "date_of_birth": "2001-11-11T04:56:05Z",
        "metadata": {},
        "sandbox": true,
        "created_at": "2023-04-22T09:33:12.331728825Z",
        "registered_at": "2005-08-07T23:19:49Z",
        "is_business": false,
        "sex": "male",
        "default_token_id": null
    },
    "success": true
}

Customer object with token expanded

{
    "customer": {
        "id": "cust_QXN34KvkPXXeeiqvuPOkCdCotsIeNP4g",
        "project_id": "proj_IFCgGTmyClrgTOzsschN1y7GJttHVQ7S",
        "tokens": [
            {
                "id": "tok_3neSbvz4aHZtmz2Z2SNDLidevkcEP3zk",
                "customer_id": "cust_QXN34KvkPXXeeiqvuPOkCdCotsIeNP4g",
                "invoice_id": null,
                "gateway_configuration_id": null,
                "gateway_configuration_sub_account": null,
                "card_id": "card_wiSgR41rYiXqnxN2NJQbJKG2aKHdf5hv",
                "is_subscription_only": false,
                "is_default": true,
                "return_url": "https://mymerchant.com/return",
                "cancel_url": "https://mymerchant.com/cancel",
                "is_chargeable": true,
                "type": "card",
                "metadata": {
                    "test": "23456789"
                },
                "description": "Brand new card 2!",
                "created_at": "2023-04-24T10:49:39.299707Z",
                "summary": "**** **** **** 4242",
                "verification_status": "not-requested",
                "manual_invoice_cancellation": null,
                "can_get_balance": null
            },
            {
                "id": "tok_xOvZE0ww8jxLMAen2BBPxNqJNjpZXpNA",
                "customer_id": "cust_QXN34KvkPXXeeiqvuPOkCdCotsIeNP4g",
                "invoice_id": null,
                "gateway_configuration_id": null,
                "gateway_configuration_sub_account": null,
                "card_id": "card_l3D0TcPmkSmeBuYh3xuORmEifFEiRKZj",
                "is_subscription_only": false,
                "is_default": false,
                "return_url": "https://mymerchant.com/return",
                "cancel_url": "https://mymerchant.com/cancel",
                "is_chargeable": true,
                "type": "card",
                "metadata": {
                    "test": "23456789"
                },
                "description": "Card 1 of the customer",
                "created_at": "2023-04-24T10:49:28.50575Z",
                "summary": "**** **** **** 0001",
                "verification_status": "not-requested",
                "manual_invoice_cancellation": null,
                "can_get_balance": null
            }
        ],
        "subscriptions": null,
        "transactions": null,
        "balance": "0",
        "currency": null,
        "email": "[email protected]",
        "first_name": "Loan",
        "last_name": "Richard",
        "address1": "7242 Rue Courbet",
        "address2": "Cedex 7",
        "city": "Courbevoie",
        "state": "Vendée",
        "zip": "23856",
        "country_code": "FR",
        "ip_address": "1.1.1.1",
        "phone": {
            "number": "685869595",
            "dialing_code": "0033"
        },
        "legal_document": "1122.434.234",
        "date_of_birth": "2001-11-11T04:56:05Z",
        "metadata": {},
        "sandbox": true,
        "created_at": "2023-04-24T10:49:20.291426Z",
        "registered_at": "2005-08-07T23:19:49Z",
        "is_business": false,
        "sex": "male",
        "default_token_id": "tok_3neSbvz4aHZtmz2Z2SNDLidevkcEP3zk"
    },
    "success": true
}