Integration Guide for Payment (secuconnect API + custom checkout)

Introduction

This guide shows how you can use the secuconnect API in order to implement your own checkout or payment process. This is the most flexible way for you, and integrates seamlessly with your e-commerce application. If you want to safe the effort, you can also use our secupay Smart Checkout or even our ready-to-use shop modules for many popular shop systems. Please do not hesitate to ask our sales team or help desk for their assistance. You are very welcome!

The integration guide begins with a Getting Started section, that explains the basic concepts and important key terms. In this section, you will learn how to create a first order and start the Payment Wizard. We recommend to study the Getting Started section thoroughly. The remaining sections, Reference and Troubleshooting can be accessed when needed. Should you require assistance with integration or further order processing, our support staff will be happy to help.

Getting Started

Key Terms

Merchant and Contract

The merchant sells products to the customer or offers a service. Thus he delivers something and receives the payment for it. As payment service provider (PSP), secupay cares for the payment and interacts with both, the merchant and his customer.

Every merchant can have one or more contracts with secupay for different purposes. These contracts are managed behind the scenes for you. Important for you: Yuo will receive one or more contract IDs (GCR_xxx), and some information for which purpose you shall use them.

Smart Transaction and Payment Transaction

A Payment Transaction manages the payment process between secupay and your customer as well as between secupay and you, the merchant. It is defined by the payer and the payee, the payment method and the amount.

A Smart Transaction is rather a business transaction like a purchase order. It knows about the status of the payment, and manages delivery and the like. The Payment Transaction is managed by the Smart Transaction, and associated to it.

General Workflow

The basic workflow is this:

  1. create a Smart Transaction, and set the customer;

  2. authorize the payment for this Smart Transaction (only needed for direct debit, credit card, PayPal; optional possible for invoice);

  3. start the Smart Transaction;

  4. perform a Sofort payment for the Smart Transaction (only if Sofort).

So the shortest flow is for invoice payment or advance payment. You only need to create the Smart Transaction, and to start it. The "start" marks the contract closure.

Example

In our example we will:

  1. Authenticate against the secuconnect API

  2. Create a Payment Customer

  3. Create a Smart Transaction

  4. Authorize the Smart Transaction for Invoice Payment (/prepare/invoice)

  5. Start the Smart Transaction (/start)

The transaction shall use the sale workflow and the demo mode. In demo mode, the payment is not really executed.

The last two steps can be combined into /start/invoice, but you will learn more, if you see both steps.

Step 1: Authenticate Against secuconnect API

Most API calls require authentication. The secuconnect API uses the OAuth 2.0 protocol for authentication. The OAuth service checks your credentials, and hands an access token over to you. It grants you access to the API for a limited period of time. The client must pass this token with all subsequent API calls.

The endpoint for OAuth authorization is POST https://connect.secucard.com/ oauth/token.

Example request:

POST /oauth/token HTTP/1.1
Host: connect.secucard.com
Content-Type: application/x-www-form-urlencoded
Content-Length: 151
 
grand_type=client_credentials&client_id=129b362607f87990bdf5589a0be3a04d&client_secret=31e991b25b7896a3fad567507f7eb38feaef9329657a4a8cd30fbe6eecf5f50b

Successful response:

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 132
...
 
{
"access_token": "qb56tjj1bcvo9n2nj4u38k84lo",
"expires_in": 1200,
"token_type": "bearer",
"scope": "https://scope.secucard.com/e/api"
}

The returned access token is valid for as many seconds as signalised in the expires_in field (line 8). You need to pass the received token (line 7) in an HTTP request header Authenticate: Bearer qb56tjj1bcvo9n2nj4u38k84lo of the subsequent calls.

Usually, direct usage of HTTPS is not necessary, but for can be useful for debugging and to understand the SDK.

The corresponding example using the secuconnect PHP SDK:

use \Secuconnect\Client\Configuration;
use \Secuconnect\Client\Authenticator;
use \Secuconnect\Client\OauthCredentials;
 
// Optionally you can configure a PSR-6 compliant cache
Configuration::getDefaultConfiguration()->setCache($cache);
 
