Create Checkout

POST 
/payment/creation

This API method initiates the checkout process. It allows you to create a new payment transaction and receive a checkout token for further processing.

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 need to be provided in your Checkout API request. To define your product groups please reach out to your Product Solution Specialist.

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

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

Request

Header Parameters

Content-Type stringrequired

Must be application/json

Accept-Language stringrequired

Must be be en-US

Origin stringrequired

The origin of the request

User-Agent stringrequired

The client making the request

application/json

Body

Bodyrequired

merchantKeystringrequired

The Merchant Key is the unique identifier for your integration. Keep this credential secure, do not store client side.

Possible values: <= 36 characters

partnerReferencestring

Transaction identifier provided by the merchant. If provided must be unique (for that merchant).

Possible values: <= 64 characters, Value must match regular expression "a-z", "A-Z", "0-9", "-", "_", ".", ":"

customerAccountIdcustomerAccountId

A unique identifier provided by the integrating merchant by which the user's account can be identified e.g., customer number.

Possible values: <= 255 characters

3DSExemption object

3DS exemption data

flagstring

Possible values: [LVA]

shopCountrystring

ISO 3166-1 alpha-2 code of the shop country.

Possible values: >= 2 characters and <= 2 characters

payment objectrequired

The payment amount to be charged against the payment option.

amountnumber<decimal>required

currencyCodestringrequired

Possible values: <= 3 characters

descriptionstringrequired

Possible values: <= 127 characters

paymentSplit object
If passed, defines all related information for split payments. Not supported on Hosted Payment Page
paymentSplitDestinations object[]required
Possible values: >= 1
Array [
amountnumber<decimal>required
Transaction modification amount
Possible values: >= 0.01, Value must match regular expression ^\d{1,18}\.\d{2}$
Example: 49.99
currencyCodestringrequired
Transaction modification currency. The 3-letter currency ISO-4217 code
Possible values: >= 3 characters and <= 3 characters
Example: EUR
descriptionstringrequired
A terse description of the good or service being sold i.e., the reason for the payment
Possible values: <= 127 characters
Example: windscreen wipers 4 pcs
destinationReferencestringrequired
Destination merchant account alias
Possible values: <= 127 characters
Example: destination-ref-1
]
templateContextobject

Template context for the Hosted Payment Page. Once provided, it is used by SmartPay to render a specific HTML with customized properties.

billingAddress objectrequired

Billing address of the consumer.

addressLine1stringrequired

Street name.

Possible values: <= 60 characters

Example: Max-Planck-Straße

addressLine2string

Apartment, suite, unit, building, floor or other secondary address information.

Possible values: <= 60 characters

addressLine3string

Specific delivery instructions, department names, or additional floor information.

Possible values: <= 60 characters

citystringrequired

The city or localitly of the address.

Possible values: <= 50 characters

Example: Berlin

countryCodestringrequired

ISO-3 code of the address country (e.g., DEU for Germany).

Possible values: >= 3 characters and <= 3 characters

Example: DEU

numberstring

The house or building number corresponding to the street address.

Possible values: <= 10 characters

Example: 30

postCodestringrequired

The postal or ZIP code of the address.

Possible values: <= 10 characters

Example: 14473

statestring

3-letter code of the address state. Mandatory when countryCode corresponds to Canada or USA.

Possible values: <= 3 characters

shippingAddress object

Shipping address of the consumer.

addressLine1stringrequired

Street name.

Possible values: <= 60 characters

Example: Max-Planck-Straße

addressLine2string

Apartment, suite, unit, building, floor or other secondary address information.

Possible values: <= 60 characters

addressLine3string

Specific delivery instructions, department names, or additional floor information.

Possible values: <= 60 characters

citystringrequired

The city or localitly of the address.

Possible values: <= 50 characters

Example: Berlin

countryCodestringrequired

ISO-3 code of the address country (e.g., DEU for Germany).

Possible values: >= 3 characters and <= 3 characters

Example: DEU

numberstring

The house or building number corresponding to the street address.

Possible values: <= 10 characters

Example: 30

postCodestringrequired

The postal or ZIP code of the address.

Possible values: <= 10 characters

Example: 14473

statestring

3-letter code of the address state. Mandatory when countryCode corresponds to Canada or USA.

Possible values: <= 3 characters

