The customer is the customer of the merchant. There is an object created with the payment transaction. So in most cases "Customer" is the person who will pay the created payment transaction.

Customer is a collection of personal data and address.

Every time a new customer (payer) registered on the platform and wants to make a payment for the first time, it is necessary to transfer the customer data to the secuconnect-API. The created Customer-ID can then be reused for each future payment transaction payment

Possible actions :

  • create a new customer;
  • read the customers data;
  • update an existing customer;
  • delete a customer;
  • read a list of all existing customers.

Every API user who is able to access the payment service can create a new customer, read his data, update it, delete it and get a list of all existing customers.

API uses following data structures:

  • PaymentCustomerDTO

The following parameter SHOULD be transmitted on every update or create:

  • forename
  • surname
  • companyname (only in case of a company)
  • email
  • address
    • street
    • street_number
    • postal_code
    • city
    • country

You find more information in the different sections below.

The customer object

{
    "contact": {
        "salutation": "Mr.",
        "title": "Dr.",
        "forename": "John",
        "surname": "Doe",
        "companyname": "Example Inc.",
        "dob": "1901-02-03",
        "email": "example@example.com",
        "phone": "0049-123-456789",
        "mobile": "0049-987-654321",
        "address": {
            "street": "Example Street",
            "street_number": "6a",
            "postal_code": "01234",
            "city": "Examplecity",
            "country": "Germany"
        }
    }
}

Supported actions


Create a new customer (paymentCustomersPost)

To create new Customer PaymentCustomersDTO need to be passed to paymentCustomersPost method from PaymentCustomersApi class. With PaymentCustomersDTO prepared we can pass it to paymentCustomersPost.

Example

(In this code example there is no Authentication part, it is explained here.)

// Build request objects
$contactAddress = new Address();
$contactAddress
  ->setStreet('Frankfurter Str.')
  ->setStreetNumber('125a')
  ->setPostalCode('60326')
  ->setCity('Frankfurt am Main')
  ->setCountry('Germany');

First we create address.

$customerContact = new PaymentCustomersDTOContact();
$customerContact
  ->setSalutation('Mr.')
  ->setTitle('Dr.')
  ->setForename('John')
  ->setSurname('Doe')
  ->setCompanyname('My Company Inc.')
  ->setDob('1905-03-03')
  ->setEmail('mr-john-doe@mail.com')
  ->setPhone('0049-123-456789')
  ->setMobile('0049-987-654321')
  ->setAddress($contactAddress);

Then we provide other contact informations.

$customer = new PaymentCustomersDTO();
$customer->setContact($customerContact);

Customer DTO only contains contact information.

// Make request
try {
  $api = new PaymentCustomersApi();
  $response = $api->paymentCustomersPost($customer);
  // Success. $response contain PaymentCustomersProductModel
  $customerId = $response->getId();

  echo 'Created new payment customer product with ID: ' . $customerId . PHP_EOL;
  echo 'Payment customer product data after create:' . PHP_EOL . $response . PHP_EOL;
} catch (\Secuconnect\Client\ApiException $e) {
  // Failure. $e->getResponseBody() contains ProductExceptionPayload
  echo $e->getResponseBody() . PHP_EOL;
  throw $e;
}

