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 needs 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.

important

For transactions using Apple Pay or Google Pay™, please consult the respective integration pages for details on required domain configuration and button styling parameters within the object criteria.

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

required

merchantKey stringrequired

Possible values: <= 36 characters

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

partnerReference string

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

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

customerAccountId customerAccountId (string)

Possible values: <= 255 characters

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

3DSExemption

object

3DS exemption data

flag string

Possible values: [LVA]

shopCountry string

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

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

payment

object

required

The payment amount to be charged against the payment option.

amount decimalrequired

currencyCode stringrequired

Possible values: <= 3 characters

description stringrequired

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 [

destinationReference stringrequired

Possible values: <= 127 characters

Destination merchant account alias

]

templateContext object

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

billingAddress

object

required

Billing address of the consumer.

addressLine1 stringrequired

Possible values: <= 60 characters

Street name.

addressLine2 string

Possible values: <= 60 characters

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

addressLine3 string

Possible values: <= 60 characters

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

city stringrequired

Possible values: <= 50 characters

The city or localitly of the address.

countryCode stringrequired

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

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

number string

Possible values: <= 10 characters

The house or building number corresponding to the street address.

postCode stringrequired

Possible values: <= 10 characters

The postal or ZIP code of the address.

state string

Possible values: <= 3 characters

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

shippingAddress

object

Shipping address of the consumer.

addressLine1 stringrequired

Possible values: <= 60 characters

Street name.

addressLine2 string

Possible values: <= 60 characters

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

addressLine3 string

Possible values: <= 60 characters

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

city stringrequired

Possible values: <= 50 characters

The city or localitly of the address.

countryCode stringrequired

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

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

number string

Possible values: <= 10 characters

The house or building number corresponding to the street address.

postCode stringrequired

Possible values: <= 10 characters

The postal or ZIP code of the address.

state string

Possible values: <= 3 characters

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

consumer

object

required

Consumer's personal data, in case the consumer is a physical person.
Mandatory, unless businessConsumer is provided.
consumer and businessConsumer objects may not be submitted together.

culture string

Possible values: <= 5 characters

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.

dateOfBirth date

Possible values: <= 10 characters, Value must match regular expression ^\d{4}-\d{2}-\d{2}$

Date of birth. Format - YYYY-MM-DD. Mandatory for payment option registration flow. Minimum date allowed is 1900-01-01

emailAddress emailrequired

Possible values: <= 255 characters

Customer email address for any notification

firstName stringrequired

Possible values: <= 60 characters

Person first name

gender string

Possible values: <= 6 characters

Person gender

homePhone string

Possible values: <= 30 characters

Person's home phone number (including the country code)

lastName stringrequired

Possible values: <= 60 characters

Person last name

merchantCustomerId string

Possible values: <= 255 characters

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.

middleName string

Possible values: <= 60 characters

The customer's middle name

mobilePhone string

Possible values: <= 30 characters

Person's mobile phone number (including the country code)

taxId string

Possible values: <= 30 characters

Person's tax identification number

timezone string

Possible values: <= 50 characters

Preferred timezone name

title string

Possible values: <= 3 characters

Person title

workPhone string

Possible values: <= 30 characters

Person's work phone number (including the country code)

businessConsumer

object

required

Company data, in case the consumer is a business or a legal entity.
Mandatory, unless consumer is provided.
consumer and businessConsumer objects may not be submitted together.

companyName stringrequired

Possible values: <= 100 characters

Name of the legal entity

companyRegistrationCountryCode string

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

Company registration country ISO2 or ISO3 code

companyRegistrationNumber string

Possible values: <= 50 characters

Company registration number

companyType stringrequired

Possible values: <= 100 characters

culture string

Possible values: <= 5 characters

emailAddress stringrequired

Possible values: <= 255 characters

Customer email address for any notification

taxId string

Possible values: <= 30 characters

Person's tax identification number

order

object

Purchased order details.

externalOrderReference stringrequired

