Create Payment Transaction
This guide is for the deprecated Flex.API. If you are starting with a new integration, please refer to the Guide for the secuconnect API: Link
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.
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:
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:
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:
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:
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. |
|
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:
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:
|
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> ):
|