Create Checkout

The API method Create Checkout initiates the checkout process. This section provides details on its request and response structures, required parameters, and use cases. For an overview of how this method fits into the broader integration process, see our Integration Journey​ page.

Request

info

The request must have the following headers:

• Content-Type: application/json
• Accept-Language: en-US
• Origin: { Origin }
• User-Agent: { User-Agent }

tip

For full specifications for the Create Checkout API parameters, please refer to the API-Reference.

important

In case of payments to different target merchant accounts in the same marketplace, the target merchant accounts references should be provided by merchant to their dedicated Product Solution Specialist.

info

You can have product groups defined as part of your setup, to display different set of payment options (Card, SEPA, PayPal...) for different products.
The input parameter productGroup under object extraInfo, would then needs to be provided in your Checkout API request. To define your product groups please reach out to your Product Solution Specialist.

Mandatory data per payment option

The table below shows you the minimum data object requirements per payment option to be provided in checkout API. As SmartPay is handling the payment option selection for you, please always send the full data required.

Payment option	payment	billingAddress	shippingAddress	consumer
Apple Pay	Yes	Optional	Optional	Yes
Credit cards	Yes	Yes	For physical goods	Yes
Google Pay	Yes	Optional	Optional	Yes
IDEAL	Yes	Yes	Optional	Yes
Pay-by-Bank	Yes	Yes	Optional	Yes
PayPal	Yes	Yes	For physical goods	Yes
PayU	Yes	Yes	Optional	Yes
SEPA DD	Yes	Yes	Optional	Yes

info

Minimum data requirements are determined by regulatory and payment provider requirements. Please reach out to your Product Solution Specialist for further details.

Example

Request

Path:

POST {Base URL}/payment/creation

Header:

Content-Type: application/json
Accept-Language: en-US
Origin: { Origin }
User-Agent: { User-Agent }

{
    "merchantKey": "3227a1df-1033-46fd-93bd-x01777339e5b",
    "partnerReference": "5363737832823654334",
    "customerAccountId": "",
    "3dsExemption": {
        "flag": "LVA"
    },
    "shopCountry": "DE",
    "payment": {
        "currencyCode": "EUR",
        "amount": 40.11,
        "description": "Purchase 1x product ABC"
    },
    "templateContext": {
        "templateId": "test-12",
        "culture": "en-EN"
    },
    "paymentSplit": {
        "paymentSplitDestinations": [
            {
                "destination": 0,
                "destinationReference": "destinationMerchantAccountAlias_1",
                "currencyCode": "EUR",
                "amount": 50.99,
                "description": "SMP-Split-Transaction-1"
            },
            {
                "destination": 1,
                "destinationReference": "destinationMerchantAccountAlias_2",
                "currencyCode": "EUR",
                "amount": 50.99,
                "description": "SMP-Split-Transaction-2"
            }
        ]
    },
    "billingAddress": {
        "customerFullName": "Hells Butcher",
        "emailAddress": "hells.butcher_001@mail.com",
        "address": "Leopoldstrasse",
        "number": "244",
        "city": "Munich",
        "postCode": "80807",
        "countryCode": "DE"
    },
    "shippingAddress": {
        "address": "Leopoldstrasse",
        "number": "244",
        "city": "Munich",
        "postCode": "80807",
        "countryCode": "DE"
    },
    "consumer": {
        "emailAddress": "hells.butcher_001@mail.com",
        "customerGroupId": "VIP",
        "gender": "m",
        "lastName": "Hells",
        "firstName": "Butcher",
        "middleName": "fon",
        "title": "Mr",
        "culture": "en-de",
        "timezone": "<EXAMPLE>",
        "dateOfBirth": "2000-01-01",
        "mobilePhone": "015xx22-2135466",
        "isBusinessUser": false,
        "taxId": "00745948504594"
    },
    "order": {
        "externalOrderReference": "123-333-Oct-2020",
        "lines": [
            {
                "lineNumber": 1,
                "lineType": "Classic",
                "itemArticleId": "321456",
                "itemName": "tire",
                "quantity": 4,
                "unitPrice": 384,
                "unitVatPrice": 16,
                "unitGrossPrice": 400,
                "vatPercent": 4.00,
                "netAmount": 1536,
                "vatAmount": 64,
                "grossAmount": 1600
            },
            {
                "lineNumber": 2,
                "lineType": "Classic",
                "itemArticleId": "321456",
                "itemName": "tire",
                "quantity": 4,
                "unitPrice": 384,
                "unitVatPrice": 16,
                "unitGrossPrice": 400,
                "vatPercent": 4.00,
                "netAmount": 1536,
                "vatAmount": 64,
                "grossAmount": 1600
            }
        ]
    }
}

tip

The Create Checkout response includes the 36-character GUID of the Transaction ID for modification APIs and Checkout Token for web widget initialization.

important

For transactions using Apple Pay or Google Pay™, please consult the respective integration pages for details on required domain configuration and button styling parameters within the object criteria.

Response

{
    "transactionId": "fc10f767-12a7-46d0-9da0-4af6b5b67c4d",
    "checkoutToken": "KwlJmj1QoJL4oFPaCYnNCTW8cC8ZsLvQg16erCzx7hlU0rxLi3TdAKBLAN6md2Ik",
    "paymentStatus": "CREATED",
    "requestTime": "2023-04-05T13:25:41.790Z",
    "ignoredProperties": [
        "payment.country",
        "templateContext",
        "consumer.customerGroupId",
        "consumer.isBusinessUser"
        ]
}

Response on failure

Status Code:

400 (Bad Request)

Header:

Content-Type: application/json
Accept-Language: en-US

{
    "message": [
        {
            "payment": [
                "amount must not be less than 0.01",
                "currencyCode must match /^[A-Z]{3}$/ regular expression",
                "currencyCode must be a string",
                "currencyCode should not be empty"
            ]
        },
        {
            "consumer": [
                "firstName must be shorter than or equal to 60 characters",
                "firstName must be a string",
                "firstName should not be empty"
            ]
        }
    ]
}

info

If you receive an HTTP status other than 2xx, the request failed. Please try to interpret the response message to correct your request and contact customer support in case of further questions.

SmartPay Gatekeeper

SmartPay's Gatekeeper functionality ensures controlled transaction flow by regulating the number of active payment sessions per merchant. This feature helps maintain a seamless payment experience by enforcing limits on simultaneous transactions.

The Gatekeeper works to manage active payment sessions effectively:

• Each initiated payment session increases the active session count for a merchant.
• When a payment is completed or the session expires, the count decreases.
• If the merchant's active session limit is reached, new transactions are temporarily blocked until an existing session completes or expires.

This feature operates at the system level and does not rely on specific response headers for rate limit enforcement.

Active sessions automatically decrease when:

• A payment is successfully processed.
• A session remains inactive and is terminated by background jobs.

info

The maximum number of active sessions per merchant is based on predefined limits and can be adjusted as needed. Merchants handling high transaction volumes should coordinate with their Product Solution Specialist to optimize session limits for their business requirements.