Create Payment Transaction

This is by far the most important API request of the Flex.API. In order to create a new payment transaction you send a POST request to /payment/init.

Request
POST /payment/init HTTP/1.1
Host: api-testing.secupay-ag.de
Content-Type: application/json; charset=utf-8;
Accept: application/json
Accept-Charset: utf-8
 
{
"data": {
"apikey": "6801fxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx7ace",
"payment_type": "debit",
"demo": 1,
"payment_action": "sale",
"url_success": "https://example.org/SUCCESS",
"url_failure": "https://example.org/FAILURE",
"url_push": "https://example.org/PUSH",
"apiversion": "2.11",
"language": "de_DE",
"title": "Herr",
"firstname": "Max",
"lastname": "Mustermann",
"street": "Musterstr.",
"housenumber": "112 a",
"zip": "09555",
"city": "Musterhausen",
"country": "DE",
"telephone": "+4912342134123",
"dob_value": "01.02.1903",
"email": "max@example.org",
"ip": "172.31.6.49",
"currency": "EUR",
"amount": "199",
"purpose": "Test order 1"
}
}

Parameter overview:

Attribute

Type

Description

apikey

string

Your individual API key. It identifies the merchant, determines the contract, and grants access to the API. 40 alphanumeric digits like 6801fxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx7ace.

payment_type

string

Determines the payment method:

  • prepay (advance payment)

  • debit (SEPA direct debit)

  • invoice

  • creditcard

  • sofort

You can only use the contracted methods. The same method might be active in demo mode or not. Please ask our customer service for more payment methods.

demo

boolean|number| string

Optional demo flag:

  • 0 or false (real transaction)

  • 1 or true (demo transaction)

If ommitted, it defaults to false. Then it is a real transaction.

Please be careful with the flag and make sure to remove the demo parameter for transactions in the productive environment.

payment_action

string

Optional. Determines the workflow:

  • sale

  • authorization

In the sale flow the buyer completes the payment process with a pay now button. This is the final closure, and the money is captured immediately.

Having the authorization flow, the payment is only authorized. It needs a subsequent interface call to capture the money. You would use this flow if the final closure is done at your site after the customer returned to it.

If omitted, the payment action defaults to sale.

language

string

Optional, the language of the payment window:

  • de_DE for German

  • en_US for English

If omitted, it defaults to de_DE.

title

string

Optional "Mr" or "Mrs".

firstname

string

First name(s), like "Max-Johann", or "John M."

lastname

string

Last name(s), like "Mustermann", "Mustermann-Müller", or "van Mustermann".

company

string

Optional company name, like "Musterfirma GmbH & Co. KG". It is mandatory, if the customer is a company.

street

string

Street without house number, like "Musterallee", or "Dr.-Max-Mustermann-Platz".

housenumber

string

Full house number (including additions for split or joined properties; for example, "101-103", or "21 b").

zip

string

Postal code, like "09555".

city

string

Official town name.

country

string

Country as ISO-3166 Alpha-2 code; for example "DE" for Germany, or "CH" for Switzerland. See language for the translation of the payment window.

telephone

string

Phone number (international format), like "+493515555555".

dob

string

Optional date of birth (format example 31.01.2020); needed for scoring when you offer invoice.

email

string

E-mail address.

ip

string

IP address of the buyer as string.

amount

string|int

Amount to pay in the smallest unit; for example 1995 with EUR means 1995 Euro Cents, or €19.95.

Monetary amounts are expressed in the smallest currency unit (e. g. Euro Cent).

currency

string

Optional currency as ISO-4217 Alpha-3 code; for example EUR, GBP, or CHF. Special contract options are required in order to receive payments in currencies other than EUR.

If omitted, the currency defaults to Euro (EUR).

purpose

string

Optional purpose line. It is displayed for each position (a) at the bank statement of the payer, and (b) at our detailed advice note for the merchant. For example "order 5002012345 from 2020/01/31" or "hotel room, 1 p., b&b" .

apiversion

string

Optional API version, for example "2.11"

url_success

string

URL to return in case of success. See section Return Customer To Merchant Page.

url_failure

string

URL to return in any case of failure. See section Return Customer To Merchant Page.

url_push

string

URL to receive push messages on status changes. See section Receive Status Notifications (Push API).

If everthing is fine, the API responds with 200 OK:

Response
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8;
...
 
{
"status": "ok",
"data": {
"hash": "tujevzgobryk3303",
"iframe_url": "https://api.secupay.ag/payment/tujevzgobryk3303"
},
"errors": null
}

As you remember from the Getting Started section, the hash is needed for subsequent API calls, and the iframe URL displays our payment window.

Parameter overview:

Attribute

Type

Description

status

string

Whether the query was successful or not:

  • ok

  • error

data/hash

string

Transaction identifier, needed for subsequent API calls.

data/iframe_url

string

URL for authorisation or payment, depending on the payment_action.

Despite its name, you should not open the iframe_url within an Iframe ( <iframe> ):

  • It is forbidden to conduct a Sofort payment within an Iframe. (s. link to Sofort Integration Center)

  • 3-D Secure checks can leave the Iframe and switch to full-screen. In this case, the success (url_success) or failure URL (url_failure) of the shop is not opened inside the Iframe, but in the uppermost browser window (DOM window.top).

  • Some popular browsers have very strict same-origin restrictions for third party content, so that Cookie technology will not work inside Iframes. Most external authorisation flows cannot be completed.