Following section will walk through CRUD scenarios including authentication and configuration. PaymentCustomer API will be used as example.

Other parts of API are described in PaymentAPI.

Configuration

#TODO

Accessing payment customer API

All calls to Payment API need to be executed by calling methods on PaymentCustomerApi instance. Create one using new keyword.

var customerAPI = new SecuConnectApi.PaymentCustomersApi();
Authentication

Each call to API server need to be authenticated with token issued by API server through authentication endpoint. Tokens expire after some time, and different parts of API require different credentials - different tokens.

Authentication workflow

General workflow to authenticate looks as follow:

  • decide which credentials are required
  • create required credentials by calling OAuth*Credentials::from
  • pass it to Authenticator
  • call Authenticator::getToken
  • save result to API instance you want to use
Authentication for payment customer API

Payment Customer API require client credentials: client id, client secret. To pass those to authentication endpoint, pack credentials into OAuthClientCredentials and pass it to Authenticator object.

authenticator = new SecuConnectApi.Authenticator(
    SecuConnectApi.OAuthClientCredentials.from(
        '09ae83af7c37121b2de929b211bad944',
        '9c5f250b69f6436cb38fd780349bc00810d8d5051d3dcf821e428f65a32724bd'
    )
);

Method getToken() will return token that can be passed to PaymentCustomersApi instance.

customerAPI.apiClient.authentications.oauth_token.accessToken = authenticator.getToken();

CRUD example

Following section explains how to create, read, update and delete PaymentCustomer's.

Before making first API call make sure that:

  • Correct host is set in Configuration
  • Authentication succeeded and token is saved to Configuration
  • Instance of desired part of API is accessible
Data models

API uses two kinds of structures for each represented entity. Model and DTO. Model provides full informations about entity, whereas DTO is stripped down data structure that contains only necessary information to perform create and update. In each operation documentation specify which one is expected as input/output.

PaymentCustomersProductModel

Represents all customer data
propertydescriptiontypepossible values
objectThe name of the smart objectstringpayment.customers
id

id of payment container

string(3 letters)_(30 alphanumeric signs)
contractpayment customer contractobject (ProductInstanceUID)
contactcustomer contactobject (PaymentCustomersDTOContact)
createdPaymentCustomersProductModel creation date

string

2018-02-13T11:52:13+01:00
updatedPaymentCustomersProductModel update datestring2018-02-13T11:58:30+01:00

PaymentCustomersDTO

Represents data needed to create or update customer
propertydescriptiontypepossible values
contactcustomer contactobject (

PaymentCustomerDTOContact

Contact information for customer
propertydescriptiontypepossible values
forenamecustomer forenamestringJohn
surnamecustomer surnamestringDoe
companynamecustomer company namestringExample Inc.
salutationcustomer salutationstring"Herr", "Frau" or any other appropriate
gendercustomer genderstring#TODO
titlecustomer academic titlestring"Dr." or any other appropriate
emailcustomer emailstringexample@example.com
phonecustomer phone numberstring0049-123-456789
mobilecustomer mobile numberstring0049-987-654321
dobcustomer date of birthstring1901-02-03
pictureDocument id of an picturestring
url_websiteUniform Resource Locator to customer webstitestringwww.example.com
birthplacecustomer birthplacestringDresden
nationalitycustomer nationalitystringDE
addresscustomer addressobject (Address)-
Create a new customer

To create new Customer PaymentCustomersDTO need to be passed to paymentCustomersPost method from PaymentCustomersApi class.

With PaymentCustomersDTO prepared we can pass it to paymentCustomersPost.

var customerDTO = new SecuConnectApi.PaymentCustomersDTO();
var contact = new SecuConnectApi.PaymentCustomersDTOContact();
var address = new SecuConnectApi.Address();
customerDTO.contact = contact;
contact.surname = "John R.";
contact.forename = "Hacker";
contact.address = address;
address.country = "PL";
address.city = "Wroclaw";
address.street = "Kurkowa";
address.postal_code = "50-000";
address.street_number = "14";

result = customerAPI.paymentCustomersPost(customerDTO);

result.then(function(data) {
    customer = data;
}, function(error) {
    console.error(error);
});

Result is javascript Promise.

If call succeed result will resolve to PaymentCustomerProductModel.

If call fails result will reject to ExceptionPayload and more specificaly to one of following variants:

  • ProductFormatException
  • ProductNotAllowedException
Update an existing customer

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

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

var customerDTO = new SecuConnectApi.PaymentCustomersDTO();
var contact = new SecuConnectApi.PaymentCustomersDTOContact();
var address = new SecuConnectApi.Address();
customerDTO.contact = contact;
contact.surname = "John Random";
contact.forename = "Hacker";
contact.address = address;
address.country = "PL";
address.city = "Wroclaw";
address.street = "Kurkowa";
address.postal_code = "50-000";
address.street_number = "14";

result = customerAPI.paymentCustomersIdPut(customer.id, customerDTO);

result.then(function(data) {
    customer = data;
}, function(error) {
    console.error(error);
});

Result is javascript Promise.

If call succeed result will resolve to PaymentCustomerProductModel.

If call fails result will reject to ExceptionPayload and more specificaly to one of following variants:

  • ProductFormatException
  • ProductNotAllowedException
Search for an existing Customer

SDK exposes two methods responsible for search. One will get all models in a list, other will return single model (if it exists). In each case same data in each model are returned.

Choose whatever suite your needs more.

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

result = customerAPI.paymentCustomersGetById(customer.id);

result.then(function(data) {
}, function(error) {
    console.error(error);
});

Result is javascript Promise.

If call succeed result will resolve to PaymentCustomerProductModel.

Obtain list of Customers

Existing customers can be listed using PyamentCustomersAPI paymentCustomersGet method.

result = customerAPI.paymentCustomersGet();

result.then(function(data) {
}, function(error) {
    console.error(error);
});

Result is javascript Promise.

If call succeed result will resolve to object containing count and data which will be a list of  PaymentCustomerProductModel.

If call fails result will reject to ExceptionPayload and more specificaly to one of following variants:

  • ProductFormatException
  • ProductNotAllowedException
Delete an existing customer

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

result = customerAPI.paymentCustomersIdDelete(customer.id)

result.then(function(data) {
   
}, function(error) {
    console.error(error);
});

Result is javascript Promise.

If call succeed result will resolve to PaymentCustomerProductModel.

If call fails result will reject to ExceptionPayload and more specificaly to one of following variants:

  • ProductNotAllowedException