Create shopper details.

Create New Shopper

Creates an address including name for the shopper.

POST /ps/api/public/v1/merchants/{merchant_key}/shoppers

Identifiers

Name	Type	Description
merchant_key	MerchantKey	The key of the merchant.

Parameters

Not applicable.

Request

Field	Type	M	Description
shopper_reference	String(1, 50)	M	The shopper reference from the merchant.
type	Enum(35)	M	Type of customer. The default value is 'CONSUMER'.
name	Block	M	The shopper name for the address.
+ initials	String(1, 35)	O	The initials. This field is commonly omitted.
+ first	String(1, 35)	M	The first given name. It depends on `type`.
+ middle	String(1, 35)	O	Any subsequent given name or names. May also be used as middle initial.
+ last	String(1, 100)	M	The family or inherited name(s). The maximum length depends on `type`.
address	Block	M	The address details.
+ street	String(1, 100)	M	The street.
+ housenumber	String(1, 35)	M	The house number.
+ housenumber_addition	String(1, 35)	O	The addition to the house number.
+ postal_code	String(1, 35)	O	The postal or zip code.
+ city	String(1, 35)	M	The city.
+ state	String(1, 40)	C	For PayPal payment method, state should only be provided under certain conditions as mentioned here.
+ country	Country	M	The country as ISO 3166-1 Alpha 2.
email	String(1, 200)	M	The email address of the shopper.
gender	Enum(1)	O	The gender of the shopper: "M" (Male), "F" (Female), or "U" (Unknown).
date_of_birth	Date	O	The date of birth of the shopper (yyyy-mm-dd).
phone_number	String(1, 50)	O	The phone number of the shopper.

Note :

gender, date_of_birth and phone_number are only used for the payment methods Riverty, Klarna, ELV, E-Financing, and Capayable.
The address fields street, city and state can accept apostrophes at the beginning.

The following values are supported for type:

Value	Maximum Length `name.last`	Notes
CONSUMER	35	The shopper is a consumer.
BUSINESS	100	The shopper is a business. The `name.first` cannot be filled in.

Response

Field	Type	M	Description
shopper_key	ShopperKey	M	The key of the created or existing shopper.
address_key	AddressKey	M	The key of the created address.

HTTP Status

Status	Meaning
201 (Created)	The order is successfully created.
400 (Bad Request)	The request was not valid.
404 (Not Found)	The merchant key was not found.

Create New shopper address example

> curl \
    -X POST \
    --header 'Content-Type: application/json' \
    --header 'Authorization: Basic RG9jZGF0YVBGOkJXazJhZkpV' \
    https://secure.sandbox.pay.cm.com/ps/api/public/v1/merchants/4ef08825-993a-424d-a769-3ee97116a1b6/shoppers \
    -d '{
        "shopper_reference" : "vk20170224p",
        "name" : {
             "first"  : "Johan",
             "middle" : "de",
             "last"   : "Vries"
        },
        "address"   : {
             "street"      : "Hoofdstraat",
             "housenumber" : "82",
             "housenumber_addition": "A",
             "postalcode"  : "3972LB",
             "city"        : "Driebergen-Rijsenburg",
             "state"       : "Utrecht",
             "country"     : "DE"
        },
        "email"         : "[email protected]",
        "gender"        : "M",
        "date_of_birth" : "1996-12-01",
        "phone_number"  : "+31611223344"
    }'
 
< Http 201 Created
<    '{
        "shopper_key" : "ec11cd24-e667-4f9e-a677-5ffe0d4aee5e",
        "address_key" : "ec11cd24-e667-4f9e-a677-5ffe0d4aee5e"
    }'

Note :

Currently, the same key is generated for shopper_key and address_key. In the future it will be different.

Return addresses of a shopper

Return the shopper addresses for given shopper key along with shopper information.

GET /ps/api/public/v1/merchants/{merchant_key}/shoppers/{shopper_key}/addresses

Identifiers

Name	Type	Description
shopper_key	ShopperKey	The key of the shopper.
merchant_key	MerchantKey	The key of the merchant.

Parameters

Not applicable.

Request

Not applicable.

Response

Array of:

Field	Type	M	Description
shopper_reference	String(1, 50)	M	The shopper reference from the merchant.
name	Block	M	The shopper name for the address.
+ initials	String(1, 35)	O	The initials. This field is commonly omitted.
+ first	String(1, 35)	M	The first given name.
+ middle	String(1, 35)	O	Any subsequent given name or names. May also be used as middle initial.
+ last	String(1, 35)	M	The family or inherited name(s).
address	Block	M	The address details.
+ street	String(1, 100)	M	The street.
+ housenumber	String(1, 35)	M	The house number.
+ housenumber_addition	String(1, 35)	O	The addition to the house number.
+ postal_code	String(1, 35)	O	The postal or zip code.
+ city	String(1, 35)	M	The city.
+ state	String(1, 40)	C	For PayPal payment method, state should only be provided under certain conditions as mentioned here.
+ country	Country	O	The country as ISO 3166-1 Alpha 2.
email	String(1, 200)	C	The email address of the shopper.
gender	Enum(1)	O	The gender of the shopper: "M" (Male), "F" (Female), or "U" (Unknown).
date_of_birth	Date	O	The date of birth of the shopper (yyyy-mm-dd).
phone_number	String(1, 50)	O	The phone number of the shopper.

Notes:

The email address may not be filled if the order is created without an email address and the Payment is authorized with an iDeal Fast checkout.
The country may not be filled if the order is created without a country and the Payment is authorized with an iDeal Fast checkout.

HTTP Status

Status	Meaning
200 (OK)	Success.
401 (Unauthorized)	Authorization header missing or invalid.
403 (Forbidden)	The merchant key is not allowed.
404 (Not Found)	The shopper key / merchant key were not found.

Get shopper addresses example

> curl \
    -X GET \
    --header 'Authorization: Basic RG9jZGF0YVBGOkJXazJhZkpV' \
    https://secure.sandbox.pay.cm.com/ps/api/public/v1/merchants/4ef08825-993a-424d-a769-3ee97116a1b6/shoppers/ec11cd24-e667-4f9e-a677-5ffe0d4aee5e/addresses
 
< Http 200 Ok
<    '[
        {
            "shopper_reference": "ceedb1d0-020d-49a5-b1be-6c0a8d6f8ccd",
            "name": {
                "initials": "A",
                "first": "Johan",
                "middle": "de",
                "last": "Vries"
            },
            "address": {
                "street": "Hoofdstraat",
                "housenumber": "82",
                "housenumber_addition": "A",
                "postal_code": "3972LB",
                "city": "Driebergen-Rijsenburg",
                "state": "Utrecht",
                "country": "NL"
            },
            "email": "M",
            "date_of_birth": "1996-12-01",
            "phone_number": "+31611223344"
        }
      ]'