Customer

Submit additional customer information within your payment.

Certain payment methods, like Unzer Direct Debit Secured and Unzer Invoice Secured require more than just payment data - that’s where the customer resource comes into play. With its help, you can easily add and submit additional customer information within your payments.

Customer resources can be created, fetched, updated and deleted.

There are two types of customers the system supports: B2B (business-to-business) and B2C (business-to-consumer). For B2B customer, additional information must be defined in companyinfo when creating a resource. For further information, see the the table down below.

Supported payment types for B2B customers

You can create and use B2B customer resources only with secured payment, and with the following payment methods:

Attributes

Here’s a list of of customer attributes, their type/format and a brief description. Mandatory fields are marked bold:

name format description
id string Customer ID returned by the Unzer API
lastname string(40) The customer’s first name.
firstname string(40) Customer’s First name
salutation mr,mrs,unknown Customer’s Salutation
company string(40) Customer’s Company name
birthDate Date Customer’s Date of birth
Mandatory in case of companyInfoModel.registrationType is NOT_REGISTERED
customerId string(256) Customer’s Unique ID within the merchant system. It identifies the customer and can be used within the GET request. The customerId must be unique and cannot be used a second time.
email string(100) Customer’s Mail address
Mandatory in case of companyInfoModel.registrationType is NOT_REGISTERED
phone string(20)
Pattern: ([0-9 +]+)
Customer’s Phone number
mobile string(20)
Pattern: ([0-9 +]+)
Customer’s Mobile number
billingAddress object Customer’s billing address.
billingAddress.name string Name for billing. Use this field if the name for billing is different to the customer name
billingAddress.street string(50) Customer’s Street (only for billing address)
billingAddress.state string(8) Customer’s State (only for billing address)
billingAddress.zip string(10) Customer’s Postal Code (only for billing address)
billingAddress.city string(30) Customer’s City (only for billing address)
billingAddress.country string(2) Customer’s Country in ISO country code ISO 3166 ALPHA-2 (only for billing address)
shippingAddress object Customer’s Shipping Address.
shippingAddress.name string Name of Person for Shipping Address
shippingAddress.street string(50) Customer’s Street (only for shipping address)
shippingAddress.state string(8) Customer’s State (only for shipping address)
shippingAddress.zip string(10) Customer’s Postal Code (only for shipping address)
shippingAddress.city string(30) Customer’s City (only for shipping address)
shippingAddress.country string(2) Customer’s Country in ISO country code ISO 3166 ALPHA-2 (only for shipping address)
companyInfo.registrationType “registered” or “not_registered” B2B registered or not registered customer
companyInfo.commercialRegisterNumber string(256) Mandatory if companyInfoModel.registrationType is REGISTERED, restricted ‘<’ and ‘>’
companyInfo.commercialSector string(256) Mandatory if companyInfoModel.registrationType is NOT_REGISTERED, restricted ‘<’ and ‘>
companyInfo.function string(256) Must be the value “OWNER” for NOT_REGISTERED, restricted ‘<’ and ‘>’

Mandatory parameters

Only firstname and lastname are mandatory parameters for creating a B2C customer resource by itself. Although this will work with most payment methods a selected few payment types require additional information - namely Unzer Direct Debit Secured and Unzer Invoice Secured.

If you want to create a B2B customer resource you will also need additional (B2B specific) parameters. You can find all mandatory customer parameters below:

B2C Customer

Only firstname and lastname are mandatory parameters for creating a B2C customer resources.

  • firstname
  • lastname

B2C Customer for Unzer Direct Debit Secured & Unzer Invoice Secured

In order to ensure proper functionality and risk-checks for Unzer Direct Debit Secured and Unzer Invoice Secured, it’s necessary to pass additional customer data.

Here’s the minimum required for the aforementioned payment types:

  • firstname
  • lastname
  • birthday
  • address
  • street
  • zip
  • city
  • country

Only one address is mandatory and it doesn’t matter if it’s the billing or the shipping address.

Matching shipping- and billing address
In case there’s any difference between shipping- and a billing address assigned to a single customer, the payment won’t go through and an error will be thrown. In order for the payment to work, both addresses need to be the same.
This only applies to Unzer Direct Debit Secured and unzer Invoice Secured.

B2B Customer Registered

B2B customers work in the exact same way as B2C customer resources with the addition of B2B specific parameters. With that said, there’s a difference between a registered (a company registered in the commercial register with a commercial register number) and a not registered B2B customer type.

The mandatory parameter list for registered B2B customers is as follows:

  • address
  • street
  • zip
  • city
  • country
  • company
  • companyInfo
  • registrationType
  • commercialRegisterNumber

B2B Customer not Registered

The mandatory parameter list for unregistered B2B customers is as follows:

  • birthday
  • email
  • address
  • street
  • zip
  • city
  • country
  • company
  • companyInfo
  • registrationType
  • function
  • commercialSector

Creating a customer

You can create a customer resource by executing a POST request with the customer data.

Remember: firstname and lastname are mandatory parameters, the rest is either optional or defined by the payment method.

UnzerAPI - Creating a customer

POST https://api.unzer.com/v1/customers

