alt

Important information

Please be advised that there will be a scheduled downtime across our API network on November 05 and November 07, 2024. For more information, visit our platform status portal.:
- Scheduled maintenance on November 5, 2024
- Scheduled maintenance on November 7, 2024

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 resource.

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

For payment workflow and risk checks for Direct Debit Secured, Unzer Invoice & Unzer Installment, it’s necessary to send additional customer data including:

  • firstname
  • lastname
  • birthdate
  • 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 addresses

For Direct Debit Secured, Unzer Invoice, and Unzer Installment, the shipping and billing address should be the same for a successful payment workflow. This is 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:

FieldB2B registered customerB2B unregistered customer
addressRequiredRequired
streetRequiredRequired
zipRequiredRequired
cityRequiredRequired
countryRequiredRequired
companyRequiredRequired
companyInfoRequiredRequired
commercialRegisterNumberRequiredNot required
registrationTypeRequiredRequired
functionNot requiredRequired
commercialSectorNot requiredRequired

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"
     }
 }
ParameterTypeDescription
id (required)stringSpecify the customer ID. If left blank, Unzer system generates a random customer ID
firstname(required)string(40)Specify the customer’s first name
lastname (required)string(40)Specify the customer’s last name
salutationenumSpecify the customer’s Salutation. Available values are mr, mrs, unknown
company(conditional)string(60)Specify the customer’s company name, required for B2B customers
birthDateDate
YYYY-MM-DD
Customer’s date of birth

Required for: Unzer Invoice and
Mandatory in case of companyInfoModel.registrationType is NOT_REGISTERED
customerIdstring(256)Specify the 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)Specify the customer’s email address
Mandatory in case of companyInfoModel.registrationType is NOT_REGISTERED
phonestring(24)
Pattern: ([0–9 +]+)
Customer’s phone number
mobilestring(24)
Pattern: ([0–9 +]+)
Customer’s mobile number
billingAddressobjectCustomer’s billing address
billingAddress.namestring(81)Specify the customer’name for billing. Use this field if the name for billing is different to the customer name
billingAddress.streetstring(64)Specify the customer’s street (only for billing address)
billingAddress.statestring(256)Specify the customer’s state (only for billing address)
billingAddress.zipstring(10)Specify the customer’s postal code (only for billing address)
billingAddress.citystring(30)Specify the customer’s city (only for billing address)
billingAddress.countrystring(2)Specify the customer’s country in ISO country code ISO 3166 ALPHA-2 (only for billing address)
shippingAddressobjectSpecify the customer’s shipping address.
shippingAddress.namestring(81)Specify the name of the person for the shipping Address
shippingAddress.streetstring(64)Specify the street address (only for shipping address)
shippingAddress.statestring(256)Specify the State (only for shipping address)
shippingAddress.zipstring(10)Specify the postal code (only for shipping address)
shippingAddress.citystring(30)Specify the city (only for shipping address)
shippingAddress.countrystring(2)Specify the country in ISO country code ISO 3166 ALPHA-2 (only for shipping address)
companyInfo.registrationTypestring(256)Specify if B2B is registered or not registered (not_registered) as a customer
companyInfo.commercialRegisterNumberstring(256)Mandatory if companyInfoModel.registrationType is REGISTERED, restricted ‘<’ and ‘>’.
companyInfo.commercialSectorstring(256)Mandatory if companyInfoModel.registrationType is NOT_REGISTERED, restricted ‘<’ and ‘>
Valid values
* OTHER
* WHOLESALE_TRADE_EXCEPT_VEHICLE_TRADE
* RETAIL_TRADE_EXCEPT_VEHICLE_TRADE
* WATER_TRANSPORT
* AIR_TRANSPORT
* WAREHOUSING_AND_SUPPORT_ACTIVITIES_FOR_TRANSPORTATION
* POSTAL_AND_COURIER_ACTIVITIES
* ACCOMMODATION
* FOOD_AND_BEVERAGE_SERVICE_ACTIVITIES
* MOTION_PICTURE_PRODUCTION_AND_SIMILAR_ACTIVITIES
* TELECOMMUNICATIONS
* COMPUTER_PROGRAMMING_CONSULTANCY_AND_RELATED_ACTIVITIES
* INFORMATION_SERVICE_ACTIVITIES
* RENTAL_AND_LEASING_ACTIVITIES
* TRAVEL_AGENCY_AND_RELATED_ACTIVITIES
* SERVICES_TO_BUILDINGS_AND_LANDSCAPE_ACTIVITIES
* LIBRARIES_AND_SIMILAR_CULTURAL_ACTIVITIES
* SPORTS_ACTIVITIES_AND_AMUSEMENT_AND_RECREATION_ACTIVITIES
* OTHER_PERSONAL_SERVICE_ACTIVITIES
* NON_RESIDENTIAL_REAL_ESTATE_ACTIVITIES
* MANAGEMENT_CONSULTANCY_ACTIVITIES
* ELECTRICITY_GAS_AND_STEAM_SUPPLY
* WATER_COLLECTION_TREATMENT_AND_SUPPLY
* SEWERAGE
* MANUFACTURE_OF_FOOD_PRODUCTS
* MANUFACTURE_OF_BEVERAGES
* MANUFACTURE_OF_TEXTILES
* OTHERS_COMMERCIAL_SECTORS
* MANUFACTURE_OF_WEARING_APPAREL
* MANUFACTURE_OF_LEATHER_AND_RELATED_PRODUCTS
* MANUFACTURE_OF_PHARMACEUTICAL_PRODUCTS
* REPAIR_AND_INSTALLATION_OF_MACHINERY_AND_EQUIPMENT
* TRADE_AND_REPAIR_OF_MOTOR_VEHICLES
* PUBLISHING_ACTIVITIES
* REPAIR_OF_COMPUTERS_AND_GOODS
* PRINTING_AND_REPRODUCTION_OF_RECORDED_MEDIA
* MANUFACTURE_OF_FURNITURE
* OTHER_MANUFACTURING
* ADVERTISING_AND_MARKET_RESEARCH
* OTHER_PROFESSIONAL_SCIENTIFIC_AND_TECHNICAL_ACTIVITIES
* ARTS_ENTERTAINMENT_AND_RECREATION
companyInfo.functionstring(256)Specify 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/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