// Create an authenticator object with OAuth authentication and obtains token
$auth = new Authenticator(OauthClientCredentials::from($clientId, $clientSecret));
$accessToken = $auth->getToken();
 
// Saves the token to the default client configuration
Configuration::getDefaultConfiguration()->setAccessToken($accessToken);

We provide SDKs for PHP, Java, NodeJS, and .NET free of charge.

Step 2: Create Payment Customer

The API endpoint to create a Smart Transaction is POST https://connect.secucard.com/api/v2/Payment/Customers.

Example request:

POST /api/v2/Payment/Customers HTTP/1.1
Host: connect.secucard.com
Content-Type: application/json
Authorization: Bearer qb56tjj1bcvo9n2nj4u38k84lo
...
 
{
"contact": {
"salutation": "Mr.",
"forename": "Max",
"surname": "Mustermann",
"address": {
"street": "Max-Muster-Str.",
"street_number": "25a",
"postal_code": "09555",
"city": "Musterstadt",
"country": "DE",
"additional_address_data": "Whg. 202"
},
"email": "mmustermann@example.net",
"mobile": "+49 177 5555555",
"phone": "+49 555 5555555"
}
}

Successful response:

HTTP/1.1 200 OK
Content-Type: application/json
...
 
{
"object": "payment.customers",
"id": "PCU_38RG7MHRE2NJTPFMXRYQP3NKW6GVAZ",
"merchant": {
"object": "general.merchants",
"id": "MRC_DNUWH3RE6J6TNRGW0X607S294W0XO3"
},
"contact": {
"salutation": "Mr.",
"forename": "Max",
"surname": "Mustermann",
"address": {
"street": "Max-Muster-Str.",
"street_number": "25a",
"postal_code": "09555",
"city": "Musterstadt",
"country": "DE",
"additional_address_data": "Whg. 202"
},
"email": "mmustermann@example.net",
"mobile": "+49 177 5555555",
"phone": "+49 555 5555555"
}
}

The most important field is id. It identifies this single customer, and you need it to create the Smart Transaction.

Step 3: Create a Smart Transaction

The API endpoint to create a Smart Transaction is POST https://connect.secucard.com/api/v2/Payment/Customers.

Example request:

POST /api/v2/Payment/Customers HTTP/1.1
Host: connect.secucard.com
Content-Type: application/json
Authorization: Bearer qb56tjj1bcvo9n2nj4u38k84lo
...
 
{
"contact": {
"salutation": "Mr.",
"forename": "Max",
"surname": "Mustermann",
"address": {
"street": "Max-Muster-Str.",
"street_number": "25a",
"postal_code": "09555",
"city": "Musterstadt",
"country": "DE",
"additional_address_data": "Whg. 202"
},
"email": "mmustermann@example.net",
"mobile": "+49 177 5555555",
"phone": "+49 555 5555555"
}
}

Successful response:

HTTP/1.1 200 OK
Content-Type: application/json
...
 
{
"object": "payment.customers",
"id": "PCU_38RG7MHRE2NJTPFMXRYQP3NKW6GVAZ",
"merchant": {
"object": "general.merchants",
"id": "MRC_DNUWH3RE6J6TNRGW0X607S294W0XO3"
},
"contact": {
"salutation": "Mr.",
"forename": "Max",
"surname": "Mustermann",
"address": {
"street": "Max-Muster-Str.",
"street_number": "25a",
"postal_code": "09555",
"city": "Musterstadt",
"country": "DE",
"additional_address_data": "Whg. 202"
},
"email": "mmustermann@example.net",
"mobile": "+49 177 5555555",
"phone": "+49 555 5555555"
}
}

The most important field is id. It identifies this single customer, and you need it to create the Smart Transaction.

Some fields in application context may be irrelevant in your case. Others may be useful.

Step 4: Authorize for Invoice Payment

In order to authorize the Smart Transaction for invoice payment, you only need to call POST Smart/Transactions/STX_xxx/prepare/invoice.

If not passed before, you can pass the customer a last time. This request will cause the customer scoring, and wil set the STX to approved if everything is fine.

Example request:

