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.

Supported payment types for B2B customers

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

• Unzer Invoice

The mandatory parameter list for B2B customers is as follows:

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"
     }
 }

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:

• Direct Debit Secured
• Unzer Invoice
• (Deprecated) Unzer Direct Debit Secured

During an authorization call:

• Unzer Installment

See also

• Charge a payment
• API reference