It's very straightforward code example. Most important is:

  • build request objects to line 21 (of course it's just a simple example in real life it will look differently) - this request object contains information about customer address and his personal and contact data like: surname, email, phone, etc.
  • making a request to our API using PHP SDK on line 25 we create new object of PaymentCustomersApi and then sending the request using paymentCustomersPost method to create new User

Response

Success

If creation succeeded $response will contain instance of PaymentCustomersProductModel.

Error

In case of error $e→getResponseBody() will contain ProductExceptionPayload with 2 possible specific types:

ErrorPossible reasons
ProductFormatException
  • no payload
  • invalid dob format
Example of successful response

After successful creating new payment customer we get a response like below:

{
    "object": "payment.customers",
    "id": "PCU_2...7",
    "contract": {
        "object": "payment.contracts",
        "id": "PCR_2...6"
    },
    "contact": {
        "forename": "John",
        "surname": "Doe",
        "companyname": "My Company Inc.",
        "salutation": "Mr.",
        "title": "Dr.",
        "email": "mr-john-doe@mail.com",
        "phone": "0049-123-456789",
        "mobile": "0049-987-654321",
        "dob": "1905-03-03T00:00:00+01:00",
        "address": {
            "street": "Frankfurter Str.",
            "street_number": "125a",
            "city": "Frankfurt am Main",
            "postal_code": "60326",
            "country": "Germany"
        }
    },
    "created": "2017-12-22T14:59:32+01:00"
}

Update an existing customer (paymentCustomersIdPut)

To update customer it's ID is required and PaymentCustomersDTO must be updated with new values of properties.

Example

Let's reuse $customer object from previous section, and assume that $customerId contains customer ID, then we can update it by following code:

(in this code example there is no Authentication part, it is explained here)

// Build request objects
$contactAddress = new Address();
$contactAddress
  ->setStreet('Braslauer Str.')
  ->setStreetNumber('41c')
  ->setPostalCode('01129')
  ->setCity('Dresden')
  ->setCountry('Germany');

We are creating customer address.

$customerContact = new PaymentCustomersDTOContact();
$customerContact
  ->setSalutation('Mr.')
  ->setTitle('Dr.')
  ->setForename('John')
  ->setSurname('Doe')
  ->setCompanyname('My Company Inc.')
  ->setDob('1905-03-03')
  ->setEmail('mr-john-doe@mail.com')
  ->setPhone('0049-123-456789')
  ->setMobile('0049-987-654321')
  ->setAddress($this->contactAddress);

We are setting updated contact informations.

$customer = new PaymentCustomersDTO();
$customer->setContact($customerContact);

We are setting contact on customer dto.

$customerId = 'PCU_2...7';

We also need ID of existing customer. It's the same value as PaymentCustomerProductModel::getId().

// Make request
try {
  $api = new PaymentCustomersApi();
  $response = $api->paymentCustomersIdPut($customerId, $customer);
  // Sucess. $response contain PaymentCustomersProductModel
  echo 'Payment customer product data after update:' . PHP_EOL . $response . PHP_EOL;
} catch (\Secuconnect\Client\ApiException $e) {
  // Failure. $e->getResponseBody() contains ProductExceptionPayload
  echo $e->getResponseBody() . PHP_EOL;
  throw $e;
}

It's very similar to creating a new customer. Most importat things are:

  • build request objects to line 26 (of course it's just a simple example in real life it will look differently) very important is to fill the customerId that we want to update and information about customer address, his personal and contact data like: surname, email, phone, etc. NOTE: We need to enter the same data as when a new customer is creating, because when we don't enter those data, then existing data will be overwritten by empty values.
  • making a request to our api using PHP SDK on line 29 we create new object of PaymentCustomersApi and then sending the request using paymentCustomersIdPut method to update existing User

Response

Success

If update succeeded $response will contain instance of PaymentCustomersProductModel.

Error

In case of error $e→getResponseBody() will contain ProductExceptionPayload with 2 possible specific types:

ErrorPossible reasons
ProductFormatException
  • no payload
  • invalid dob format
Example successful response

After successful updating existing payment customer we get a response like below:

{
    "object": "payment.contracts",
    "id": "PCR_WSM5A4J0K2MZ63JRX75XU59HYW3JAK",
    "demo": true,
    "allow_cloning": true,
    "sepa_mandate_inform": "never",
    "created": "2017-12-29T11:46:15+01:00",
    "updated": "2017-12-29T11:59:26+01:00"
}

Delete an existing customer (paymentCustomersIdDelete)

To delete customer, it's ID is required and should be passed to paymentCustomersIdDelete method from PaymentCustomersApi class.

Example

(in this code example there is no Authentication part, it is explained here)

$customerId = 'PCU_2...7';

// Make request
try {
  $api = new PaymentCustomersApi();
  $response = $api->paymentCustomersIdDelete($customerId);
  // Sucess. $response contain PaymentCustomersProductModel
  echo 'Data of payment customer product, which deleted:' . PHP_EOL . $response . PHP_EOL;
} catch (\Secuconnect\Client\ApiException $e) {
  // Failure. $e->getResponseBody() contains ProductExceptionPayload
  echo $e->getResponseBody() . PHP_EOL;
  throw $e;
}


To delete a customer only thing we have to do is:

  • to fill customerId that we want to delete and then call paymentCustomersIdDelete method of PaymentCustomersApi (line 6)

Response

Success

If delete succeeded $response will contain instance of PaymentCustomersProductModel, which was deleted.

Error

In case of error $e→getResponseBody() will contain ProductExceptionPayload with 1 possible specific types:

ErrorPossible reasons
ProductNotAllowedException
  • incorrect customer id
Example successful response

After successful deleting existing payment customer we get a response like below:

[
    {
        "object": "payment.contracts",
        "id": "PCR_WSM5A4J0K2MZ63JRX75XU59HYW3JAK",
        "demo": true,
        "allow_cloning": true,
        "sepa_mandate_inform": "never",
        "created": "2017-12-29T11:46:15+01:00",
        "updated": "2017-12-29T11:59:26+01:00"
    }
]

Search for an existing Customer (paymentCustomersGetById)

Existing customers can be search by id, PaymentCustomersAPI paymentCustomersGetById should be used for it:

Example

try {
	$api = new PaymentCustomersApi();
    $response = $api->paymentCustomersGetById($customerId);
    if(empty($response)) {
        // Not found.
    } else {
        // Sucess. $response contain PaymentCustomersProductModel
    }
    
} catch (\Exception $e) {
    // Failure. E.g. network issues.
}

To search a customer only thing we have to do is:

  • to fill customerId that we want to search and then call paymentCustomersIdGetById method of PaymentCustomersApi (line 3)

Response

Success

If search succeeded and customer exists $response will contain instance of PaymentCustomersProductModel, which was found. 

Error

If no matching customer will be found, empty object will be returned.

Obtain list of Customers (paymentCustomersGet)

Existing customers can be listed using PaymentCustomersAPI paymentCustomersGet method.

Example

(in this code example there is no Authentication part, it is explained here)

try {
	$api = new PaymentCustomersApi();
    $response = $api->paymentCustomersGet();
    if(empty($response)) {
        // No customers found.
    } else {
        // Sucess. $response contain list of PaymentCustomersProductModel
        $response->getCount();
        foreach($response->getData() as $customer) {...}
    }
    // Sucess. $response contain list of PaymentCustomersProductModels
} catch (\Exception $e) {
    // Failure. E.g. network issues.
}

To obtain list of customers we must:

  •  call paymentCustomersGet method of PaymentCustomersApi (line 3)

Response

Success

If obtain succeeded and any customers exist $response will contain object with count of existing customers and data, where data is a list of PaymentCustomersProductModel.