POST /api/v2/Smart/Transactions/STX_xxx/prepare/invoice HTTP/1.1
Host: connect.secucard.com
Content-Type: application/json
Authorization: Bearer qb56tjj1bcvo9n2nj4u38k84lo
 
{
"customer": {
"id": "PCU_2YK9WTXAS2NK46QAD3H58BAEZQCWA2"
}
}

Successful response:

Example Request Prepare
HTTP/1.1 200 OK
Content-Type: application/json
...
{
"object": "smart.transactions",
"id": "STX_33PXAW2YN2NJTPM5KPGMK7QF5PBVA2",
// ...
"customer": {
"object": "payment.customers",
"id": "PCU_38RG7MHRE2NJTPFMXRYQP3NKW6GVAZ",
"contact": {
"forename": "Max",
"surname": "Mustermann",
"name": "Max Mustermann",
"salutation": "Mr.",
"address": {
"street": "Max-Muster-Str.",
"street_number": "25a",
"additional_address_data": "Whg. 202",
"postal_code": "09555",
"city": "Musterstadt",
"country": "DE"
},
"email": "mmustermann@example.net",
"mobile": "+491775555555",
"phone": "+495555555555"
}
},
"transactions": [
{
"object": "payment.transactions",
"id": "MRC_FDBREW9ZS7P6FTN4ZY2ATC6NK0QWO7",
// ...
}
],
"created": "2020-03-27T10:55:23+01:00",
"status": "approved",
// ...
"application_context": {
"return_urls": {
"url_success": "https://www.example.org/SUCCESS",
"url_error": "https://www.example.org/FAILURE",
"url_abort": "https://www.example.org/FAILURE"
}
},
"checkout_links": null,
"payment_links": {
"creditcard": "https://checkout.secupay.com?initPaymentMethod=Creditcard&stx=STX_33PXAW2YN2NJTPM5KPGMK7QF5PBVA2",
"debit": "https://checkout.secupay.com?initPaymentMethod=Debit&stx=STX_33PXAW2YN2NJTPM5KPGMK7QF5PBVA2",
"invoice": "https://checkout.secupay.com?initPaymentMethod=Invoice&stx=STX_33PXAW2YN2NJTPM5KPGMK7QF5PBVA2",
"prepaid": "https://checkout.secupay.com?initPaymentMethod=Prepay&stx=STX_33PXAW2YN2NJTPM5KPGMK7QF5PBVA2",
"general": "https://checkout.secupay.com?stx=STX_33PXAW2YN2NJTPM5KPGMK7QF5PBVA2"
}
}

Step 5: Start Smart Transaction

In order to start the authorized Smart Transaction, you only need to call POST Smart/Transactions/STX_xxx/start. When successful, the status changes to ok. (It would differ if you used "intent": "order".)

Example request:

POST /api/v2/Smart/Transactions/STX_xxx/start HTTP/1.1
Host: connect.secucard.com
Content-Type: application/json
Authorization: Bearer qb56tjj1bcvo9n2nj4u38k84lo
 
{
}

Successful response:

Example Response Prepare
HTTP/1.1 200 OK
Content-Type: application/json
...
{
"object": "smart.transactions",
"id": "STX_33PXAW2YN2NJTPM5KPGMK7QF5PBVA2",
// ...
"transactions": [
{
"object": "payment.transactions",
"id": "PCI_FDBREW9ZS7P6FTN4ZY2ATC6NK0QWO7",
// ...
}
],
"created": "2020-03-27T10:55:23+01:00",
"status": "ok",
// ...
"application_context": {
"return_urls": {
"url_success": "https://www.example.org/SUCCESS",
"url_error": "https://www.example.org/FAILURE",
"url_abort": "https://www.example.org/FAILURE"
}
},
"checkout_links": null,
"payment_links": {
"creditcard": null
"debit": null
"invoice": null
"prepaid": null
"general": null
}
}

Summary

You have seen how to integrate our Payment Wizard with your application using our secuconnect API. We have created a Payment Customer and a Smart Transaction, and started the Smart Trasnaction with payment method invoice.

Furthermore you can:

  • use many more payment methods;

  • add a basket and shipping information;

  • reuse customer data and payment instruments;

  • cancel a transaction before or even after the payment is executed;

  • let our secuconnect SDKs assemble and parse requests and responses.

