This tutorial is about the API integration of Payment Link, our payment page. If you only need small numbers of Payment Links, you can also create them manually in secuOffice.

Step 1: Authenticate with OAuth 2.0

The endpoint for OAuth authorization is POST / oauth/token.

Request

POST /oauth/token HTTP/1.1
Host: connect-testing.secupay-ag.de
Content-Type: application/json
Accept: application/json
 
{
    "grant_type": "client_credentials",
    "client_id": "00563697073442633035025909838580",
    "client_secret": "3382456441636938321687549172178382320163695870914358804052148567"
}

If everything is fine, it responds with 200 OK and the token details:

Response

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

You need to pass the received token with your subsequent calls, using the Authorization: Bearer HTTP header. The above token is qb56tjj1bcvo9n2nj4u38k84lo, and it is valid for the next 1,200 seconds.

Step 2: Create the Smart Transaction

The API endpoint to create the needed Smart Transaction is POST /api/v2/Smart/Transactions.

Request

POST /api/v2/Smart/Transactions HTTP/1.1
Host: connect-testing.secupay-ag.de
Authorization: Bearer qb56tjj1bcvo9n2nj4u38k84lo
Content-Type: application/json
Accept: application/json
 
{
    "is_demo": true,
    "intent": "sale"
    "contract": {
      "id": "GCR_KTSST836QYITQJM1JGYIZ4F4OLKI04"
    },
    "customer": {
        "contact": {
            "salutation": "Mr."
            "forename": "Max",
            "surname": "Mustermann",
            "address": {
                "street": "Musterstr.",
                "street_number": "11",
                "additional_address_data": "App. 302",
                "postal_code": "09123",
                "city": "Musterstadt",
                "country": "DE"
            },
            "email": "max@example.org",
            "phone": "+49 555 5555555",
            "mobile": "+49 177 5555555",
            "dob": "1965-12-31"
        }
    },
    "transactionRef": "Test secupay",
    "basket_info": {
        "currency": "EUR",
        "sum": 17500
    },
    "application_context": {
        "checkout_template": "COT_WD0DE66HN2XWJHW8JM88003YG0NEA2",
    },
    "payment_context": {
        "auto_capture": true
    }
}

This creates a Smart Transaction for a payment of €175.00.

Request details:

Field	Type	Meaning
`is_demo`	`boolean`	Optional. Whether the transaction is a demo transaction: `true` for demo transactions; `false` for productive transactions. Defaults to `false`, productive transaction.
`intent`	`string`	The intent of the transaction. In our case always `"sale"`.
`contract`	`object`	The contract ID of the merchant (`"id": "GCR_..."`). You receive this ID during onboarding.
`customer`	`object`	The customer details. (See details on `contact` below.)
`transactionRef`	`string`	Optional. This can be helpful to trace back the order on your site. It is also used for the purpose line at the bank statements.
`basket_info`	`object`	Currency and total. (See details below.)
`application_context`	`object`	Optional application context, like optional return URLs. (See details below.)
`payment_context`	`object`	Controls payment details. (See details below.)

Details of the contact object (inside customer):

Field	Type	Meaning
`company_name`	`string`	Optional company name.
`forename`	`string`	First name of the person.
`surname`	`string`	Last name of the person.
`salutation`	`string`	Optional salutation of the person.
`address`	`object`	Optional postal address. (See details below.)
`email`	`string`	Email address.
`phone`	`string`	Optional landline number.
`mobile`	`string`	Optional mobile phone number.
`dob`	`string`	Optional date of birth. (ISO 8601 date like `"2023-02-28"`.)

Details of the address object (inside contact):

Field	Type	Meaning
`street`	`string`	Street, or street with house number.
`street_number`	`string`	Optional house number.
`additional_address_data`	`string`	Optional second address line, for apartment number, etc.
`postal_code`	`string`	ZIP code.
`city`	`string`	City or town.
`country`	`string`	Country. (ISO 3166 two letter country code like `"DE"`.)

