Sample application

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.

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

Authentication with client credentials
authenticator = new SecuConnectApi.Authenticator(
SecuConnectApi.OAuthClientCredentials.from(
'...',
'...'
)
);

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

Accessing payment customers API
customerAPI.apiClient.authentications.oauth_token.accessToken = authenticator.getToken();

CRUD example

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

Preflight checklist

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

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

Represents all customer data

property

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

object (ProductInstanceUID)


contact

customer contact

object (PaymentCustomersDTOContact)


created

PaymentCustomersProductModel creation date

string

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

updated

PaymentCustomersProductModel update date

string

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

PaymentCustomersDTO

Represents data needed to create or update customer

property

description

type

possible values

contact

customer contact

object (Sample application JS#PaymentCustomerDTOContact



PaymentCustomerDTOContact

Contact information for customer

property

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


url_website

Uniform Resource Locator to customer webstite

string

www.example.com

birthplace

customer birthplace

string

Dresden

nationality

customer nationality

string

DE

address

customer address

object (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
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:

Updating existing customer
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

Search for specific customer vs search for all customers

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:

Retrieving existing customer
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.

List all customers
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.

Deleting existing customer
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