Create Checkout API

Last changes: 09-20-2022

The API method Create Checkout initiates the checkout process (see Integration).

API Parameters

Field Mandatory Description Type Length
merchantKey Yes The Merchant Key is the unique identifier for your integration, keep this credential secure, do not store client side. GUID 36
customerAccountId No Customer Account ID – A unique identifier provided by the integrating merchant by which the user’s account can be identified e.g. customer number.

If provided, SmartPay checks if an account exists, if it does it processes the transaction using the account or alternatively it creates a new account using the identifier.

If this parameter is omitted the transaction is processed as a guest payment; without the option to persists the payment option for future payments.
String 255
payment Yes The payment amount to be charged against the payment option. Payment Object
billingAddress Yes Billing address of the consumer. Address Object
shippingAddress No Shipping address of the consumer. Address Object
consumer Yes Consumer's personal information. Person Object
orderDetails No Order details for the payment transaction. Order details Object
extraInfo No Payment extra information to define the product group, to display different set of payment options (Card, SEPA, PayPal...) for different products. Extra Info Object

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 handeling the payment option selection for you, please always send the full data required.

As an example, if you whish to offer Klarna to your consumers, please always include order details object to your checkout request. If Klarna is not in your payment scope, the oder details object is optional.

Payment option payment billingAddress shippingAddress consumer orderDetails
Credit cards Yes Yes For physical goods Yes Optional
PayPal Yes Yes For physical goods Yes Optional
IDEAL Yes Yes Optional Yes Optional
PayU Yes Yes Optional Yes Optional
SEPA DD Yes Yes Optional Yes Optional
Klarna pay later Yes Yes For physical goods Yes Yes
Klarna pay over time Yes Yes For physical goods Yes Yes

Example

Request

Path:

POST {Base URL}/payment/creation

Header:

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

{
    "merchantKey": "73afeb44-432e-4b91-be37-a6b3d2fb7447",
    "customerAccountId": "Test-123",
    "payment": {
        "currencyCode": "EUR",
        "amount": 50.99,
        "description": "SMP-Transaction-01"
    },
    "billingAddress": {
        "addressLine1": "Leopoldstrasse",
        "number": "244",
        "city": "Munich",
        "postCode": "80807",
        "countryCode": "DE"
    },
    "shippingAddress": {
        "addressLine1": "Leopoldstrasse",
        "number": "244",
        "city": "Munich",
        "postCode": "80807",
         "countryCode": "DE"
    },
    "consumer": {
        "emailAddress": "hells.butcher_001@mail.com",
        "gender": "f",
        "lastName": "Hells",
        "firstName": "Butcher",
        "middleName": "fon",
        "title":"Mrs",
        "culture": "de-de",
        "dateOfBirth": "2000-01-01",
        "mobilePhone": "015xx22-2135466",
        "taxId": "00745948504594"
    },
    "orderDetails": {  
        "externalOrderReference": "Test 123",
        "orderPositions":[{
                "positionNumber": 1,
                "positionType": "Physical",
                "articleId":"321456",
                "articleName":"tire",
                "quantity":4,
                "netAmount":384,
                "taxAmount":16,
                "grossAmount":400,
                "taxRatePercent":4.00,
                "netPrice":1536,
                "taxPrice":64,
                "grossPrice":1600
            },
            {
                "positionNumber": 2,
                "positionType": "Physical",
                "articleId":"321456",
                "articleName":"tire",
                "quantity":4,
                "netAmount":384,
                "taxAmount":16,
                "grossAmount":400,
                "taxRatePercent":4.00,
                "netPrice":1536,
                "taxPrice":64,
                "grossPrice":1600
            }
        ]
    }
}

Response

{
    "transactionId": "e9c107eb-7630-4076-8b20-c19e05ecfe4d",
    "paymentStatus": "CREATED",
    "requestTime": "2020-11-03T16:38:35.680Z"
}

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"
            ]
        }
    ]
}

Document version 2.0 - 2020-12-17