The payment contract defines what payment methods and what additional payment methods you can use. To change something in your Contract using API you will need additional access rights for this(Currently only secupay users can delete or update a contract). Mostly you will be only allowed to get your data.

Sometimes you will get the access rights to call the method “clone” or “requestId”, which will creates new payment contracts (called sub-contract) with the same configuration of your payment contract. Then you are also allowed to get the data of your sub-contract (but not to modify them).

“clone” is when you want to create a sub-contract for yourself

“requestId” is when you want to create a sub-contract for a third party

Using the secuconnect API one can:

  • create a new contract;
  • clone contract;
  • read the contract data;
  • update an existing contract;
  • delete a contract;
  • read a list of all existing contracts.

Every API user who is able to access the payment service can read his data, and get a list of all existing contracts.

The following parameter MUST be transmitted every time a transaction is created or updated

  • project
  • contact
    • salutation
    • forename
    • surname
    • dob
    • companyname (only in case of a company)
    • address
      • street (street_number)
      • postal_code
      • city
    • email
    • phone
  • payout_account

Example

{
 "project":"project_name 2018-08-29 #000000",
 "contact":{
  "salutation":"Mr.",
  "forename":"John",
  "surname":"Doe",
  "dob":"1901-02-03",
  "address":{
   "street":"Example Street",
   "postal_code":"01234",
   "city":"Examplecity"
  },
  "email":{
   "email":"example@example.com"
  },
  "phone":{
   "phone":"0049-123-456789"
  }
 },
 "payout_account":{
  "iban":"DE89370400440532013000",
  "bic":"",
  "owner":"Test #1"
 }
}

Contract Management

// Contract management
try {
  // Init Data
  PaymentContractsDTORequestId contractRequestId = prepareContractRequestId();

  // Init API interface
  PaymentContractsApi contractsApi = new PaymentContractsApi();
  contractsApi.getApiClient().setAccessToken(accessToken);

  // Send request
  PaymentContractsRequestIdResult contractResult = contractsApi.requestId("me", contractRequestId);

  // Analyse response
  System.out.println("Contract: " + contractResult.toString());
  /*
   * Sample output:
   * ==============
   * Contract: class PaymentContractsRequestIdResult {
   *     contract: class PaymentContractsProductModel {
   *         object: payment.contracts
   *         id: PCR_WAUN605YW2MV3265N0ZAV2V2G3A2A3
   *         parent: class ProductInstanceUID {
   *             object: payment.contracts
   *             id: PCR_3YFT66NUT2MRMZSH70ZAV946082CAW
   *         }
   *         demo: true
   *         allowCloning: false
   *         sepaMandateInform: never
   *         created: 2018-11-07T17:23:39.000+01:00
   *     }
   *     apikey: 270bf4b1f4d5bf923cb4b1ef6e8c62b16377fff9
   * }
   */
} catch (ApiException e) {
  // Fetch errors
  e.printStackTrace();
  System.out.println("ERROR: " + e.getResponseBody());
  return;
}


private static PaymentContractsDTORequestId prepareContractRequestId() {
    PaymentContractsDTORequestId dto = new PaymentContractsDTORequestId();

    // Define the "contact person"
    Contact contact = new Contact();
    contact.setSalutation("Mr."); // mandatory
    contact.setTitle("Dr."); // optional
    contact.setForename("John"); // mandatory
    contact.setSurname("Doe"); // mandatory
    contact.setCompanyname("Example Inc."); // mandatory for companies
    contact.setDob("1901-02-03"); // mandatory
    contact.setEmail("example@example.com"); // mandatory
    contact.setPhone("0049-123-456789"); // mandatory

    Address address = new Address();
    address.setStreet("Example Street"); // mandatory
    address.setStreetNumber("6a"); // can be also in the street, if you have only one field one your side for this
    address.setPostalCode("01234"); // mandatory
    address.setCity("Example-City"); // mandatory
    address.setCountry("DE"); // not mandatory but highly recommended (ISO 3166-1 alpha-2)
    contact.setAddress(address);

    dto.setContact(contact);

    // Define the bank account for payout
    PaymentInformation payoutAccount = new PaymentInformation();
    payoutAccount.setOwner("John Doe");
    payoutAccount.setIban("DE37503240001000000524");
    payoutAccount.setBic("FTSBDEFAXXX"); // not mandatory for "DE" but recommended
    dto.setPayoutAccount(payoutAccount);

    // Define the "project name"
    dto.setProject("Project #" + new SimpleDateFormat("yyyy-MM-dd HH:mm:ss").format(new Date())); // MUST be unique

    return dto;
}

PaymentContractsApi

All URIs are relative to https://connect-testing.secupay-ag.de/api/v2/