Details of the application_context object (incomplete):

Field	Type	Meaning
`return_urls`	`object`	Optional return URLs for the Payment Link to redirect the buyer to after the successful or failed checkout process to your page.
`checkout_template`	`string`	Checkout template. I controls the page flow and fields of Smart Checkout. Must be `COT_WD0DE66HN2XWJHW8JM88003YG0NEA2` for Payment Link.
`language`	`string`	Optional display language for Smart Checkout: `de` for German; `en` for English. Defaults to German.

Details of the return_urls object (inside application_context):

Field	Type	Meaning
`url_success`	`string`	Optional URL the buyer is redirected to after successful payment.
`url_error`	`string`	Optional URL the buyer is redirected to when the payment failed.
`url_abort`	`string`	Optional URL the buyer is redirected to when he stopped the payment process intentionally.
`url_failure`	`string`	Optional URL the buyer is redirected to after failed payment. This is write-only, and sets both `url_error` and `url_abort`.

Details of the payment_context object (incomplete):

Field	Type	Meaning
`auto_capture`	`boolean`	You should use `true`. This shows the "Buy now!" button, and captures the payment automatically after successful authorisation. When `false` or if omitted, it would show the "Continue!" button, and only authorises the payment. You would need an additional API call for the actual payment.

If everything is fine, the API responds with 200 OK and the representation of the Smart Transaction:

Response

HTTP/1.1 200 OK
Content-Type: application/json
...
 
{
    "object": "smart.transactions",
    "id": "STX_2AUSR7M6B2NHPG3C4JTKBEY07YXSAZ",
    "merchant": {
        "object": "general.merchants",
        "id": "MRC_G8SE48FRHVITKILAPNCEDU0NUD55W8",
        "companyname": "Musterhändler GmbH"
    },
    "contract": {
        "object": "general.contracts",
        "id": "GCR_KTSST836QYITQJM1JGYIZ4F4OLKI04"
    },
    "customer": {
        "object": "payment.customers",
        "id": "PCU_DZXFBGXCY2P52KHAZC8W5HKWG9BJA3",
        "contact": {
            "name": "Max Mustermann",
            "forename": "Max",
            "surname": "Mustermann",
            "companyname": null,
            "salutation": "Mr.",
            "gender": null,
            "title": null,
            "dob": "1965-12-31T00:00:00+00:00",
            "url_website": null,
            "birthplace": null,
            "nationality": null,
            "picture": null,
            "email": "max@example.org",
            "phone": "+495555555555",
            "mobile": "+491775555555",
            "address": {
                "street": "Musterstr.",
                "street_number": "11",
                "additional_address_data": "App. 302",
                "postal_code": "09123",
                "city": "Musterstadt",
                "country": "DE"
            }
        }
    },
    ...
    "created": "2020-02-04T15:34:00+01:00",
    "status": "created",
    "transactionRef": "Test secupay",
    ...
    "basket_info": {
        "sum": 4985,
        "currency": "EUR",
        ...
    },
    "is_demo": true,
    ...
    "application_context": {
         "checkout_template": "COT_WD0DE66HN2XWJHW8JM88003YG0NEA2",
         "return_urls": {
            "url_success": "https://shop.example.com/PAYMENT-SUCCEEDED",
            "url_error": "https://shop.example.com/PAYMENT-FAILED",
            "url_abort": "https://shop.example.com/PAYMENT-ABORTED"
        },
        ...
    },
    "payment_context": {
        "auto_capture": true,
        "payment_methods": null,
        "merchant_initiated": false,
        "accrual": false,
        "creditcard_schemes": [
            "mastercard",
            "visa",
            "american express"
        ]
    },
    "checkout_links": null,
    "payment_links": {
        "creditcard": "https://pay-dev.secuconnect.com?payment-method=creditcard&stx=STX_33PXAW2YN2NJTPM5KPGMK7QF5PBVA2&contract=GCR_KTSST836QYITQJM1JGYIZ4F4OLKI04&server=testing",
        "debit": "https://pay-dev.secuconnect.com?payment-method=debit&stx=STX_33PXAW2YN2NJTPM5KPGMK7QF5PBVA2&contract=GCR_KTSST836QYITQJM1JGYIZ4F4OLKI04&server=testing",
        "invoice": "https://pay-dev.secuconnect.com?initPaymentMethod=invoice&stx=STX_33PXAW2YN2NJTPM5KPGMK7QF5PBVA2&contract=GCR_KTSST836QYITQJM1JGYIZ4F4OLKI04&server=testing",
        "paypal": "https://pay-dev.secuconnect.com?payment-method=paypal&stx=STX_33PXAW2YN2NJTPM5KPGMK7QF5PBVA2&contract=GCR_KTSST836QYITQJM1JGYIZ4F4OLKI04&server=testing",
        "prepaid": "https://pay-dev.secuconnect.com?payment-method=prepay&stx=STX_33PXAW2YN2NJTPM5KPGMK7QF5PBVA2&contract=GCR_KTSST836QYITQJM1JGYIZ4F4OLKI04&server=testing",
        "sofort": "https://pay-dev.secuconnect.com?payment-method=sofort&stx=STX_33PXAW2YN2NJTPM5KPGMK7QF5PBVA2&contract=GCR_KTSST836QYITQJM1JGYIZ4F4OLKI04&server=testing",
        "general": "https://pay-dev.secuconnect.com?stx=STX_33PXAW2YN2NJTPM5KPGMK7QF5PBVA2&contract=GCR_KTSST836QYITQJM1JGYIZ4F4OLKI04&server=testing"
    }
}

