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

Accessing payment customer API

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

PaymentCustomersApi customerApi = new 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 passing credentials to specific OAuth*Credentials constructor
  • pass created OAuth*Credentials object to Authenticator constructor
  • call getToken() method from Authenticator class
  • save result of previous called method to as a OAuth*Token object
  • call getAccessToken() method from OAuth*Token class
  • set obtained access token using ApiClient method called setAccessToken(accessToken)
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 constructor.

OAuthClientCredentials oAuthClientCredentials = new OAuthClientCredentials(
        "09ae83af7c37121b2de929b211bad944",
        "9c5f250b69f6436cb38fd780349bc00810d8d5051d3dcf821e428f65a32724bd"
);
Authenticator authenticator = new Authenticator(oAuthClientCredentials);

Method getToken() will return token object, which contains more information abut token like eg. expire time, creation date. Method getAccessToken() will return access token string value that can be passed to ApiClient instance.

String accessToken = null;

try {
    OAuthClientToken token = (OAuthClientToken) authenticator.getToken();
    accessToken = token.getAccessToken();
} catch (ApiException e) {
    e.printStackTrace();
}


ApiClient customerApiClient = customerApi.getApiClient();
customerApiClient.setAccessToken(accessToken);

CRUD example

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

Before making first API call make sure that:

  • Correct host is set in ApiClient
  • Authentication succeeded and token is saved to ApiClient
  • 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 class

Represents all customer data
fielddescriptiontypepossible values
objectThe name of the smart objectStringpayment.customers
id

id of payment container

String(3 letters)_(30 alphanumeric signs)
contractpayment customer contractProductInstanceUID
contactcustomer contactPaymentCustomersDTOContact
createdPaymentCustomersProductModel creation date
DateTime
2018-02-13T11:52:13+01:00
updatedPaymentCustomersProductModel update date
DateTime
2018-02-13T11:58:30+01:00

PaymentCustomersDTO class

Represents data needed to create or update customer
fielddescriptiontypepossible values
contactcustomer contactPaymentCustomerDTOContact

PaymentCustomersDTOContact class

Contact information for customer
fielddescriptiontypepossible 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
urlWebsiteUniform Resource Locator to customer webstiteStringwww.example.com
birthplacecustomer birthplaceStringDresden
nationalitycustomer nationalityStringDE
addresscustomer addressAddress-
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.

PaymentCustomersDTOContact contact = new PaymentCustomersDTOContact();
contact.setForename("John");
contact.setSurname("Doe");
contact.setCompanyname("Example Inc.");

PaymentCustomersDTO customerDTO = new PaymentCustomersDTO();
customerDTO.setContact(contact);

PaymentCustomersProductModel customer = customerApi.paymentCustomersPost(customerDTO);

Result is PaymentCustomersProductModel object.

In case fail result is ApiException.

Delete an existing customer

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

String customerId = '';
List<PaymentCustomersProductModel> deletedCustomerList = customerApi.paymentCustomersIdDelete(customerId);
PaymentCustomersProductModel deletedCustomer = deletedCustomerList.get(0);

Result is PaymentCustomersProductModel.

In case fail result is ApiException.