Some of the mentioned things are described in the Reference section below. If you don't find the needed information, please do not hesitate to ask us.

Reference

Advance Payment (Prepaid)

In order to start an advance payment, you simply need to call POST /Smart/Transaction/STX_xxx/start/prepaid.

Example request:

POST /api/v2/Smart/Transactions/STX_xxx/start/prepaid HTTP/1.1
Host: connect.secucard.com
Content-Type: application/json
Authorization: Bearer qb56tjj1bcvo9n2nj4u38k84lo
 
{
}

Successful response:

Example Response Prepare
HTTP/1.1 200 OK
Content-Type: application/json
...
{
"object": "smart.transactions",
"id": "STX_33PXAW2YN2NJTPM5KPGMK7QF5PBVA2",
// ...
"transactions": [
{
"object": "payment.transactions",
"id": "PCI_FDBREW9ZS7P6FTN4ZY2ATC6NK0QWO7",
// ...
}
],
"created": "2020-03-27T10:55:23+01:00",
"status": "pending",
// ...
"application_context": {
"return_urls": {
"url_success": "https://www.example.org/SUCCESS",
"url_error": "https://www.example.org/FAILURE",
"url_abort": "https://www.example.org/FAILURE"
}
},
"checkout_links": null,
"payment_links": {
"creditcard": null
"debit": null
"invoice": null
"prepaid": null
"general": null
}
}

A Smart Transaction started with advance payment will change into status pending to signalize that we still wait for the payment. When the payment has arrived, it switches to ok.

Invoice Payment

In order to start an invoice payment, you can one use one or two steps. The two-step solution with separate authorization is shown in the example in the Getting Started section. To do it in one step, you need to call POST /Smart/Transaction/STX_xxx/start/invoice.

Example request:

POST /api/v2/Smart/Transactions/STX_xxx/start/invoice HTTP/1.1
Host: connect.secucard.com
Content-Type: application/json
Authorization: Bearer qb56tjj1bcvo9n2nj4u38k84lo
 
{
}

Successful response:

Example Response Prepare
HTTP/1.1 200 OK
Content-Type: application/json
...
{
"object": "smart.transactions",
"id": "STX_33PXAW2YN2NJTPM5KPGMK7QF5PBVA2",
// ...
"transactions": [
{
"object": "payment.transactions",
"id": "PCI_FDBREW9ZS7P6FTN4ZY2ATC6NK0QWO7",
// ...
}
],
"created": "2020-03-27T10:55:23+01:00",
"status": "ok",
// ...
"application_context": {
"return_urls": {
"url_success": "https://www.example.org/SUCCESS",
"url_error": "https://www.example.org/FAILURE",
"url_abort": "https://www.example.org/FAILURE"
}
},
"checkout_links": null,
"payment_links": {
"creditcard": null
"debit": null
"invoice": null
"prepaid": null
"general": null
}
}

A Smart Transaction started with invoice payment will change into status ok. If you use the intent order, it will change to status received or collection, depending on the actual delivery method.

SEPA Direct Debit Payment

In order to start an direct debit payment, you need to take three steps:

  1. create a Payment Container for the bank account;

  2. prepare the Smart Transaction for direct debit payment using theis container;

  3. start the the Smart Transaction.

Step 1: Create the Payment Container

The Payment Container is created using POST /Payment/Containers. It must belong to the customer you are using.

Example request:

POST /api/v2/Payment/Containers HTTP/1.1
Host: connect.secucard.com
Content-Type: application/json
Authorization: Bearer qb56tjj1bcvo9n2nj4u38k84lo
 
{
"type": "bank_account",
"private": {
"owner": "John Doe",
"iban": "DE12500105170648489890",
"bic": "ABCDDE12XXX"
},
"customer": {
"id": "PCU_WGRRF2BU82N9ES6670ZAV6KXJ0KNAH"
}
}

Successful response:

HTTP/1.1 200 OK
Content-Type: application/json
...
 
