Create Checkout API
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 } - User-Agent:
{ User-Agent }
| 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. | String | 36 | Yes |
| partnerReference | Transaction identifier provided by the merchant. If provided must be unique (for that merchant). Accepted symbols: "a-z", "A-Z", "0-9", "-", "_", ".", ":". | String | 64 | No |
| customerAccountId | 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 |
| 3dsExemption | 3DS exemption data, flag with enumeration: LVA. | String | - | No |
| shopCountry | ISO 3166-1 alpha-2 code of the shop country. | String | 2 | No |
| payment | Requested transaction amount information. | Object | - | Yes |
| templateContext | Template context for the Hosted Payment Page. Once provided, it is used by SmartPay to render a specific HTML with customized properties. | Object | - | No |
| paymentSplit | If passed, defines all related information for split payments. Not supported on Hosted Payment Page. | Object | - | No |
| billingAddress | Billing address of the consumer. | Object | - | Yes |
| shippingAddress | Shipping address of the consumer. | Object | - | No |
| consumer | Consumer's personal data, in case the consumer is a physical person. | Object | - | Conditional. Mandatory if "businessConsumer" object is not provided. |
| businessConsumer | Company data, in case the consumer is a business or a legal entity. | Object | - | Conditional. Mandatory if "consumer" object is not provided. |
| order | Purchased order details. | Object | - | No |
| extraInfo | Payment extra information to define the product group, to display different set of payment options (Card, SEPA, PayPal...) for different products. | Object | - | No |
| criteria | Collection of additional request parameters passed to the payment provider. | Object | - | No |
| customReferences | For external party usage. Please refer to Data Model for details. | Object | - | No |
| deal | Details of the deal. Used only for 3RI payments (Partial/split shipment and Delayed shipment use cases) | Object | - | No |
| targetMerchantAccountReference | If provided, the payment is processed in favour of the indicated submerchant account, and the main merchant account number is ignored. | String | 127 | No |
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.
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 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 |
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
}
]
}
}
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",
"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"
]
}
]
}
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.
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.
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.
To ensure efficient processing, full database scans should be avoided when evaluating session limits. If optimizations are required, SmartPay provides alternative solutions to minimize system load. Please contact your designated Product Solution Specialist for more information.