Manage customer

Submit customer information within your payment.

Customer resource allows you to send information about the customer, like name and address together with your payment. Unzer Direct Debit Secured, Unzer Invoice Secured, and Unzer Instalment payment methods require customer resource. Customer resource can be stored for using with future payments, refunds, or reversals. In Unzer payment system, a customer resource can be created, fetched, updated and deleted.

Types of customers

There are three different customer types:

  • B2C customer
  • registered B2B customer
  • not-registered B2B customer

Go to Manage customer (API) page to learn more about customer types.

Create a customer

Customer types only differ in the mandatory parameters but use the same Customer-class and resource. We added the CustomerFactory to provide for an easy way to create the needed customer object. It contains three static methods with the required arguments and returns the customer object to be created.

The customer object created with the CustomerFactory is not yet known to the API.
You can create the corresponding resource either by calling Unzer->createCustomer($customer) or by using it in a transaction call e. g. Unzer::authorize(...) which will implicitly create the customer resource if required.

Request

#
$unzer    = new UnzerSDK\Unzer('s-priv-xxxxxxxxxx');
$customer = UnzerSDK\Resources\CustomerFactory::createCustomer('Max', 'Mustermann');
$unzer->createCustomer($customer);
$unzer    = new UnzerSDK\Unzer('s-priv-xxxxxxxxxx');
$address  = (new UnzerSDK\Resources\EmbeddedResources\Address())
            ->setName('Max Mustermann')
            ->setStreet('Musterstraße. 2')
            ->setZip('12345')
            ->setCity('Musterstadt')
            ->setCountry('DE')
            ->setState('DE-1');

$customer = UnzerSDK\Resources\CustomerFactory::createRegisteredB2bCustomer(
            $address,
            '123',
            'abc GmbH',
            UnzerSDK\Constants\CompanyCommercialSectorItems::ACCOMMODATION
        );

$unzer->createCustomer($customer);
$unzer    = new UnzerSDK\Unzer('s-priv-xxxxxxxxxx');
$address  = (new UnzerSDK\Resources\EmbeddedResources\Address())
            ->setName('Max Mustermann')
            ->setStreet('Musterstraße. 2')
            ->setZip('12345')
            ->setCity('Musterstadt')
            ->setCountry('DE')
            ->setState('DE-1');

$customer = UnzerSDK\Resources\CustomerFactory::createNotRegisteredB2bCustomer(
            'Max',
            'Mustermann',
            '2000-12-12',
            $address,
            'info@unzer.com',
            'abc GmbH',
            UnzerSDK\Constants\CompanyCommercialSectorItems::ACCOMMODATION
        );

$unzer->createCustomer($customer);

Response

A customer ID is generated that is later used for fetching transaction data related to the customer. The createCustomer method returns a customer object that contains the ID from the created customer resource. You can access the ID by calling the getId method of the customer object.

$customer->getId();

Parameter of CustomerFactory::createCustomer()

Name Type Description
firstname string The first name of the customer.
Required: true
lastname string The last name of the customer.
Required: true

Parameter of CustomerFactory::createNotRegisteredB2bCustomer()

Name Type Description
firstname string The first name of the customer.
Required: true
lastname string The last name of the customer.
Required: true
birthDate string The birth date of the customer.
Required: true
Format: ‘YYYY-MM-DD’
billingAddress UnzerSDK\Resources\EmbeddedResources\Address The billing address.
Required: true
email string The email address of the customer.
Required: true
company string The company name.
Required: true
commercialSector UnzerSDK\Constants\CompanyCommercialSectorItems The commercial sector of the company.
Required: false
Default: UnzerSDK\Constants\CompanyCommercialSectorItems::OTHER

Parameter of CustomerFactory::createRegisteredB2bCustomer()

Name Type Description
billingAddress UnzerSDK\Resources\EmbeddedResources\Address The billing address of the customer.
Required: true
commercialRegisterNumber string The last name of the customer.
Required: true
company string The company name.
Required: true
commercialSector UnzerSDK\Constants\CompanyCommercialSectorItems The commercial sector of the company.
Required: false
Default: UnzerSDK\Constants\CompanyCommercialSectorItems::OTHER

Update customer details

To update customer details, call the updateCustomer method of the unzer class.

Request

$unzer    = new UnzerSDK\Unzer('s-priv-xxxxxxxxxx');
$customer = $unzer->fetchCustomer('s-cst-xxxxxxxxx');
$customer-> $customer->setEmail('updated.email@test.com');
$unzer->updateCustomer($customer);
The customer ID once created, cannot be updated.

Fetch the customer to view the updated fields

$unzer = new UnzerSDK\Unzer('s-priv-xxxxxxxxxx');
$customer = $unzer->fetchCustomer('s-cst-xxxxxxxxx');
echo $customer->getEmail();

Delete a customer

You can delete a customer by calling the deleteCustomermethod with the customer ID.

Request

$unzer = new UnzerSDK\Unzer('s-priv-xxxxxxxxxx');
unzer->deleteCustomer(s-cst-xxxxxxxxx);

When you fetch the customer with that customer ID, you will get an error that the customer does not exist. In the PHP-SDK this will raise an UnzerApiException that needs to be handled.

Request

try {
    $unzer = new UnzerSDK\Unzer('s-priv-xxxxxxxxxx');
    $customer = $unzer->fetchCustomer('s-cst-xxxxxxxxx');
} catch (UnzerApiException $e) {
    // API returned error resource.
    $this->log($e->getClientMessage());
    $this->log($e->getMerchantMessage());
}

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 request:

Request

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

$unzer         = new UnzerSDK\Unzer('s-priv-xxxxxxxxxx');
$ppl           = $unzer->fetchPaymentType('s-ppl-9wmri5mdlqps');
$authorization = $ppl->authorize(100.0, 'EUR', 'https://your.return.url', 's-cst-xxxxxxxxx');

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

Response

$customerId = $authorization->getCustomerId();

After you’ve linked a customer to a payment, the payment workflow will contain the customerId in the resources object and it is not necessary to link the customer in following transactions.

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 authorize call:

  • Unzer Instalment

See also