Create Checkout API

Last changes: 02-28-2024

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

API Parameters

The request must have the following headers:

Content-Type: application/json

Accept-Language: en-US

Origin: { Origin }

Field	Description	Type	Length	Mandatory
merchantKey	The Merchant Key is the unique identifier for your integration, keep this credential secure, do not store client side.	GUID	36	Yes
customerAccountId	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	NO for Checkout YES for Create MIT transaction, unless dealReference is provided.
payment	The payment amount to be charged against the payment option.	Payment	Object	Yes
billingAddress	Billing address of the consumer.	Address	Object	Yes
shippingAddress	Shipping address of the consumer.	Address	Object	No
consumer	Consumer's personal information.	consumer	Object	Conditional. Mandatory if "businessConsumer" object is not provided.
businessConsumer	Business/Company information.	businessConsumer	Object	Conditional. Mandatory if "consumer" object is not provided.
order	Order details for the payment transaction.	Order	Object	No
extraInfo	Payment extra information to define the product group, to display different set of payment options (Card, SEPA, PayPal...) for different products.	Extra Info	Object	No
criteria	Collection of additional request parameters passed to the payment provider.	An array of Criterion objects	Object	No
partnerReference	Merchant internal transaction reference. If provided, enables SmartPay to block cases of double processing	String	64	No
customReferences	For external party usage	customReferences	Object	No
deal	Details of the deal. Used only for 3RI payments (Partial/split shipment and Delayed shipment use cases)	Deal	Object	No

Please refer to our data model for details regarding the referenced objects.

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 Technical Rollout Manager .

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

Minimum data requirements are determined by regualtory and payment provider requirements. Please reach out to your rollout manager for further details.

Example

Request

Path:: POST {Base URL}/payment/creation
Header:: Content-Type: application/json
Accept-Language: en-US

{
    "merchantKey": "3227a1df-1033-46fd-93bd-x01777339e5b",   // comes from Authentication requirements
    "partnerReference": "5363737832823654334",
    "customerAccountId": "",
    "excemptionFlag":"07",
    "shopCountry": DEU
    "payment": {
        "currencyCode": "EUR",
        "amount": 40.11,
        "description": "Purchase 1x product ABC"
    },
    "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": "de-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,
                "vatPrice":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
            }
        ]
    }
}

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

Response

{
    "transactionId": "fc10f767-12a7-46d0-9da0-4af6b5b67c4d",
    "checkoutToken": "KwlJmj1QoJL4oFPaCYnNCTW8cC8ZsLvQg16erCzx7hlU0rxLi3TdAKBLAN6md2Ik",
    "paymentStatus": "CREATED",
    "requestTime": "2023-04-05T13:25:41.790Z"
}

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

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

Document version 2.0 - 2020-12-17

Previous

Next