Sample application

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.

Accessing payment customer API
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.

Authentication with client credentials
OAuthClientCredentials oAuthClientCredentials = new OAuthClientCredentials(
"...",
"..."
);
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.

Accessing payment customers API
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.

Preflight checklist

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

Model vs DTO

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

field

description

type

possible values

object

The name of the smart object

String

payment.customers

id

id of payment container

String

(3 letters)_(30 alphanumeric signs)

contract

payment customer contract

ProductInstanceUID

contact

customer contact

PaymentCustomersDTOContact

created

PaymentCustomersProductModel creation date

DateTime

2018-02-13T11:52:13+01:00

updated

PaymentCustomersProductModel update date

DateTime

2018-02-13T11:58:30+01:00

PaymentCustomersDTO class

Represents data needed to create or update customer

field

description

type

possible values

contact

customer contact

PaymentCustomerDTOContact

PaymentCustomersDTOContact class

Contact information for customer

field

description

type

possible values

forename

customer forename

String

John

surname

customer surname

String

Doe

companyname

customer company name

String

Example Inc.

salutation

customer salutation

String

"Herr", "Frau" or any other appropriate

gender

customer gender

String

#TODO

title

customer academic title

String

"Dr." or any other appropriate

email

customer email

String

example@example.com

phone

customer phone number

String

0049-123-456789

mobile

customer mobile number

String

0049-987-654321

dob

customer date of birth

String

1901-02-03

picture

Document id of an picture

String

urlWebsite

Uniform Resource Locator to customer webstite

String

www.example.com

birthplace

customer birthplace

String

Dresden

nationality

customer nationality

String

DE

address

customer address

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.

Creating new customer
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.

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

Result is PaymentCustomersProductModel.

In case fail result is ApiException.