consumer objectnullablerequired
Consumer's personal data, in case the consumer is a physical person. See consumer in Data model.
Conditional. Can be present if businessConsumer is missing from the request.
culturestring
Consists of ISO 639-1 language code and ISO 3166-1 alpha-2 country code separated by dash. If this value is not provided the browser culture is used. Default culture is English (e.g., en-de). This field is not case sensitive.
Possible values: <= 5 characters
Example: en-EN
dateOfBirthstring<date>
Date of birth. Format - YYYY-MM-DD. Mandatory for payment option registration flow. Minimum date allowed is 1900-01-01
Possible values: <= 10 characters, Value must match regular expression ^\d{4}-\d{2}-\d{2}$
Example: 1989-11-08
emailAddressstring<email>required
Customer email address for any notification
Possible values: <= 255 characters
Example: john.doe@gmail.com
firstNamestringrequired
Person first name
Possible values: <= 60 characters
Example: John
genderstring
Person gender
Possible values: <= 6 characters
Example: Mr
homePhonestring
Person's home phone number (including the country code)
Possible values: <= 30 characters
Example: 496912345678
lastNamestringrequired
Person last name
Possible values: <= 60 characters
Example: Doe
merchantCustomerIdstring
Consumer/Customer Account Id in the merchant system. When provided into the Create Checkout API, SmartPay will request e-wallet account creation which will have external account reference equals to the given merchantCustomerId value.
Possible values: <= 255 characters
Example: abcd123
middleNamestring
The customer's middle name
Possible values: <= 60 characters
Example: Robert
mobilePhonestring
Person's mobile phone number (including the country code)
Possible values: <= 30 characters
Example: 496912345678
taxIdstring
Person's tax identification number
Possible values: <= 30 characters
Example: 123456789
timezonestring
Preferred timezone name
Possible values: <= 50 characters
Example: CET
titlestring
Person title
Possible values: <= 3 characters
Example: Mr
workPhonestring
Person's work phone number (including the country code)
Possible values: <= 30 characters
Example: 496912345678
businessConsumer objectnullablerequired

Company data, in case the consumer is a business or a legal entity. See businessConsumer in Data model.
Conditional. Can be present if consumer is missing from the request.

companyNamestringrequired

Name of the legal entity

Possible values: <= 100 characters

companyRegistrationCountryCodestring

Company registration country ISO2 or ISO3 code

Possible values: >= 2 characters and <= 3 characters

companyRegistrationNumberstring

Company registration number

Possible values: <= 50 characters

companyTypestringrequired

Possible values: <= 100 characters

culturestring

Consists of ISO 639-1 language code and ISO 3166-1 alpha-2 country code separated by dash. If this value is not provided the browser culture is used. Default culture is English (e.g., en-de). This field is not case sensitive.

Possible values: <= 5 characters

Example: en-EN

emailAddressstringrequired

Customer email address for any notification

Possible values: <= 255 characters

taxIdstring

Person's tax identification number

Possible values: <= 30 characters

order object

Purchased order details.

externalOrderReferencestringrequired

Possible values: <= 225 characters

lines orderLine[]required

Array [

additionalData object[]

Array [

namestring

Possible values: <= 100 characters

valuestring

Possible values: <= 255 characters

]

lines object[]

List of purchased items associated with the order.

Array [

lineNumberintegerrequired

Sequential line number of the item in the order.

itemArticleIdstringrequired

Unique identifier or SKU of the purchased item.

Possible values: <= 64 characters

itemNamestringrequired

Name or description of the purchased item.

Possible values: <= 255 characters

quantityintegerrequired

Quantity of the item purchased.

unitPricenumber<decimal>required

Unit net price (excluding VAT) of a single item.

Possible values: >= 0

unitVatPricenumber<decimal>

VAT amount per unit item.

Possible values: >= 0

unitGrossPricenumber<decimal>required

Unit gross price (net price + VAT) of a single item.

Possible values: >= 0

vatPercentnumber<decimal>required

VAT percentage applied to the item.

Possible values: >= 0 and <= 100

netAmountnumber<decimal>required

Total net amount for the line (quantity × unit net price).

Possible values: >= 0

vatAmountnumber<decimal>required

Total VAT amount for the line (quantity × unit VAT price).

Possible values: >= 0

grossAmountnumber<decimal>required

Total gross amount for the line (net amount + VAT amount).

Possible values: >= 0

]

]

totals object

grossAmountnumber<decimal>

Total gross amount for the line (net amount + VAT amount).

Possible values: >= 0

netAmountnumber<decimal>

Total net amount for the line (quantity × unit net price).

Possible values: >= 0

vatAmountnumber<decimal>

Total VAT amount for the line (quantity × unit VAT price).

Possible values: >= 0

extraInfo object
Payment extra information to define the product group, to display different set of payment options (Card, SEPA, PayPal...) for different products.
customerGroupstring
In case customer group rule is defined in channel configuration, this value is used for channel evaluation
Possible values: <= 100 characters
Example: SilverCustomers
productGroupstring
In case customer group rule is defined in channel configuration, this value is used for channel evaluation
Possible values: <= 100 characters
Example: tyres
criteria object[]
List of custom key-value pairs that the merchant can submit.
The names callBackUrl and redirectUrl will be disregarded.
Array [
namestringrequired
Possible values: <= 50 characters
valuestringrequired
Possible values: <= 100 characters
]
customReferences object

For external party usage. Please refer to Data Model for more details.

custom1string

generic custom reference

Possible values: <= 255 characters

custom2string

generic custom reference

Possible values: <= 255 characters

custom3string

generic custom reference

Possible values: <= 255 characters