Body:
{
  "lastname": "Mustermann",
  "firstname": "Max",
  "salutation": "mr",
  "company": "Unzer GmbH",
  "customerId": "51222",
  "birthDate": "1970-01-01",
  "email": "info@unzer.com",
  "phone": "+49 6221 - 64 71 100",
  "mobile": "+49 172 123 456",
  "billingAddress": {
    "name": "Max Mustermann",
    "street": "Musterstrasse 15",
    "state": "DE-BW",
    "zip": "69115",
    "city": "Heidelberg",
    "country": "DE"
  },
  "shippingAddress": {
    "name": "Max Mustermann",
    "street": "Musterstrasse 15",
    "state": "DE-BW",
    "zip": "69115",
    "city": "Heidelberg",
    "country": "DE"
  },
  //Additional information for B2B Customer
  "companyInfo" : {
    "registrationType": "registered|not_registered",  // Mandatory in case companyInfo is existing, restrict '<' and '>'
    "commercialRegisterNumber": "...", // Mandatory for REGISTERED, restrict '<' and '>'
    "function": "...", // Mandatory must be the value "OWNER" for NOT_REGISTERED, restrict '<' and '>'
    "commercialSector": "..."// Mandatory for NOT_REGISTERED, restrict '<' and '>'
  }
}
Public / Private Key
A customer can be created by using either the private or the public key.

Updating a customer

To update a customer, simply execute a PUT request on an already existing customer resource ID. Only the data you want to change should be included in the request.

Here’s an update example:

UnzerAPI - Updating customer

PUT https://api.unzer.com/v1/customers/s-cst-wz434039493

Body:
{
  "firstname": "Gorden",
  "billingAddress": {
    "name": "Gorden Doe"
  }
}
Public / Private Key
A customer can be updated by using either the private or the public key.

Fetching a customer

You can fetch customer data using a GET request on the customer resource ID. This has to be done with you private key. A very good alternative is to use the customerId as identifier to fetch the data instead of the ID.

UnzerAPI - fetching custmer

// Fetch the data using the customerId
GET https://api.unzer.com/v1/customers/s-cst-wz434039493

OR
// Fetch the data using the customerId
GET https://api.unzer.com/v1/customers/51222
Private Key
Note: You can only fetch customer data using your private key.

Depending on your parameters, the results may differ but it should look something like this:

UnzerAPI - Fetching customer result

Response: {
  "id": "s-cst-wz434039493",
  "lastname": "Mustermann",
  "firstname": "Max",
  "salutation": "mr",
  "company": "Unzer GmbH",
  "customerId": "51222",
  "birthDate": "1970-01-01",
  "email": "info@unzer.com",
  "phone": "+49 6221 64 71 100",
  "mobile": "+49 172 123 456",
  "billingAddress": {
    "name": "Max Mustermann",
    "street": "Musterstrasse 15",
    "state": "DE-BW",
    "zip": "69115",
    "city": "Heidelberg",
    "country": "DE"
  },
  "shippingAddress": {
    "name": "Max Mustermann",
    "street": "Musterstrasse 15",
    "state": "DE-BW",
    "zip": "69115",
    "city": "Heidelberg",
    "country": "DE"
  }
  "geoLocation": {
    "clientIp": "115.77.111.254",
    "countryCode": "AT"
  }
  //Additional information for B2B Customer
  "companyInfo": {
    "registrationType": "registered",
    "commercialRegisterNumber": "123456789",
    "function": "owner",
    "commercialSector": "finance"
  }
}

Deleting a customer

You can delete a customer by using a DELETE request on the customer ID.

UnzerAPI - Deleting customer

DELETE https://api.unzer.com/v1/customers/s-cst-wz434039493

Linking a customer to a payment

In order to sufficiently use customer resources, it is necessary to link them to a payment, such as authorize or charge.

To do that, simply add an already created customer resource (see creating a customer) within the resources object in a payment.

For example, during an authorize call:

Authorize

{
  "amount" : "1.00",
  "currency" : "EUR",
  "returnUrl": "https://www.unzer.com",
  "resources" : {
    "typeId" : "s-crd-fm7tifzkqewy",
    "customerId" : "s-cst-wz434039493"
  }
}

If done correctly, the customerId will be linked to that payment regardless of outcome. You should now see the customerId in the payment response and after calling GET on said payment.

Authorize response

{
  "id": "s-aut-1",
  "isSuccess": true,
  "isPending": false,
  "isError": false,
  "card3ds": false,
  "redirectUrl": "",
  "message": {
    "code": "COR.000.100.112",
    "customer": "Request successfully processed in 'Merchant in Connector Test Mode'"
  },
  "amount": "200.0000",
  "currency": "EUR",
  "returnUrl": "https://www.unzer.com",
  "date": "2019-10-25 07:07:50",
  "resources": {
    "customerId": "s-cst-wz434039493",
    "paymentId": "s-pay-6259",
    "basketId": "",
    "supportId": "604d4244ac538ff9c63dc397df1caf3f",
    "typeId": "s-crd-bsl2qgf7eeda"
  },
  "paymentReference": "",
  "processing": {
    "uniqueId": "31HA07BC81A42F0C230B5984FFB304A5",
    "shortId": "4359.1367.0074",
    "3dsecure": "false"
  }
}

After you’ve linked a customer to a payment, all consecutive payments contain the same customerId in the resources object. Continuing our example, if you were to charge after the authorization, you wouldn’t need to pass the customerId again. It will automatically be there.

The same goes for:

Mandatory customer resources

There are 4 different payment methods, which require you to link a customer resource during a payment. Keep that in mind when trying to authorize/charge any of these:

During a charge call:

During an authorize call: