Unzer

Manage customer

Submit customer information within your payment.

A customer is a person or entity that buys good or services from you. For example, a customer can be anyone buying shoes online to a company placing an order for 100 printers for their office. In most cases, customers also initiate a transaction. This is the starting point in the payment workflow.

Customers can be physically present when making the purchase, for example for POS payment or buy online, for online payments. A customer resource can be stored for using it for future payments, refunds, or reversals. Customers can store their shopping details for faster check out the next time (link to CIT).

They can also authorize you to deduct scheduled payments for subscriptions or top-ups.

In Unzer payment system, a customer resources can be created, fetched, updated, and deleted.

Types of customers

Customers can be classified as B2C customers and B2B customers.

B2C Customer

These customers are individuals direct buying your products or services. Only firstname and lastname are mandatory parameters for creating a B2C customer resources.

B2C Customer for Unzer Direct Debit Secured, Unzer Invoice & Unzer Instalment

In order to ensure proper functionality and risk checks for Unzer Direct Debit Secured, Unzer Invoice & Unzer Instalment Secured, it’s necessary to send additional customer data including:

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

Only one address is mandatory, and it can be either the billing or the shipping address.

Matching the shipping and billing addressess

For Unzer Direct Debit Secured, Unzer Invoice, and Unzer Instalment Secured, the shipping and billing address should be the same for a successful payment workflow. This is a required for fraud prevention and secure payment.

B2B Customer

Registered customer

B2B customers work in the exact same way as B2C customer resources, with the addition of B2B specific parameters. There are two types of B2B customers:

  • Registered (a company registered in the commercial register with a commercial register number)
  • Not registered (a company does not have a commercial register number)

To create and use B2B customer resources, you have to have the contract that allows this type of customer configuration. Otherwise, you won’t be able to set B2B specific customer attributes.

icon info
Supported payment types for B2B customers

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

The mandatory parameter list for B2B customers is as follows:

Field B2B registered customer B2B unregistered customer
address Required Required
street Required Required
zip Required Required
city Required Required
country Required Required
company Required Required
companyInfo Required Required
registrationType Required Required
commercialRegisterNumber Required Not required
registrationType Required Required
function Not required Required
commercialSector Not required Required

Create a customer

To create a customer resource, make a POST request to customer API call.

You can specify the details for the customer and add metadata as required.

POST {{domain}}/v1/customers

{
  "lastname": "Doe",
  "firstname": "John",
  "salutation": "mr",
  "company": "Sample Company GmbH",
  "customerId": "{{customer_external_id}}",
  "birthDate": "1987-12-20",
  "email": "John.Doe@unzer.com",
  "phone": "+49 1234 64 71 100",
  "mobile" : "+49 123 123 456",
    "billingAddress" : {
      "name" : "John Doe",
      "street" : "Sample street 5",
      "state" : "DE-BO",
      "zip" : "12345",
      "city" : "Sample city",
      "country" : "DE"
    },
     "shippingAddress" : {
      "name" : "John Doe",
      "street" : "Sample street 5",
      "state" : "DE-BO",
      "zip" : "12345",
      "city" : "Sample city",
      "country" : "DE"
    },
    "companyInfo" : {
      "registrationType": "not_registered",
        "function": "OWNER", 
        "commercialSector": "abc"
     }
 }
Parameter Type Description
id (required) string Specify the customer ID. If left blank, Unzer system generates a random customer ID
lastname (required) string(60) Specify the customer’s last name.
firstname(required) string(60) Specify the customer’s first name
salutation string Specify the customer’s Salutation. Available values are mr, mrs, unknown
company(conditional) string(40) Specify the customer’s company name, required for B2B customers.
birthDate Date Customer’s Date of birth

Required for: Unzer Invoice and
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 (conditional) 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 string B2B is registered or not registered (not_registered) as a 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 ‘>’

A customer ID is generated that is later used for fetching transaction data related to the customer.

{
    "id": "s-cst-4b6396786d21"
}

Update customer details

You can also update the customer details, when required. The customer ID once created, cannot be updated.

