Create shopper details

Create a new shopper address

Creates an address including name for the shopper.

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


Name Type Description
merchant_key MerchantKey The key of the merchant.


Not applicable.


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.
+ postalcode String(1, 35) O The postal or zip code.
+ city String(1, 35) M The city.
+ state String(1, 40) C A state or province. Is mandatory for Argentina, Brazil, Canada, China, Indonesia, India, Japan, Mexico, Thailand and the USA when PayPal is used as payment method.
+ 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 Afterpay, Klarna, Giropay, ELV, E-Financing, and Capayable.


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://testsecure.docdatapayments.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",
             "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, same key is generated for shopper_key and address_key. In the future it will be different.