deal object
Details of the deal. Used only for 3RI payments (Partial or split shipment and Delayed shipment use cases).
amountnumber<decimal>
The total amount of the deal. The sum of all payments with the same dealReference may not exceed this amount. Used only for Split Shipment flow.
Possible values: >= 0.01, Value must match regular expression ^\d{1,18}\.\d{2}$
Example: 19.99
dealReferencestring
Deal identifier.
Possible values: <= 21 characters
Example: rJIUUztdDPPqh4Zaw98pq
typeCodestring
Deal type
Possible values: <= 6 characters, [3RIPSS, 3RIDS]
Example: 3RIPSS
targetMerchantAccountReferencestring

If provided, the payment is processed in favour of the indicated submerchant account, and the main merchant account number is ignored.

Possible values: <= 127 characters

Example

{
  "merchantKey": "3227a1df-1033-46fd-93bd-x01777339e5b",
  "partnerReference": "5363737832823654334",
  "customerAccountId": "",
  "3DSExemption": {
    "flag": "LVA"
  },
  "shopCountry": "DE",
  "payment": {
    "currencyCode": "EUR",
    "amount": 101.98,
    "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": {
    "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": "CET",
    "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,
        "netAmount": 1536,
        "vatAmount": 64,
        "grossAmount": 1600
      },
      {
        "lineNumber": 2,
        "lineType": "Classic",
        "itemArticleId": "321456",
        "itemName": "tire",
        "quantity": 4,
        "unitPrice": 384,
        "unitVatPrice": 16,
        "unitGrossPrice": 400,
        "vatPercent": 4,
        "netAmount": 1536,
        "vatAmount": 64,
        "grossAmount": 1600
      }
    ]
  }
}

Responses

200

Successful response

tip

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

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.

tip

SmartPay API responses now include an ignoredProperties array in the response body, identifying any unused properties that were submitted but not recognized and therefore ignored. The ignoredProperties array is included in both success and error responses for all public API methods that accept a request body. This ensures that merchants are informed about unprocessed fields in their submissions, improves debugging and reduces potential issues in integration. Requests will continue to be processed successfully even if unrecognized fields are included, as long as all mandatory validations are fulfilled.

application/json

Schema

Schema

transactionIdstring

The Transaction ID.

checkoutTokenstring

The Checkout Token.

paymentStatusstring

The status of the payment.

requestTimestring<date-time>

The time of the request.

Example (auto)

{
  "transactionId": "string",
  "checkoutToken": "string",
  "paymentStatus": "string",
  "requestTime": "2024-07-29T15:51:28.071Z"
}

Example

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

400

Bad Request

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.

For error handling, please refer to this section.

application/json

Schema

Schema

messageobject[]

Error messages.

Example (auto)

{
  "message": [
    {}
  ]
}

Example

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

401

Unauthenticated

info

For error handling, please refer to this section.

application/json

Schema

Schema

errorstring
errorDetails object
contextobject
gatewayDescriptionstring
paymentProviderDescriptionstring
message object
oneOf
• string
• string[]
string

Example (auto)

{
  "error": "string",
  "errorDetails": {
    "context": {},
    "gatewayDescription": "string",
    "paymentProviderDescription": "string"
  },
  "message": "string"
}

Example

{
  "traceId": "00-1234567890abcdef0123456789abcdef-0123456789abcdef-00",
  "errors": [
    {
      "message": "You are not authenticated to perform this request.",
      "code": "unauthorized"
    }
  ]
}

403

Forbidden

info

For error handling, please refer to this section.

application/json

Schema

Schema

errorstring
errorDetails object
contextobject
gatewayDescriptionstring
paymentProviderDescriptionstring
message object
oneOf
• string
• string[]
string

Example (auto)

{
  "error": "string",
  "errorDetails": {
    "context": {},
    "gatewayDescription": "string",
    "paymentProviderDescription": "string"
  },
  "message": "string"
}

Example

{
  "traceId": "00-1234567890abcdef0123456789abcdef-0123456789abcdef-00",
  "errors": [
    {
      "message": "You do not have permissions to perform this request.",
      "code": "forbidden"
    }
  ]
}

404

Not Found

info

For error handling, please refer to this section.

application/json

Schema

Schema

errorstring
errorDetails object
contextobject
gatewayDescriptionstring
paymentProviderDescriptionstring
message object
oneOf
• string
• string[]
string

Example (auto)

{
  "error": "string",
  "errorDetails": {
    "context": {},
    "gatewayDescription": "string",
    "paymentProviderDescription": "string"
  },
  "message": "string"
}

Example

{
  "traceId": "00-1234567890abcdef0123456789abcdef-0123456789abcdef-00",
  "errors": [
    {
      "message": "Resource not found.",
      "code": "not_found"
    }
  ]
}

500

Internal Server Error

info

For error handling, please refer to this section.

application/json

Schema

Schema

errorstring
errorDetails object
contextobject
gatewayDescriptionstring
paymentProviderDescriptionstring
message object
oneOf
• string
• string[]
string

Example (auto)

{
  "error": "string",
  "errorDetails": {
    "context": {},
    "gatewayDescription": "string",
    "paymentProviderDescription": "string"
  },
  "message": "string"
}

Example

{
  "traceId": "00-1234567890abcdef0123456789abcdef-0123456789abcdef-00",
  "errors": [
    {
      "message": "Internal server error."
    }
  ]
}