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. |
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 |
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.. |
| 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 |
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.
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 |
Deal
| 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 in error details. | 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 |
Extra Info
| Field | Description | Type | Length | Mandatory |
|---|---|---|---|---|
| productGroup | Product group label | string | 100 | No |
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. |
Modification
This object is used to describe the nature of a transactional change applied to the original payment. It indicates the type of operation that was performed post-authorization, such as a capture, cancel or chargeback. For more information, please refer to the Modification APIs page.
| Name | Description | Type |
|---|---|---|
| modificationData | Additional details of the modification, please refer to modificationData. | Object |
| modificationAmount | Requested transaction modification amount information. | Object |
| status | Actualized transaction or refund status after the performed modification. | string |
| error | Text message explaining the error reason in case of failed modification. More details in the error handling section. | Object |
| creationDate | Date and time of the modification processing start. | string |
| lastStatusDate | Date and time of the modification processing completion. | string |
| statusHistory | Contains information about the status transition. | array |
ModificationData
| Field | Description | Type | Mandatory |
|---|---|---|---|
| type | Type of the performed transaction modification. Possible values: • CAPTURE, • CANCELLATION, • CHARGEBACK, • SETTLEMENT, • REFUND. | string | Yes |
| modificationId | This is a unique identifier assigned to a specific modification performed on the original transaction. While the original payment is typically referenced using a paymentId, each subsequent modification, be it a capture, cancel or refund, refund, cancellation or chargeback, is tracked with its own modificationId. This identifier ensures precise traceability of individual actions taken against the same payment. The modificationId can be used for retrieving the status of a modification or for correlating webhook notifications with a particular change event. This setup enables SmartPay to manage complex payment workflows. In Auto-Capture scenario it is the same as transactionId. | string | Yes |
| cancelId | SmartPay internal unique identifier for cancel request. | string | No |
| captureId | SmartPay internal unique identifier for capture request. | string | No |
| refundId | SmartPay internal unique identifier for refund request. | string | No |
| programRefundStatus | Reflects the status of the refund from merchant to Program level in SmartPay. | string | No |
| programRefundErrorMessage | Message in case of error during Program refund. | string | No |
| programRefundId | Stores the refund reference in case the merchant to Program refund was successful. | string | No |
| reconciliationReferenceId | External provider unique transaction identifier - unique reference for capture or cancel, and refund unique reference for refund. | string | No |
| paymentSplitResults | Defines destinations for which the payment was split and their results. | array | No |
| customReferences | A list of custom references submitted by the merchant along with a modification request, please check custom references section for more details. | 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 |
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 |
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 |
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.
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 | - |
3dsExemption and exemption
Object that indicates that the merchant is requesting to skip Strong Customer Authentication (SCA) for the transaction, based on specific exemption rules like low risk or low value.
| Field | Description | Type | Length | Mandatory |
|---|---|---|---|---|
| flag | Exemption type, currently supported value: LVA (Low Value Amount). | Enum | 3 | No |