{
"id": "PCT_J0KNRWG67AV66AHKXRF2BU82N90ZES",
"object": "payment.containers",
"type": "bank_account",
"private": {
"owner": "Max Mustermann",
"iban": "DE12500105170648489890",
"bic": "ABCDDE12XXX"
},
"customer": {
"object": "payment.customers",
"id": "PCU_2YK9WTXAS2NK46QAD3H58BAEZQCWA2"
}
}

You need to remember the container id. You need to pass it later.

Step 2: Prepare the Smart Transaction

In order to authorize the Smart Transaction for direct debit payment, you need to call POST Smart/Transactions/STX_xxx/prepare/debit and pass the Payment Container.

If not passed before, you can pass the customer a last time. This request will cause the customer scoring, and wil set the STX to approved if everything is fine.

Example request:

POST /api/v2/Smart/Transactions/STX_xxx/prepare/debit HTTP/1.1
Host: connect.secucard.com
Content-Type: application/json
Authorization: Bearer qb56tjj1bcvo9n2nj4u38k84lo
 
{
"container": {
"id": "PCT_J0KNRWG67AV66AHKXRF2BU82N90ZES"
},
"customer": {
"id": "PCU_2YK9WTXAS2NK46QAD3H58BAEZQCWA2"
}
}

Successful response:

Example Request Prepare
HTTP/1.1 200 OK
Content-Type: application/json
...
{
"object": "smart.transactions",
"id": "STX_33PXAW2YN2NJTPM5KPGMK7QF5PBVA2",
// ...
"customer": {
"object": "payment.customers",
"id": "PCU_38RG7MHRE2NJTPFMXRYQP3NKW6GVAZ",
"contact": {
"forename": "Max",
"surname": "Mustermann",
"name": "Max Mustermann",
"salutation": "Mr.",
"address": {
"street": "Max-Muster-Str.",
"street_number": "25a",
"additional_address_data": "Whg. 202",
"postal_code": "09555",
"city": "Musterstadt",
"country": "DE"
},
"email": "mmustermann@example.net",
"mobile": "+491775555555",
"phone": "+495555555555"
}
},
"transactions": [
{
"object": "payment.transactions",
"id": "PCI_FDBREW9ZS7P6FTN4ZY2ATC6NK0QWO7",
// ...
}
],
"created": "2020-03-27T10:55:23+01:00",
"status": "approved",
// ...
"application_context": {
"return_urls": {
"url_success": "https://www.example.org/SUCCESS",
"url_error": "https://www.example.org/FAILURE",
"url_abort": "https://www.example.org/FAILURE"
}
},
"checkout_links": null,
"payment_links": {
"creditcard": "https://checkout.secupay.com?initPaymentMethod=Creditcard&stx=STX_33PXAW2YN2NJTPM5KPGMK7QF5PBVA2",
"debit": "https://checkout.secupay.com?initPaymentMethod=Debit&stx=STX_33PXAW2YN2NJTPM5KPGMK7QF5PBVA2",
"invoice": "https://checkout.secupay.com?initPaymentMethod=Invoice&stx=STX_33PXAW2YN2NJTPM5KPGMK7QF5PBVA2",
"prepaid": "https://checkout.secupay.com?initPaymentMethod=Prepay&stx=STX_33PXAW2YN2NJTPM5KPGMK7QF5PBVA2",
"general": "https://checkout.secupay.com?stx=STX_33PXAW2YN2NJTPM5KPGMK7QF5PBVA2"
}
}

Step 3: Start the Smart Transaction

In order to start the authorized Smart Transaction, you only need to call POST Smart/Transactions/STX_xxx/start. When successful, the status changes to ok. (It would differ if you used "intent": "order".)

Example request:

POST /api/v2/Smart/Transactions/STX_xxx/start HTTP/1.1
Host: connect.secucard.com
Content-Type: application/json
Authorization: Bearer qb56tjj1bcvo9n2nj4u38k84lo
 
{
}

Successful response:

Example Response Prepare
HTTP/1.1 200 OK
Content-Type: application/json
...
 