Send a PUT request specifying the customer for whom you want to update the details.

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

Body:
{
  "firstname": "Gorden",
  "billingAddress": {
    "name": "Gorden Doe"
  }
}

Send a GET request to view the updated fields

GET {{domain}}/v1/customers/{{customer_id}}

"id": "s-cst-4b6396786d21",
    "lastname": "Universum",
    "firstname": "Gorden",
    "salutation": "mr",
    "company": "heidelpay GmbH",
    "customerId": "John.Doe_1623821452_364@heidelpay.com",
    "birthDate": "1987-12-20",
    "email": "john.doe@heidelpay.com",
    "phone": "+4962216471100",
    "mobile": "+49172123456",
    "billingAddress": {
        "name": "Gorden Doe",
        "street": "Hugo-Junkers-Str. 5",
        "state": "DE-BO",
        "zip": "60386",
        "city": "Frankfurt am Main",
        "country": "DE"
    }...

Delete a customer

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

DELETE {{domain}}/v1/customers/s-cst-4b6396786d21

When you send a GET request for the customer ID, you will get an error that the customer does not exist.

GET {{domain}}/v1/customers/s-cst-4b6396786d21

{
    "id": "s-err-5463de2f656647629ec900949ca",
    "isSuccess": false,
    "isPending": false,
    "isError": true,
    "url": "https://stg-api.heidelpay.com/v1/customers/s-cst-4b6396786d21",
    "timestamp": "2021-06-16 09:59:16",
    "traceId": "89286ff1f5a819dff413cb5b2a408d8f",
    "errors": [
        {
            "code": "API.410.100.100",
            "merchantMessage": "Customer cannot be found with the key s-cst-4b6396786d21",
            "customerMessage": "Customer cannot be found. Please contact us for more information."
        }
    ]
}

Add a customer to a payment

You must link the customer resource to the payment when creating a charge or authorization.

Simply add an already existing customer resource (see creating a customer) within the resources object in a payment.

For example, during an authorize (link to authorize a payment) request:

POST {{domain}}/v1/marketplace/payments/authorize

{
  "amount" : "350.00",
  "currency" : "EUR",
  "returnUrl": "http://unzer.com",
  "resources" : {
  	"customerId": "s-cst-ca736814f3ee",
    "basketId" : "s-bsk-9100",
    "typeId" : "s-ppl-zgs5mdwhfmma"
  }
}

You should now see the customerId in the payment response and after calling GET on said payment.

{
    "id": "s-aut-1",
    "isSuccess": false,
    "isPending": true,
    "isError": false,
    "redirectUrl": "https://stg-payment.unzer.com/v1/redirect/paypalot/s-HLoFdL89hknK",
    "message": {
        "code": "COR.000.200.000",
        "merchant": "Transaction pending",
        "customer": "Your payment is currently pending. Please contact us for more information."
    },
    "amount": "350.0000",
    "currency": "EUR",
    "returnUrl": "http://unzer.com",
    "date": "2021-06-16 05:50:58",
    "resources": {
        "customerId": "s-cst-ca736814f3ee",
        "paymentId": "s-pay-7490",
        "basketId": "s-bsk-9100",
        "traceId": "d63b2c6959c966117b027f838083a0f5",
        "typeId": "s-ppl-zgs5mdwhfmma"
    },
    "paymentReference": "",
    "processing": {
        "uniqueId": "31HA07BC8133F7E165CCA27BF75720F8",
        "shortId": "4877.4905.6473",
        "traceId": "d63b2c6959c966117b027f838083a0f5",
        "participantId": "31HA07BC814FC247577B195E59A99FC6"
    }
}

After you’ve linked a customer to a payment, the payment workflow will contain the customerId in the resources object.

  • authorize > cancel authorize
  • authorize > charge > shipment
  • authorize > charge > cancel charge
  • charge > shipment
  • charge > cancel charge

Payment methods with mandatory customer resources

There are 3 different payment methods, which require you to link a customer resource during a payment. You need the customer resource during authorization and charge.

During a charge call:

During an authorization call:

See also