Method HTTP request Description
paymentContractsGet GET Payment/Contracts GET Payment/Contracts
paymentContractsGetById GET Payment/Contracts/{id} GET Payment/Contracts/{id}
paymentContractsIdClonePost POST Payment/Contracts/{id}/clone POST Payment/Contracts/{id}/clone
paymentContractsIdDelete DELETE Payment/Contracts/{id} DELETE Payment/Contracts/{id}
paymentContractsIdPaymentMethodsGet GET Payment/Contracts/{id}/PaymentMethods GET Payment/Contracts/{id}/PaymentMethods
paymentContractsIdPut PUT Payment/Contracts/{id} PUT Payment/Contracts/{id}
paymentContractsIdRequestIdPost POST Payment/Contracts/{id}/requestId POST Payment/Contracts/{id}/requestId
paymentContractsPost POST Payment/Contracts POST Payment/Contracts

paymentContractsGet

PaymentContractsList paymentContractsGet(count, offset, fields, q, sort)

GET Payment/Contracts

Get a list of payment contracts

Example

// Import classes:
//import io.secuconnect.client.ApiClient;
//import io.secuconnect.client.ApiException;
//import io.secuconnect.client.Configuration;
//import io.secuconnect.client.auth.*;
//import io.secuconnect.client.api.PaymentContractsApi;

ApiClient defaultClient = Configuration.getDefaultApiClient();

// Configure OAuth2 access token for authorization: oauth_token
OAuth oauth_token = (OAuth) defaultClient.getAuthentication("oauth_token");
oauth_token.setAccessToken("YOUR ACCESS TOKEN");

PaymentContractsApi apiInstance = new PaymentContractsApi();
Integer count = 56; // Integer | The number of items to return.
Integer offset = 56; // Integer | The position within the whole result set to start returning items (First element is at 0).
String fields = "fields_example"; // String | List of fields to include in the result. Nested properties can be accessed with this notation: prop1.prop2  Example: prop3,prop1.prop2
String q = "q_example"; // String | A query string to restrict the returned items to given conditions. The query string must consist of any combination of single expressions in the form property:condition.  *                  A condition may contain:  *                      - wildcard \"*\" for any number of characters  *                      - wildcard \"?\" for one character  *                      - ranges in the form [value TO value]  *  *                  Single expressions may combined by 'AND', 'OR', 'NOT' operators and parenthesis '(', ')' for grouping.  *                  Property names can be nested like \"prop1.prop2\".  *                  Example: (NOT customer.name:meier*) AND (customer.age:[30 TO 40] OR customer.age:[50 TO 60])  *
String sort = "sort_example"; // String | String with comma separated pairs of field:order (e.g. contact.surname:asc,contact.comapnyname:desc). Result set will be sorted by included fields, in ascending 'asc', or descending 'dsc' order.
try {
    PaymentContractsList result = apiInstance.paymentContractsGet(count, offset, fields, q, sort);
    System.out.println(result);
} catch (ApiException e) {
    System.err.println("Exception when calling PaymentContractsApi#paymentContractsGet");
    e.printStackTrace();
}

Parameters

Name Type Description Notes
count Integer The number of items to return. [optional]
offset Integer The position within the whole result set to start returning items (First element is at 0). [optional]
fields String List of fields to include in the result. Nested properties can be accessed with this notation: prop1.prop2 Example: prop3,prop1.prop2 [optional]
q String A query string to restrict the returned items to given conditions. The query string must consist of any combination of single expressions in the form property:condition. A condition may contain: - wildcard \"\" for any number of characters - wildcard \"?\" for one character - ranges in the form [value TO value] Single expressions may combined by 'AND', 'OR', 'NOT' operators and parenthesis '(', ')' for grouping. Property names can be nested like \"prop1.prop2\". Example: (NOT customer.name:meier) AND (customer.age:[30 TO 40] OR customer.age:[50 TO 60]) * [optional]
sort String String with comma separated pairs of field:order (e.g. contact.surname:asc,contact.comapnyname:desc). Result set will be sorted by included fields, in ascending 'asc', or descending 'dsc' order. [optional]

Return type

PaymentContractsList

Properties

Name Type Description Notes
count Integer Number of existing payment contracts [optional]
data List<PaymentContractsProductModel> GET Payment/Contracts [optional]

Authorization

oauth_token

HTTP request headers

  • Content-Type: Not defined
  • Accept: Not defined

paymentContractsGetById

PaymentContractsProductModel paymentContractsGetById(id)

GET Payment/Contracts/{id}

Get all payment contracts

Example

// Import classes:
//import io.secuconnect.client.ApiClient;
//import io.secuconnect.client.ApiException;
//import io.secuconnect.client.Configuration;
//import io.secuconnect.client.auth.*;
//import io.secuconnect.client.api.PaymentContractsApi;

