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 |
| VISAELTRN | VISA Electron |
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.
note
* 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 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 |
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 | 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 |
Custom References
| 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 |
Criterion
Collection of additional request parameters
| Field | Description | Type | Length | Mandatory |
|---|---|---|---|---|
| name | Parameter name Example for SEPA B2B "requestedCollectionDate" | string | 50 | Yes |
| value | Parameter value | string | 100 | Yes |
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 | 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]*$
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 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 |
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 |