deprecated

Introduction to Flex.API

The Flex.API uses HTTPS to create payment transactions or to perform other actions. (Unencrypted HTTP is not offered for security reasons. But we will use the term HTTP when we refer to request methods, headers, and the like.) The data is represented in JSON.

Basic Workflows

There are two possible workflows:

• sale: The money is captured immediately. (Invoice payment needs an additional call to capture.)
• authorization: The payment is only authorised. It needs a subsequent interface call to actually capture the money.

Every payment transaction is predetermined to a particular payment method.

Working Example

In our brief example we will create a payment transaction direct debit, using the sale flow. Then we will start the payment iframe. We will use JSON as data transfer format.

These are the steps we will:

1. Obtain the available payment methods. This is not necessary, but recommended, and easy to achieve.
2. Create the payment transaction, and direct the customer to the Payment Wizard.
3. Obtain the status of the transaction when the customer is returned. This is not necessary, but recommended, and easy to achieve.

Step 1: Obtain the Available Payment Methods

First we send a GET request to /payment/gettypes to obtain the available payment methods. This is our HTTP request, directed to our test system:

This would be our response:

The returned payment methods correspond one-to-one with the field payment_type of the next step. As you see, a lot of different payment methods are active here.

Step 2: Create a Payment Transaction

Knowing direct debit would work, we offer it to our customer. Since our example uses the sale flow it must be offered at the end of your checkout process. The customer will close the contract with you together with the payment.

Here is our example request:

As you see, the request is an HTTP POST to https://api-testing.secuconnect.com/payment/init. The payment is about €19,95.

You see also a demo flag. Although it has no extra effect on the testing server, it is good to know it. You can use it in the productive environment to create payment transactions that are not being captured.

This is the response of the server:

Everything worked. The payment transaction is created.

Please notice the two fields hash and iframe_url. The URL is given to the buyer in order to authorise the payment, and finally confirm the business transaction at the same time. If former API requests need to be performed, you should store the hash on your server. If the payment method was prepaid or invoice there would also be additional data that is explained in the Reference section.

This is what your customers see, if they open the iframe_url in their browser:

The customer is prompted to confirm the payment, and sometimes for the needed data. When they use the buttons to submit or cancel, they are either directed to the success URL or the failure URL. In some cases the customer is not directed back to one of these URLs. They might simply stop here, and close the browser.

Step 3: Obtain the Transaction Status

We recommend that you also check the status of the transaction after the success URL was called.

This is an example request to obtain the status from our server:

Example response:

If the payment method was prepaid or invoice additional details would be available.

Summary

We have obtained the available payment methods with a first interface call. After this we created a payment transaction for direct debit payment to be captured immediately. We found the iframe URL in it, and acted as customer in our tests. We have entered the bank details, and confirmed the payment. Afterwards, we were led back to the shop's success URL. We have also found the transaction's hash and used it for a second API call to obtain the transaction status.

Furthermore you can:

• use the authorization flow;
• use other payment methods (credit card, advance payment, invoice payment, Sofort);
• define return URLs to direct the customer back to your website;
• show a detailed basket;
• show project or payment details;
• define stakeholder shares;
• defer the capture for a condition (accrual);
• work with recurring payments for subscriptions;
• customize the button text or the primary design colour;
• use informal speech, or change the language.

Everything you need as a merchant is found in the following reference section. Furthermore you will find details of the communication protocol, the test environment and the demo flag.