ApiClient defaultClient = Configuration.getDefaultApiClient();

// Configure OAuth2 access token for authorization: oauth_token
OAuth oauth_token = (OAuth) defaultClient.getAuthentication("oauth_token");
oauth_token.setAccessToken("YOUR ACCESS TOKEN");

PaymentContractsApi apiInstance = new PaymentContractsApi();
String id = "id_example"; // String | Search one by provided id
try {
    PaymentContractsProductModel result = apiInstance.paymentContractsGetById(id);
    System.out.println(result);
} catch (ApiException e) {
    System.err.println("Exception when calling PaymentContractsApi#paymentContractsGetById");
    e.printStackTrace();
}

Parameters

Name Type Description Notes
id String Search one by provided id

Return type

PaymentContractsProductModel

Authorization

oauth_token

HTTP request headers

  • Content-Type: Not defined
  • Accept: Not defined

paymentContractsIdClonePost

PaymentContractsProductModel paymentContractsIdClonePost(id)

POST Payment/Contracts/{id}/clone

Clone an existing payment contract

Example

// Import classes:
//import io.secuconnect.client.ApiClient;
//import io.secuconnect.client.ApiException;
//import io.secuconnect.client.Configuration;
//import io.secuconnect.client.auth.*;
//import io.secuconnect.client.api.PaymentContractsApi;

ApiClient defaultClient = Configuration.getDefaultApiClient();

// Configure OAuth2 access token for authorization: oauth_token
OAuth oauth_token = (OAuth) defaultClient.getAuthentication("oauth_token");
oauth_token.setAccessToken("YOUR ACCESS TOKEN");

PaymentContractsApi apiInstance = new PaymentContractsApi();
String id = "id_example"; // String | Contract identifier
try {
    PaymentContractsProductModel result = apiInstance.paymentContractsIdClonePost(id);
    System.out.println(result);
} catch (ApiException e) {
    System.err.println("Exception when calling PaymentContractsApi#paymentContractsIdClonePost");
    e.printStackTrace();
}

Parameters

Name Type Description Notes
id String Contract identifier

Return type

PaymentContractsProductModel

Authorization

oauth_token

HTTP request headers

  • Content-Type: Not defined
  • Accept: Not defined

paymentContractsIdDelete

List<PaymentContractsProductModel> paymentContractsIdDelete(id)

DELETE Payment/Contracts/{id}

Delete payment contract

Example

// Import classes:
//import io.secuconnect.client.ApiClient;
//import io.secuconnect.client.ApiException;
//import io.secuconnect.client.Configuration;
//import io.secuconnect.client.auth.*;
//import io.secuconnect.client.api.PaymentContractsApi;

ApiClient defaultClient = Configuration.getDefaultApiClient();

// Configure OAuth2 access token for authorization: oauth_token
OAuth oauth_token = (OAuth) defaultClient.getAuthentication("oauth_token");
oauth_token.setAccessToken("YOUR ACCESS TOKEN");

PaymentContractsApi apiInstance = new PaymentContractsApi();
String id = "id_example"; // String | Payment contract id
try {
    List<PaymentContractsProductModel> result = apiInstance.paymentContractsIdDelete(id);
    System.out.println(result);
} catch (ApiException e) {
    System.err.println("Exception when calling PaymentContractsApi#paymentContractsIdDelete");
    e.printStackTrace();
}

Parameters

Name Type Description Notes
id String Payment contract id

Return type

List<PaymentContractsProductModel>

Authorization

oauth_token

HTTP request headers

  • Content-Type: Not defined
  • Accept: Not defined

paymentContractsIdPaymentMethodsGet

List<String> paymentContractsIdPaymentMethodsGet(id)

GET Payment/Contracts/{id}/PaymentMethods

Get available payment methods for given contract

Example

// Import classes:
//import io.secuconnect.client.ApiClient;
//import io.secuconnect.client.ApiException;
//import io.secuconnect.client.Configuration;
//import io.secuconnect.client.auth.*;
//import io.secuconnect.client.api.PaymentContractsApi;

ApiClient defaultClient = Configuration.getDefaultApiClient();

// Configure OAuth2 access token for authorization: oauth_token
OAuth oauth_token = (OAuth) defaultClient.getAuthentication("oauth_token");
oauth_token.setAccessToken("YOUR ACCESS TOKEN");

PaymentContractsApi apiInstance = new PaymentContractsApi();
String id = "id_example"; // String | Contract identifier
try {
    List<String> result = apiInstance.paymentContractsIdPaymentMethodsGet(id);
    System.out.println(result);
} catch (ApiException e) {
    System.err.println("Exception when calling PaymentContractsApi#paymentContractsIdPaymentMethodsGet");
    e.printStackTrace();
}

