Data Model
All SmartPay APIs use a unified data model which describes the data objects and properties.
Address
| 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 | No |
| 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. |
Extra Info
| Field | Description | Type | Length | Mandatory |
|---|---|---|---|---|
| productGroup | Product group label | string | 100 | No |
Payment Options
| Payment option code | Payment option |
|---|---|
| AMEX | American Express |
| APPLPAY | Apple Pay |
| BACSDD | Bacs Direct Debit |
| * BNKACCT | Bank Account |
| CRTBANCAIR | Carte Bancaire |
| DISCOVER | Discover |
| GGLPAY | Google Pay |
| GIROPAY | GiroPay |
| IDEAL | IDEAL |
| JCB | JCB |
| MSTRCRD | Mastercard |
| MSTRO | Maestro |
| PAYBBNK | Pay-by-Bank |
| PAYPAL | PayPal |
| PAYU | PayU pay-by link |
| PAYUBLK | BLIK |
| PAYUTWST | TWISTO Pay Later |
| PAYUINST | PayU Installments |
| PREPMNT | Prepayment |
| SEPADDB2B | SEPA Direct Debit B2B |
| * SEPADDCORE | SEPA Direct Debit core |
| VISA | VISA |
| VISADBIT | VISA Debit |
note
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.
info
* Depending on use case, both payment codes SEPADDCORE and BNKACCT are used for SEPA CORE Mandate. Consult your Product Solution Specialist for more details.
Order Management
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 |
| 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
| Field | Description | Type | Length |
|---|---|---|---|
| name | Any additional information linked with the order can be stored as additional data (such as contract numbers, references and internal identification). | String | 100 |
| value | 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
| Field | Description | Type | Length |
|---|---|---|---|
| vatAmount | 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 | 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 | 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 |
Update account
Request objects
| 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. |
Response objects
| 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 |
Compliance data
| 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 | - |
Payment
| 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 |
Consumer
| 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 |
| culture | 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. | 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 |
Business Consumer
| 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 | 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. | 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 |
Custom References
Optional object in Create Checkout API and the Modification APIs. If provided, the fields are visible in the Merchant Panel and reporting.
| 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 |
Criteria
List of custom key-value pairs that the merchant can submit.
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.
The names callBackUrl and redirectUrl will be disregarded.
| Field | Description | Type | Length | Mandatory |
|---|---|---|---|---|
| name | Parameter name. * Example for SEPA B2B: requestedCollectionDate. | string | 50 | Yes |
| value | Parameter value. | string | 100 | Yes |
info
* For SEPA Direct Debit transactions, please consider a requested collection date no earlier than 3 days according to the SEPA organizational guideline.
Mandate management
Mandate - root object
| 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 and SEPA_CORE. | 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 your Product Solution Specialist. | string | 35 | Conditional | Yes |
| creditorAddress | Creditor's address, check with your Product Solution Specialist. 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 API or Update Mandate API 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]*$
Reference Instructions
| 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 |
Debtor bank
| 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 |
Mandate Activation
| 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 |
Account
| 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 will be stored. | string | 125 | No | Yes |
| billingAddress | Billing address of the consumer. See Address. | object | - | No | Yes |
| isBusinessUser | Set to true if 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 |
Deal
Deal parameters
| 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 |
Error
Validation errors
Validation errors that are returned to the merchant when the validation performed by SmartPay fails - i.e., the transaction is not forwarded to the payment service provider at all.
| Field | Description | Type | Length | Mandatory |
|---|---|---|---|---|
| message | Contains error messages generated by SmartPay. | String or array | - | Yes, in case there is an error. |
Processing errors
Processing errors that are returned when SmartPay validation are passed successfully but the transaction is pronounced unsuccessful by an external provider.
| 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 |
Network token
Network token object
| Field | Description | Type | Length | Mandatory |
|---|---|---|---|---|
| tokenNumber | Network Token PAN. It is stored encrypted, then it is decrypted when displayed. | String | 10 | Yes |
| tokenExpiryMonth | Expiry month of the network token. | String | 2 | Yes |
| tokenExpiryYear | Expiry year of the network token. | String | 2 | Yes |
Network token with Cryptogram
| Field | Description | Type | Length | Mandatory |
|---|---|---|---|---|
| tokenNumber | Network Token PAN. It is stored encrypted; then it is decrypted when displayed. | String | 10 | Yes |
| tokenExpiryMonth | Expiry month of the network token. | String | 2 | Yes |
| tokenExpiryYear | Expiry year of the network token. | String | 2 | Yes |
| cryptogram | The cryptogram generated by the network token service. Example: "ACLVjiemjIDEAATf4U8pAAADFA==". | String | 100 | Yes |
3dsExemption and exemption
| Field | Description | Type | Length | Mandatory |
|---|---|---|---|---|
| flag | Exemption type, currently supported value: "LVA" (Low Value Amount). | Enum | 3 | No |