secupay Payment Link – Our Payment Page

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.secuconnect.com
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.secuconnect.com
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:

images/download/attachments/168772664/image2022-12-2_16-20-29-version-1-modificationdate-1688374283000-api-v2.png

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:

images/download/attachments/168772664/secupay_secuOffice_Crowdinvesting-1024x666-version-1-modificationdate-1688382563000-api-v2.jpg

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”).

images/download/attachments/168772664/image2023-7-4_9-54-50-version-1-modificationdate-1688457291000-api-v2.png

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.