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.

Customer resource allows you to send information about the customer, like name and address together with your payment. Direct Debit Secured, Unzer Invoice, and Unzer Installment 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
  • unregistered 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. Currently, we provide 2 different versions of the Customer resource:

  • \UnzerSDK\Resources\Customer –> Current version using private key and low entropy ID.
  • \UnzerSDK\Resources\V2\Customer –> Next version (prototype) using token and high entropy ID.

No matter which Customer class you use, a new customer object is not yet known to the API. To create the corresponding resource either call Unzer->createCustomer($customer) or use 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 = $unzer->createCustomer((new Customer())->setFirstname('Max')->setLastname('Mustermann')->setEmail('m.m@test.de'));
$unzer->createCustomer($customer);
$unzer    = new UnzerSDK\Unzer('s-priv-xxxxxxxxxx');

// Create a basic customer (B2C)
$customer = new Customer();
$customer->setFirstname('Marc')
         ->setLastname('Dononvan')
         ->setBirthDate('2001-12-12')
         ->setEmail('marc.donovan@unzer.com')
         ->setCompany('Unzer GmbH');

$customer->getBillingAddress()
         ->setName('Marc Dononvan')
         ->setStreet('Hugo-Junkers-Str. 5')
         ->setZip('60386')
         ->setCity('Frankfurt am Main')
         ->setCountry('DE')
         ->setState('DE-BO');

// Add company info to make it a B2B customer.
$companyInfo = new CompanyInfo();
$companyInfo->setCommercialSector(CompanyCommercialSectorItems::OTHER)
            ->setCompanyType(CompanyTypes::SOLE)
            ->setOwner((new CompanyOwner())->setFirstname("Marc")->setLastname("Dononvan")->setBirthdate("1995-06-21"))
            ->setFunction('Owner')
            ->setRegistrationType(CompanyRegistrationTypes::REGISTRATION_TYPE_REGISTERED);
$customer->setCompanyInfo($companyInfo);

// Create the customer resource.
$this->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();

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);
icon info
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/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 authorization call:

See also