Possible values: <= 225 characters

lines

orderLine[]

required

Array [

additionalData

object[]

Array [

name string

Possible values: <= 100 characters

value string

Possible values: <= 255 characters

]

lines

object[]

List of purchased items associated with the order.

Array [

lineNumber integerrequired

Sequential line number of the item in the order.

itemArticleId stringrequired

Possible values: <= 64 characters

Unique identifier or SKU of the purchased item.

itemName stringrequired

Possible values: <= 255 characters

Name or description of the purchased item.

quantity integerrequired

Quantity of the item purchased.

unitPrice decimalrequired

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

unitVatPrice decimal

VAT amount per unit item.

unitGrossPrice decimalrequired

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

vatPercent decimalrequired

Possible values: <= 100

VAT percentage applied to the item.

netAmount decimalrequired

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

vatAmount decimalrequired

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

grossAmount decimalrequired

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

]

totals

object

grossAmount decimal

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

netAmount decimal

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

vatAmount decimal

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

extraInfo

object

Payment extra information to define the product group, to display different set of payment options (Card, SEPA, PayPal...) for different products.

customerGroup string

Possible values: <= 100 characters

In case customer group rule is defined in channel configuration, this value is used for channel evaluation

productGroup string

Possible values: <= 100 characters

In case customer group rule is defined in channel configuration, this value is used for channel evaluation

criteria

object[]

List of custom key-value pairs that the merchant can submit.
The names callBackUrl and redirectUrl will be disregarded.
For transactions using Apple Pay or Google Pay™, please consult the respective integration pages for details on required domain configuration and button styling parameters within this object.

Array [

name stringrequired

Possible values: <= 50 characters

value stringrequired

Possible values: <= 100 characters

]

customReferences

object

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

custom1 string

Possible values: <= 255 characters

generic custom reference

custom2 string

Possible values: <= 255 characters

generic custom reference

custom3 string

Possible values: <= 255 characters

generic custom reference

deal

object

Details of the deal. Used only for 3RI payments (Partial or split shipment and Delayed shipment use cases).

amount decimal

Possible values: >= 0.01, Value must match regular expression ^\d{1,18}\.\d{2}$

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.

dealReference string

Possible values: <= 21 characters

Deal identifier.

typeCode string

Possible values: <= 6 characters, [3RIPSS, 3RIDS]

Deal type

targetMerchantAccountReference string

Possible values: <= 127 characters

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

Responses

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 log as all mandatory validations are fulfilled.

application/json

Schema
Example (from schema)
Example

Schema

transactionId string

The Transaction ID.

checkoutToken string

The Checkout Token.

paymentStatus string

The status of the payment.

requestTime date-time

The time of the request.

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

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

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
Example (from schema)
Example

Schema

message object[]

Error messages.

{
  "message": [
    {}
  ]
}

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

Unauthenticated

info

For error handling, please refer to this section.

application/json

Schema
Example (from schema)
Example

Schema

error string

errorDetails

object

context object

gatewayDescription string

paymentProviderDescription string

message

object

oneOf

MOD1
MOD2

string

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

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

Forbidden

info

For error handling, please refer to this section.

application/json

Schema
Example (from schema)
Example

Schema

error string

errorDetails

object

context object

gatewayDescription string

paymentProviderDescription string

message

object

oneOf

MOD1
MOD2

string

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

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

Not Found

info

For error handling, please refer to this section.

application/json

Schema
Example (from schema)
Example

Schema

error string

errorDetails

object

context object

gatewayDescription string

paymentProviderDescription string

message

object

oneOf

MOD1
MOD2

string

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

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

Internal Server Error

info

For error handling, please refer to this section.

application/json

Schema
Example (from schema)
Example

Schema

error string

errorDetails

object

context object

gatewayDescription string

paymentProviderDescription string

message

object

oneOf

MOD1
MOD2

string

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

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

Create Checkout

/payment/creation

Request​

Header Parameters

Body

Responses​

Request

Responses