Please note: Payment option CARDS is returned by SmartPay in case the actual card brand has not been selected by the consumer yet or if it could not be determined.
Data Model
Last changes: 09-21-2022
All SmartPay APIs use a unified data model which describes the data objects and properties.
| Field | Mandatory | Description | Type | Length |
| addressLine1 | Yes | Address line 1. | string | 60 |
| addressLine2 | No | Address line 2. | string | 60 |
| addressLine3 | No | Address line 3. | string | 60 |
| number | Yes | House number. | string | 10 |
| city | Yes | City name. | string | 50 |
| postCode | Yes | Postal code, PIN or ZIP Code of the address. | string | 10 |
| countryCode | Yes | ISO 3166-1 alpha-2 or ISO 3166-1 alpha-3 code of the address country. | string | [2, 3] |
| state | Yes, when countryCode corresponds to United States or Canada. | State or province of the address. Use the State, Province, and Territory Codes for the United States and Canada. | string | 3 |
| Payment option | Payment option code |
| Visa | VISA |
| SEPA DD | BNKACCT |
| PayU | PAYU |
| PayPal | PAYPAL |
| Mastercard | MSTRCRD |
| Klarna pay later | KLARNA_PAY_LATER |
| Klarna pay over time | KLARNA_PAY_OVER_TIME |
| JCB | JCB |
| IDEAL | IDEAL |
| Carte Bancaire | CRTBANCAIR |
| American Express | AMEX |
| Credit Card | CARDS |
Order details
| Field | Mandatory | Description | Type | Length |
| externalOrderReference | Yes | Order identifier in your system. | string | 225 |
| orderPositions | Yes | Array of order items. | Order item | [0..inf] |
Order item
| Field | Mandatory | Description | Type | Length |
| positionNumber | Yes | Index number of the position in the order. | int | Min: 1 |
| positionType | Yes | Billing model type of the position. Supported values: "Physical" or "Digital". | string | 50 |
| articleId | No | Position article number / identifier. | string | 20 |
| articleName | Yes | Position name in local language. | string | 135 |
| quantity | Yes | Quantity of the sales items in the position. (e.g. 2) | Decimal | 18.5 |
| netAmount | Yes | Net sales amount of one unit of the order position. (e.g. 90,91€) | Decimal | 18.4 |
| taxAmount | No | Tax amount of one unit of the order position. (e.g. 9,09€ = 90,91€ * 10%) | Decimal | 18.4 |
| grossAmount | No | Net sales amount of one unit of the order position. (e.g. 100,00€ = 90,91€ + 9,09€) | Decimal | 18.4 |
| taxRatePercent | No | Tax rate of the sales item in percent. (e.g. 10%) | Decimal | 18.5 |
| netPrice | No | Net price of the entire position (e.g. 181,82€ = 2 * 90,91€) | Decimal | 18.4 |
| taxPrice | No | Tax price of the position. (e.g. 18,18 = 181,82 * 10%) | Decimal | 18.4 |
| grossPrice | Yes | Gross price of the position.(e.g. 200,00€= 181,82€ + 18,18€) | Decimal | 18.4 |
| Field | Mandatory | Description | Type | Length |
| description | Yes | A terse description of the good or service being sold i.e. the reason for the payment. This field can be used for referencing purposes and will be shown in Merchant Panel. | string | 127 |
| amount | Yes | Transaction modification amount | decimal | 18.2 |
| currencyCode | Yes | Transaction modification currency. The 3-letter currency ISO-4217 code. | string | 3 |
| Field | Mandatory | Description | Type | Length |
| firstName | Yes | Person first name. | String | 60 |
| lastName | Yes | Person last name. | String | 60 |
| middleName | No | The customer's middle name. | String | 60 |
| emailAddress | Yes | Customer's email address. | String | 255 |
| title | No for guest / Yes for stored payment option, dummy data acceptable | Person title [Mr,Ms,Mrs]. | String | 3 |
| culture | No | Preferred culture code. Consists of ISO 639-1 language code and ISO 3166-1 alpha-2 country code separated by dash. | String | 5 |
| dateOfBirth | No for guest / Yes for stored payment option, dummy data acceptable | Date of birth. Format: YYYY-MM-DD | Date | |
| gender | No | Person gender [m/f/d]. | String | 1 |
| mobilePhone | No | Person's mobile phone number (including the country code). | String | 30 |
| homePhone | No | Person's home phone number (including the country code). | String | 30 |
| workPhone | No | Person's work phone number (including the country code). | String | 30 |
| taxId | No | Person's tax identification number. | String | 30 |
Document version 1.3 -
2021-03-10 - updated description of eMail address field.
2021-03-08 - note regarding payment description added.
2021-01-28 - note regarding CARDS payment option code added.