{
"object": "smart.transactions",
"id": "STX_33PXAW2YN2NJTPM5KPGMK7QF5PBVA2",
// ...
"transactions": [
{
"object": "payment.transactions",
"id": "MRC_FDBREW9ZS7P6FTN4ZY2ATC6NK0QWO7",
// ...
}
],
"created": "2020-03-27T10:55:23+01:00",
"status": "ok",
// ...
"application_context": {
"return_urls": {
"url_success": "https://www.example.org/SUCCESS",
"url_error": "https://www.example.org/FAILURE",
"url_abort": "https://www.example.org/FAILURE"
}
},
"checkout_links": null,
"payment_links": {
"creditcard": null
"debit": null
"invoice": null
"prepaid": null
"general": null
}
}

After successful start, the status of the Smart Transaction changes to ok. In some cases it wil chnge to pending first, and you have to wait with the delivery until we change it to ok.

Credit Card Payment

To integrate credit card payment into your custom checkout you need to use the credit card iframe by secupay ( https://cc.secupay.com/ ). The platform page contains a CTA button to proceed and start the communication with the secuconnect API using a backend system.

images/download/attachments/81133880/STX_Credit_card_to_payment_container.png

Frontend Integration

Inetgration example

<!doctype html>
<html>
<head>
<!-- ... -->
</head>
<body>
<iframe id="iframe" src="https://cc.secupay.com" style="width: 100%; height: 400px;"></iframe>
<form>
<button id="submit-button" type="button">confirm</button>
</form>
<script>
 
// Assign handler for "iframe is ready" event
window.addEventListener('load', handleInit, false);
 
// Assign handler for "receiving encrypted credit card data"
window.addEventListener('message', handleCC, false);
 
// Add click event for the submit button
document.getElementById('submit-button').addEventListener('click', handleSubmitButton);
 
/**
* Handle submit button
*/
function handleSubmitButton() {
var iframe = document.getElementById('iframe').contentWindow;
iframe.postMessage({ action: "get-cc-data" }, 'https://cc.secupay.com');
}
 
/**
* Handle "receiving encrypted credit card data"
* @param e
*/
function handleCC(e) {
// Logging
console.log('Caught ', e.type, ' origin ', e.origin, ' with data ', e.data, '. Full details: ', e);
 
// Check origin
if (e.origin !== 'https://cc.secupay.com') {
return;
}
 
// Check action name
if (e.data.action !== 'prepared-cc-data') {
return;
}
}
 
/**
* Handle "iframe is ready" event
* @param e
*/
function handleInit(e) {
// Logging
console.log('Caught ', e.type, ' origin ', e.origin, ' with data ', e.data, '. Full details: ', e);
 
// Set owner (optional)
var iframe = document.getElementById('iframe').contentWindow;
iframe.postMessage(
{
action: "set-owner",
owner: "Test 123"
},
'https://cc.secupay.com'
);
 
// Set language (optional)
iframe.postMessage(
{
action: "set-lang",
lang: "en"
},
'https://cc.secupay.com'
);
}
</script>
</body>
</html>

The handlerCC() method receives in e.data a structure like this:

{
owner: {
value: "Max Mustermann",
isValid: true,
errorMessage: ""
},
cardNumber: {
value: "4111xxxxxxxx1111",
company: "VISA",
isValid: true,
errorMessage: ""
},
yearExp: {
value: "2022",
isValid: true,
errorMessage: ""
},
monthExp: {
value: "3",
isValid: true,
errorMessage: ""
},
encrptedData: // ...
}

You will never receive the plain PAN, but only a truncated one. And you will not receive the CVC code.

Step 1: Create Payment Container

Endpoint: POST Payment/Containers

POST /Containers HTTP/1.1
Host: https://connect-testing.secupay-ag.de/api/v2/Payment
Accept: application/json
Content-Type: application/json
Accept-Charset: utf-8
Authorization: Bearer ...
 
{
"type": "credit_card",
"customer": {
"id": "PCU_W4...",
},
"private": {
"owner": "Max Mustermann",
"pan": "4111xxxxxxxx1111",
"expiration_date": "2022-03-31T23:59:59+00:00",
"issuer": "VISA",
// ...
}
}

Mapping:

Frontend

Backend

data.encryptedData.masked.card_owner

private.owner

data.encryptedData.masked.card_number

private.pan

data.yearExp + data.monthExp

private.expiration_date

data.cardNumber.company

private.issuer

data.encryptedData.crypted_container

private.transact_container

data.encryptedData.crypted_skey

private.transact_skey_pubkey

data.encryptedData.key_filename

private.transact_skey_keyname

data.encryptedData.container_hash

private.transact_hash

Step 2: Prepare the Smart Transaction

Without 3-D Secure:

// Add customer and add payment method
SmartTransactionsPrepare prepareDTO = new SmartTransactionsPrepare();
 
prepareDTO.setCustomer(new ProductInstanceUID());
prepareDTO.getCustomer().setId("PCU_26XTQN8592ND77D0D3H58A2DKE5AA4");
prepareDTO.getCustomer().setObject("payment.customers");
 
prepareDTO.setContainer(new ProductInstanceUID());
prepareDTO.getContainer().setId("PCT_PF8DJZADN2NZUZ6TSQVQV7XKHA9QA2");
prepareDTO.getContainer().setObject("payment.containers");
prepareDTO.setCallbackUrls(new SmartTransactionsPrepareCallbackUrls());
 
prepareDTO.getCallbackUrls().setSuccessUrl("https://connect-testing.secupay-ag.de/connect/testJsonPush/");
prepareDTO.getCallbackUrls().setFailureUrl("https://connect-testing.secupay-ag.de/connect/testJsonPush/");
 
SmartTransactionsProductModel preparedTransaction = api.prepare(createdTransaction.getId(), "creditcard", prepareDTO);

With 3-D Secure you need additional return URLs:

// Add customer and add payment method
SmartTransactionsPrepare prepareDTO = new SmartTransactionsPrepare();
 
prepareDTO.setCustomer(new ProductInstanceUID());
prepareDTO.getCustomer().setId("PCU_26XTQN8592ND77D0D3H58A2DKE5AA4");
prepareDTO.getCustomer().setObject("payment.customers");
 
prepareDTO.setContainer(new ProductInstanceUID());
prepareDTO.getContainer().setId("PCT_PF8DJZADN2NZUZ6TSQVQV7XKHA9QA2");
prepareDTO.getContainer().setObject("payment.containers");
prepareDTO.setCallbackUrls(new SmartTransactionsPrepareCallbackUrls());
 
prepareDTO.getCallbackUrls().setSuccessUrl("https://connect-testing.secupay-ag.de/connect/testJsonPush/");
prepareDTO.getCallbackUrls().setFailureUrl("https://connect-testing.secupay-ag.de/connect/testJsonPush/");
 
SmartTransactionsProductModel preparedTransaction = api.prepare(createdTransaction.getId(), "creditcard", prepareDTO);
 
// Iframe URL is only returned, if 3-D Secure check is needed
if (preparedTransaction.getIframeUrl() != null) {
System.out.print("\n\n\nopen this url in browser: " + preparedTransaction.getIframeUrl());
return;
}

Step 3: Start the Smart Transaction

Whetehr 3-D Secure or not, you need to call this in Java:

// Complete transaction
SmartTransactionsProductModel startedTransaction = api.startTransaction(preparedTransaction.getId(), ""); // payment method needs to be empty

Recurring Payment (Subscriptions, 1-Click Checkout)

Once you have created a Payment Container, you can reuse it as long as it is valid.

This is the general flow:

images/inline/205d268a206791d83ae582513899d167752700eb.png

Everything what's needed is to create another Smart Transaction for the same customer, and prepare it with the same Payment Container.

Cancel the Transaction

To cancel a transaction you can use this endpoint: POST /api/v2/Payment/Transactions/PCI_XYZ/cancel
Alternatively, you can also cancel a transaction with the paymentID (hash) using (here you have to specificity the payment method that was used for the initial transaction):
POST /api/v2Payment/Secupaycreditcards/gdcfwxxxxpe2758919/cancel
In order to create credit card refunds, a special contract setting is required.
Additional information can be found here:

https://github.com/secuconnect/secuconnect-java-sdk/blob/3be5979a7804ae4a9d1506e800e93ff237ce93c1/src/main/java/io/secuconnect/client/model/PaymentTransactionCancelDTO.java

Example Request

A partial refund/cancel can be done by transmitting the parameter amount.Not transmitting this parameter or setting it to "0" it will do a complete refund/cancel.

{
"amount": 100,
"reason": "Money back because xxxx",
"reduce_stakeholder_payment": false
}

If stakeholder_payment also needs to be adjusted (percental), set the parameter reduce_stakeholder_payment to true. The default value is false.

Information for Response

If the action results in a refund, a new_trans_id is generated.

For a partial refund, you will see the open amount in the parameter remaining_amount.

The parameter refund_waiting_for_payment: true indicates that the merchant needs to transfer money back (after it was transferred to him).

Cancelling Sub-Transactions

A cancel can either be valid for the complete transaction or only affect sub-transactions.

To cancel a sub-transaction use the payment-id of the sub-transaction, e.g. abcdefghijkm1234567_23456789 instead of abcdefghijkm1234567 for the main transaction.

Submit Shipping Information

shipping

  1. created;

  2. approved (optional): payment is authorized;

  3. pending (optional): waiting for pay-in;

  4. received: waiting for shipment;

  5. shipped.

2 Endpoints are available to submit shipping information

For Payment transactions: GET Payment/Transactions/PCI_XYZ/shippingUrl

In order to set shipping information the transaction status has to be 86 "Kauf auf Rechnung abgeschlossen".

For Smart Transactions: POST /Smart/Transactions/STX_XYZ/finalize

Submitting shipping information using the Smart/Transactions Endpoint will be available in a future SDK Update.

Upload Documents

You can use the API-Endpoint Document/Uploads.

There are two possible ways to upload a file.

The maximum file size is 500.000 bytes

The common way is to upload the file via multipart message. For more details about this please visit https://en.wikipedia.org/wiki/MIME#Multipart_messages.

Upload Via Multipart Message

Request
POST /api/v2/Document/Uploads HTTP/1.1
Host: connect.secucard.com
Accept: application/json
Accept-Charset: utf-8
Content-Type: multipart/form-data; boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW
 
------WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="file"; filename="Ident_1213.pdf"
Content-Type: application/pdf
 
 
------WebKitFormBoundary7MA4YWxkTrZu0gW-
Response
{
"object": "document.uploads",
"id": "DUP_XYZ",
"created": "2018-08-01T08:00:30+02:00",
"type": "application/pdf",
"name": "Invoice_123456",
"size": 61617
}

Response-Parameters

  • object - The type of data (this should be always "document.uploads")

  • id - The ID of the uploaded files (this is needed for the next API request)

  • created - The uploaded date time.

  • type - The Content-Type (MIME-Standard, this should be always "application/pdf")

  • name - The filename of the uploaded file (the same as you have specified in the request in the parameter "filename")

  • size - The size of the file in Bytes

Upload Via JSON

The parameter content needs to be a Base64-Encoded-PDF. You can find more information about this on https://en.wikipedia.org/wiki/Base64#Examples.

Request
POST /api/v2/Document/Uploads HTTP/1.1
Host: connect.secucard.com
Accept: application/json
Content-Type: application/json
Accept-Charset: utf-8
 
{
"content": "YmFzZTY0X2VuY29kZWRfcGRm"
}
Response
{
"object": "document.uploads",
"id": "DUP_XYZ",
"created": "2018-07-31T15:08:52+02:00"
}

Response-Parameters

  • object - The type of data (this should be always "document.uploads")

  • id - The ID of the uploaded files (this is needed for the next API request)

  • created - The uploaded date time.

Submit Invoice Documents

Endpoint: /Payment/SecupayInvoices/ assignExternalInvoicePdf /abcdefg123456/ DUP_900B357K5Y4DU5WN95XMZS85X6US43

The Method AssignExternalInvoicePdf is used to submit invoice documents.

The Payment ID (hash) of the original transaction is required.

Example Response
{
"document": {
"id": "DUF_8Z092GGNK60KD94JPZFKYDS6C67X4C",
"mime_type": "image/png; charset=binary",
"name": "Invoice_123456.pdf",
"size": 55774,
"url": "https://api.testing.secupay-ag.de/ds_g/22842f43028d4927993e956f0cc31f0c"
}
}

Troubleshooting