The request must have the following headers:
Content-Type: application/json
Accept-Language: en-US
Origin: { Origin }
Create Checkout API
Last changes: 09-04-2023
The API method Create Checkout initiates the checkout process (see Integration).
| 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 | Conditional | Mandatory if "businessConsumer" object is not provided. Consumer's personal information. | consumer | Object |
| businessConsumer | Conditional | Mandatory if "consumer" object is not provided. Business/Company information. | businessConsumer | Object |
| order | No | Order details for the payment transaction. | Order | 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 |
| partnerReference | No | Merchant internal transaction reference. If provided, enables SmartPay to block cases of double processing | String | 64 |
| customReferences | No | For external party usage | customReferences | Object |
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 .
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.
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"
},
"order": {
"externalOrderReference": "123-333",
"lines":[
{
"lineNumber": 1,
"itemArticleId":"321456",
"itemName":"tires A",
"quantity":2,
"unitPrice":125,
"unitVatPrice":0,
"unitGrossPrice":125,
"vatPercent":0,
"netAmount":250,
"vatAmount":0,
"grossAmount":250
},
{
"lineNumber": 1,
"itemArticleId":"321456",
"itemName":"tires B",
"quantity":2,
"unitPrice":125,
"unitVatPrice":0,
"unitGrossPrice":125,
"vatPercent":0,
"netAmount":250,
"vatAmount":0,
"grossAmount":250
}
]
}
}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