Dashboard ↗

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

FieldTypeDescription
idstring
readonly
String value that uniquely identifies the customer.
default_token_id (Expandable)stringDefault token for the customer. This is used as the payment token when you supply the customer’s ID as a payment source.
tokens[]objectTokens that belong to the customer (which can be cards or other payment methods).
See Tokens object
transactions[]objectTransactions that were started by the customer (which can be in any transaction state).
See Transaction object
emailstringCustomer’s email address.
Must be a valid email
first_namestringFirst name of the customer.
Maximum 80 characters long
last_namestringLast name of the customer.
Maximum 80 characters long
address1stringFirst line of the customer’s address.
Maximum 80 characters long
address2stringSecond line of the customer’s address.
Maximum 80 characters long
citystringCity of the customer’s address.
Maximum 80 characters long
statestringState or county of the customer’s address.
Maximum 80 characters long
zipstringZIP code of the customer’s address.
Maximum 16 characters long
country_codestringCountry code of the customer’s address (US, FR…).
phoneobjectPhone number of the customer.
legal_documentstringLegal document number (required in some countries).
Maximum 255 characters long; example for a CPF document in Brazil: 853.513.468-93
ip_addressstringIP address of the customer.
Must be a valid IPv4 or IPv6 address
sexstringSex of the customer. Can be male or female.
date_of_birthdatetimeCustomer’s date of birth.
is_businessbooleanDenotes whether or not the customer represents a business.
metadataobjectMetadata related to the customer, in the form of key-value pairs (string - string).
registered_atdatetimeDate when the customer was registered on your platform. This defaults to the same date as created_at if you omit it.
sandboxboolean
readonly
Denotes whether or not this customer was created in the sandbox testing environment.
created_atdatetimeDate 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

FieldTypeDescription
numberstringPhone number without the dialing code.
Maximum 14 characters long
dialing_codestringInternational 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
}