Parameters

Name Type Description Notes
id String Contract identifier

Return type

List<String>

Authorization

oauth_token

HTTP request headers

  • Content-Type: Not defined
  • Accept: Not defined

paymentContractsIdPut

PaymentContractsProductModel paymentContractsIdPut(id, body)

PUT Payment/Contracts/{id}

Update payment contract

Example

// Import classes:
//import io.secuconnect.client.ApiClient;
//import io.secuconnect.client.ApiException;
//import io.secuconnect.client.Configuration;
//import io.secuconnect.client.auth.*;
//import io.secuconnect.client.api.PaymentContractsApi;

ApiClient defaultClient = Configuration.getDefaultApiClient();

// Configure OAuth2 access token for authorization: oauth_token
OAuth oauth_token = (OAuth) defaultClient.getAuthentication("oauth_token");
oauth_token.setAccessToken("YOUR ACCESS TOKEN");

PaymentContractsApi apiInstance = new PaymentContractsApi();
String id = "id_example"; // String | Payment contract id
PaymentContractsDTO body = new PaymentContractsDTO(); // PaymentContractsDTO | Payment contract properties
try {
    PaymentContractsProductModel result = apiInstance.paymentContractsIdPut(id, body);
    System.out.println(result);
} catch (ApiException e) {
    System.err.println("Exception when calling PaymentContractsApi#paymentContractsIdPut");
    e.printStackTrace();
}

Parameters

Name Type Description Notes
id String Payment contract id
body PaymentContractsDTO Payment contract properties

Return type

PaymentContractsProductModel

Authorization

oauth_token

HTTP request headers

  • Content-Type: Not defined
  • Accept: Not defined

paymentContractsIdRequestIdPost

PaymentContractsRequestIdResult paymentContractsIdRequestIdPost(id)

POST Payment/Contracts/{id}/requestId

This method clones your payment contract, so that you can use this to separate the merchants of your marketplace. (Needs to be activated))

Example

// Import classes:
//import io.secuconnect.client.ApiClient;
//import io.secuconnect.client.ApiException;
//import io.secuconnect.client.Configuration;
//import io.secuconnect.client.auth.*;
//import io.secuconnect.client.api.PaymentContractsApi;

ApiClient defaultClient = Configuration.getDefaultApiClient();

// Configure OAuth2 access token for authorization: oauth_token
OAuth oauth_token = (OAuth) defaultClient.getAuthentication("oauth_token");
oauth_token.setAccessToken("YOUR ACCESS TOKEN");

PaymentContractsApi apiInstance = new PaymentContractsApi();
String id = "id_example"; // String | Contract identifier
try {
    PaymentContractsRequestIdResult result = apiInstance.paymentContractsIdRequestIdPost(id);
    System.out.println(result);
} catch (ApiException e) {
    System.err.println("Exception when calling PaymentContractsApi#paymentContractsIdRequestIdPost");
    e.printStackTrace();
}

Parameters

Name Type Description Notes
id String Contract identifier

Return type

PaymentContractsRequestIdResult

Properties

Name Type Description Notes
contract PaymentContractsProductModel The payment contract object [optional]
apikey String Returns the apikey of the created merchant [optional]
payingAccount PaymentContractsRequestIdResultPayingAccount [optional]

Authorization

oauth_token

HTTP request headers

  • Content-Type: Not defined
  • Accept: Not defined

paymentContractsPost

PaymentContractsProductModel paymentContractsPost(body)

POST Payment/Contracts

Add new contract

Example

// Import classes:
//import io.secuconnect.client.ApiClient;
//import io.secuconnect.client.ApiException;
//import io.secuconnect.client.Configuration;
//import io.secuconnect.client.auth.*;
//import io.secuconnect.client.api.PaymentContractsApi;

ApiClient defaultClient = Configuration.getDefaultApiClient();

// Configure OAuth2 access token for authorization: oauth_token
OAuth oauth_token = (OAuth) defaultClient.getAuthentication("oauth_token");
oauth_token.setAccessToken("YOUR ACCESS TOKEN");

PaymentContractsApi apiInstance = new PaymentContractsApi();
PaymentContractsDTO body = new PaymentContractsDTO(); // PaymentContractsDTO | Payment contracts properties
try {
    PaymentContractsProductModel result = apiInstance.paymentContractsPost(body);
    System.out.println(result);
} catch (ApiException e) {
    System.err.println("Exception when calling PaymentContractsApi#paymentContractsPost");
    e.printStackTrace();
}

Parameters

Name Type Description Notes
body PaymentContractsDTO Payment contracts properties

Return type

PaymentContractsProductModel

Authorization

oauth_token

HTTP request headers

  • Content-Type: Not defined
  • Accept: Not defined