As you see, the system behind the secuconnect API added many things. The most interesting are:

Field	Type	Meaning
`id`	`string`	The ID of the new Smart Transaction object. You may need it for the subsequent API calls.
`status`	`string`	The status of the Smart Transaction, currently `"created"`.
`payment_links`	`string[]`	The URLs to open the Payment Link. (See details below.)

Details of the payment_links object:

Field	Type	Meaning
`general`	`string`	URL to pay with any contracted and matching method.
`creditcard`	`string`	URL to pay with credit card.
`debit`	`string`	URL to pay with SEPA direct debit.
`eps`	`string`	URL to to pay with EPS (for Austria).
`easycredit`	`string`	URL to pay with easyCredit Ratenkauf (instalment payment).
`giropay`	`string`	URL to pay with giropay (for Germany).
`invoice`	`string`	URL to pay on account with bank transfer.
`paypal`	`string`	URL to pay with PayPal.
`prepaid`	`string`	URL to pay in advance with bank transfer.
`sofort`	`string`	URL to pay with klarna Sofort.

Most interesting is the ID of the Smart Transaction so far, and one of the URLs.

The newly created Payment Link is also visible in secuOffice:

For instance you can watch the status here.

Step 3: Open the Payment Link

The URL in payment_links/general opens the Payment Link, our payment page, with the payment method selection. This is the preferred method. The other URLs restrict the Payment Link to one payment method. In some cases the user might be directed back to the success, failure or abort URL immediately.

For demonstration, we simply put the URL into our browser's address bar. This opens the Payment Link in fullscreen:

As you can see, it is very easy.

Please consider that some flows will escape iframes, since these can be forbidden (klarna Sofort), or the strict security measures of modern browsers make would break the process. Thus we recommend to open the Payment Link always in fullscreen.

Note on Invoice Payment

For invoice payment, you must report the shipment. Otherwise we cannot know that and when the payment becomes due.

You can do this manually in secuOffice, or you can also automate it with the secuconnect API. See Mark As Shipped for more information.

Configure a Background Image

A background image can be configured in secuOffice at “Payment” » “Payment Link” » “Settings” (or German: “Einstellungen”).

Please remember that you cannot predict the screen size or the aspect ratio. You cannot know which part is visible. The middle part is always hidden.