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: 03-20-2024
All SmartPay APIs use a unified data model which describes the data objects and properties.
| Field | Description | Type | Length | Mandatory |
| addressLine1 | Address line 1. | string | 60 | Yes |
| addressLine2 | Address line 2. | string | 60 | No |
| addressLine3 | Address line 3. | string | 60 | No |
| number | House number. | string | 10 | Yes |
| city | City name. | string | 50 | Yes |
| postCode | Postal code, PIN or ZIP Code of the address. | string | 10 | Yes |
| countryCode | ISO 3166-1 alpha-2 or ISO 3166-1 alpha-3 code of the address country. | string | [2, 3] | Yes |
| state | State or province of the address. Use the State, Province, and Territory Codes for the United States and Canada. | string | 3 | Yes, when countryCode corresponds to United States or Canada. |
| 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
| Field | Description | Type | Length | Mandatory |
| externalOrderReference | Order identifier in your system. | string | 225 | Yes |
| lines | Array of order lines | Order line | Yes | |
| totals | An object, which sums up the order totals. | Totals | No |
Order line
| Field | Description | Type | Length | Mandatory |
| lineNumber | Index number of the position in the order. | int | Min: 1 | No |
| lineType | Type of goods or services being offered. Possible values are:"Classic", "Instalment", "Micropayment", "Subscription", "Voucher", "Voucher purchase", "Compensation Voucher", "Dealer Voucher Purchase", "Dealer Voucher Redemption" | string | 50 | No |
| klarnaLineType | Billing model type of the line. Supported values: "Physical" or "Digital". | string | 50 | Yes |
| itemArticleId | Line article number / identifier. | string | 20 | Yes |
| itemName | Line item name in local language. | string | 135 | Yes |
| itemNumber | An item number that is assigned internally. | string | 50 | No |
| quantity | Quantity of the sales items in the position. (e.g. 2) | Decimal | 18.5 | Yes |
| unitPrice | Net sales amount of one unit of the line. (e.g. 90,91€) | Decimal | 18.2 | Yes |
| vatPercent | Tax rate of the sales item in percent. (e.g. 10%) | Decimal | 18.2 | Yes |
| unitVatPrice | Tax amount of one unit of the order position. (e.g. 9,09€ = 90,91€ * 10%) | Decimal | 18.2 | No |
| unitGrossPrice | Gross sales amount of one unit of the order position. (e.g. 100,00€ = 90,91€ + 9,09€) | Decimal | 18.2 | No |
| discountPercent | Any discount percent which is applied on the entire line. | Decimal | 18.2 | No |
| discountAmount | Any discount amount which is applied on the entire line. | Decimal | 18.2 | No |
| netAmount | Net amount of the entire line (e.g. 181,82€ = 2 * 90,91€) | Decimal | 18.2 | Yes |
| vatAmount | Tax price of the position. (e.g. 18,18 = 181,82 * 10%) | Decimal | 18.2 | Yes |
| grossAmount | Gross amount of the entire line.(e.g. 200,00€= 181,82€ + 18,18€) | Decimal | 18.2 | Yes |
| additionalData | Additional data, provided as a list of objects with key/value pairs. | Array of Additional data objects | No |
Additional data
| name | Yes | Any additional information linked with the order can be stored as additional data (such as contract numbers, references and internal identification). | String | 100 |
| value | Yes | The value linked with the name provided. For example - if the name is "contractNumber" then this property will contain the contract number itself. | String | 255 |
Totals
| vatAmount | No | Total VAT amount of the order. If not provided, the sum of all vatAmount properties at line level is used to populate the property. | Decimal | 18,2 |
| netAmount | No | Total net amount of the order. If not provided, the sum of all netAmount properties at line level is used to populate the property. | Decimal | 18,2 |
| grossAmount | No | Total gross amount of the order. If not provided, the sum of all grossAmount properties at line level is used to populate the property. | Decimal | 18,2 |
| Field | Description | Type | Length | Mandatory |
| customerAccountId | Client's identifier of the consumer for which the account will be updated. | String | 255 | Yes |
| consumer | Consumer's personal data, in case the consumer is a physical person. See Consumer. | Object | Yes. Can be present if businessConsumer is missing from the request. | |
| billingAddress | Consumer's billing address data. See Address. | Object | Yes | |
| businessConsumer | Company data, in case the consumer is a business or a legal entity. See BusinessConsumer. | Object | Yes. Can be present if consumer is missing from the Request. |
| Field | Description | Type | Length |
| partnerReference | Partner service call identifier. | String | 64 |
| statusCode | Status code of the account. Possible values are: ACTIVE CLOSED INACTIVE REJECTED | String | 10 |
| accFlowStatusCode | Status code of the account flow | String | 10 |
| twoFAStatusCode | Two Factor Authentication Status Code. Possible values are: 2FADIS-Two Factor Authentication is disabled. 2FANOTCONF- Two Factor Authentication is activated but not configured. 2FAINPROC- Two Factor Authentication is activated and configuration is in process. 2FACONF-Two Factor Authentication is activated and configured. | String | 10 |
| isTwoFASetupCodeRequired | Whether a confirmation of Two-Factor Authentication setup with a verification code is required or not (this code is sent to the user email). | Boolean | |
| providerResponse | External provider data. | Object | |
| providerResponse.complianceData | Compliance data. Check Compliance data below for more info. | Array | |
| requestDateTime | Timestamp of the request in the format defined by ISO 8601. | YYYY-MM-DD | |
| responseCode | The response code. | String | 4 |
| responseDescription | The response description. | String | 512 |
| Field | Description | Type | Length |
| archiveId | Archived check result identifier. | String | 50 |
| trafficLight | The following options are possible: "RED" – hit, "YELLOW" – unsure hit, "GREEN" – no hit. | String | 10 |
| hitType | The following options are possible "SL" – sanctions list, "BL" – black list, "PEP" – publicly exposed person. | String | 10 |
| manualReview | Whether a manual review is required or not. | Boolean | |
| details | List of compliance check details. | Array |
| Field | Description | Type | Length | Mandatory |
| description | 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 | Yes |
| amount | Transaction modification amount | decimal | 18.2 | Yes |
| currencyCode | Transaction modification currency. The 3-letter currency ISO-4217 code. | string | 3 | Yes |
| Field | Description | Type | Length | Mandatory |
| firstName | Person first name. | String | 60 | Yes |
| lastName | Person last name. | String | 60 | Yes |
| middleName | The customer's middle name. | String | 60 | No |
| emailAddress | Customer's email address. | String | 255 | Yes |
| title | Person title [Mr,Ms,Mrs]. | String | 3 | No for guest / Yes for stored payment option, dummy data acceptable |
| culture | Preferred culture code. Consists of ISO 639-1 language code and ISO 3166-1 alpha-2 country code separated by dash. | String | 5 | No |
| dateOfBirth | Date of birth. Format: YYYY-MM-DD | Date | No for guest / Yes for stored payment option, dummy data acceptable | |
| gender | Person gender. | String | 6 | No |
| mobilePhone | Person's mobile phone number (including the country code). | String | 30 | No |
| homePhone | Person's home phone number (including the country code). | String | 30 | No |
| workPhone | Person's work phone number (including the country code). | String | 30 | No |
| taxId | Person's tax identification number. | String | 30 | No |
| Field | Description | Type | Length | Mandatory |
| companyName | Company legal entity name. | String | 100 | Yes |
| companyType | Company legal entity type (e.g. GmbH). | String | 100 | Yes |
| emailAddress | Company email address. | String | 255 | Yes |
| taxId | Tax identification number. | String | 30 | No |
| culture | Preferred culture code. Consists of ISO 639-1 language code and ISO 3166-1 alpha-2 country code separated by dash. | String | 5 | No |
| companyRegistrationNumber | Company registration number | String | 50 | No |
| companyRegistrationCountryCode | ISO 3166-1 alpha-2 or ISO 3166-1 alpha-3 code of the address country. | string | [2, 3] | No |
| Field | Description | Type | Length | Mandatory |
| custom1 | custom reference for external party usage | string | 255 | NO |
| custom2 | custom reference for external party usage | string | 255 | NO |
| custom3 | custom reference for external party usage | string | 255 | NO |
| Field | Description | Type | Length | Mandatory |
| name | Parameter name Example for SEPA B2B "recollectionDate" | string | 50 | Yes |
| value | Parameter value | string | 100 | Yes |
| Field | Description | Type | Length | Mandatory (in create request) | Required prior Activation |
| id | Unique read-only identifier for the object. | string | 39 | Generated by system | n/a |
| object | Read-only string representing the object's type. For mandate "MANDATE" | string | - | Generated by system | n/a |
| createdAt | Date and time when the object were created. Example: 2023-03-02T14:25:59.078Z | string (date-time) | - | Generated by system | n/a |
| mandateScheme | Mandate scheme, currently supported: SEPA_B2B | string | - | Yes | Yes |
| mandateReference | Mandate reference, will be generated by system if generatedReference = true | string | 35 | Conditional | Yes |
| referenceInstructions | Instructions for mandate reference generation. See reference Instructions. | object | - | Yes | Yes |
| MandateStatus | Status of the mandate. CREATED: Mandate created but cannot used for payments. ACTIVE: Mandate active and can be used for payments. CLOSED: Mandate canceled or expired and cannot be used for payments. | string | - | Generated by system | n/a |
| debtorName | Debtor's full name / company name as on the mandate. | string | 70 | No | Yes |
| debtorAddress | Debtor's address information, as printed on the mandate. See Address. | object | - | No | Yes |
| debtorBank | Debtor's bank details. See Debtor bank. | object | - | No | Yes |
| creditorName | Creditor's name. | string | 70 | Conditional | Yes |
| creditorIdentifier | Creditor Identifier to be used with mandate. Check with implementation manager.. | string | 35 | Conditional | Yes |
| creditorAddress | Creditor's address, check with implementation manager. Object details, see address. | object | - | Conditional | Yes |
| acceptance | Mandate activation request object. See Mandate Activation. | object | - | Generated by system | n/a |
| account | See Account. | object | - | No | Yes |
Attributes marked as required for activation need to be stored in the mandate via create mandate or update mandate request prior to requesting activation.
All string-type attributes in mandate management (except in the "account" object) need to be:
- Numbers 0-9
- Characters a-z or A-Z
- Special characters: + ? / - : ( ) . , ' and "space"
Any other character can not be processed by SEPA data exchange and will be removed. Correct data-set can be validated using the regex: ^[0-9a-zA-Z+?/\-:(),.'\s]*$
| Field | Description | Type | Length | Mandatory (in create request) | Required prior Activation |
| mandatePrefix | If specified, this prefix will be used when mandate reference is generated. | string | 14 | No | No |
| Field | Description | Type | Length | Mandatory (in create request) | Required prior Activation |
| iban | Debtor's IBAN. Must conform to IBAN format. | string | 34 | No | Yes |
| bankName | Debtor's bank name. | string | 70 | No | Yes |
| bic | Debtor's bank BIC. | string | 11 | No | Yes |
| Field | Description | Type | Length | Mandatory (in /activate request) |
| id | Unique read-only identifier for the object. | string | 39 | Generated by system |
| object | Read-only string representing the object's type. For mandate "MANDATE_ACTIVATION" | string | - | Generated by system |
| createdAt | Date and time when the object were created. Example: 2023-03-02T14:25:59.078Z | string (date-time) | string (date-time) | Generated by system |
| storedPaymentOptionReference | The "storedPaymentOptionReference" parameter is used to identify the tokenized payment option as part of other API methods. | string | 70 | Generated by system |
| mandateSignedLocation | Mandate signed location, optional, only for offline mandates (mandateAcceptance = OFFLINE. | string | 14 | No |
| mandateDateOfSignature | Mandate date of the signature. Must be in ISO date format (e.g., "YYYY-MM-DD"). | string | 11 | Yes |
| mandateAcceptance | Mandate acceptance. Should be either "ONLINE" or "OFFLINE". | string | - | Yes |
| Field | Description | Type | Length | Mandatory Mandatory (in create request) | Required prior Activation |
| id | Unique read-only identifier for the object. | string | 39 | Generated by system after activation | n/a |
| object | Read-only string representing the object's type. For mandate "CREDENTIAL_VAULT" | string | - | Generated by system after activation | n/a |
| createdAt | Date and time when the object were created. Example: 2023-03-02T14:25:59.078Z | string (date-time) | string (date-time) | Generated by system after activation | n/a |
| customerAccountId | Client's identifier of the consumer for which the mandate shall be stored. | string | 125 | No | Yes |
| billingAddress | Billing address of the consumer. See Address. | object | - | No | Yes |
| isBusinessUser | Set to true of consumer is a legal entity. | boolean | - | No | Yes |
| businessConsumer | BusinessConsumer object, see Business Consumer. | object | - | No | Yes, if isBusinessUser = true |
| consumer | Consumer object. See Consumer. | object | - | No | Yes, if isBusinessUser = false |
| Field | Description | Type | Length | Mandatory |
| amount | 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. | Decimal | 18,2 | For Create Checkout: CONDITIONAL mandatory when typecode="3RIPSS" -- For Create MIT Transaction: NO (will be ignored if submitted) |
| typeCode | Type of the deal. Possible values (enum) are: "3RIPSS" - Partial/Split shipment and "3RIDS" - Delayed shipment | Enum | 6 | For Create Checkout YES -- For Create MIT Transaction: NO (will be ignored if submitted) |
| dealReference | Deal identifier. | String | 21 | For Create Checkout: NO -- For Create MIT Transaction YES |
Validation errors
| Field | Description | Type | Length | Mandatory |
| message | Contains error messages generated by SmartPay. | String or array | Yes, in case there is an error. |
Processing errors
| Field | Description | Type | Length | Mandatory |
| error | Error category code assigned by SmartPay when an external party rejects the payment. | String | Yes, in case there is an error. | |
| errorDetails | Error description as received from the external party. More info below. | Object | No |
Error details
| Field | Description | Type | Length | Mandatory |
| gatewayDescription | Error description, as received from any payment gateway. | String | No | |
| paymentProviderDescription | Error description, as received from the external payment provider behind the payment gateway, if any provided in the response from gateway. | String | No | |
| context | Additional error details, as received from the third party. | Object | No |
Document version 1.7
2024-03-20 - Added Error.
2023-12-18 - Added Deal.
2023-12-04 - added Criteria field.
2023-10-06 - added SEPA mandate managment.
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.