Skip to main content

Data Model

All SmartPay APIs use a unified data model which describes the data objects and properties.

Address

FieldDescriptionTypeLengthMandatory
addressLine1Address line 1.string60Yes
addressLine2Address line 2.string60No
addressLine3Address line 3.string60No
numberHouse number.string10No
cityCity name.string50Yes
postCodePostal code, PIN or ZIP Code of the address.string10Yes
countryCodeISO 3166-1 alpha-2 or ISO 3166-1 alpha-3 code of the address country.string[2, 3]Yes
stateState or province of the address. Use the State, Province, and Territory Codes for the United States and Canada.string3Yes, when countryCode corresponds to United States or Canada.

Extra Info

FieldDescriptionTypeLengthMandatory
productGroupProduct group labelstring100No

Payment Options

Payment option codePayment option
AMEXAmerican Express
APPLPAYApple Pay
BACSDDBacs Direct Debit
BNKACCT *Bank Account
CRTBANCAIRCarte Bancaire
DISCOVERDiscover
GGLPAYGoogle Pay
GIROPAYGiroPay
IDEALIDEAL
JCBJCB
MSTRCRDMastercard
MSTROMaestro
PAYBBNKPay by Bank
PAYPALPayPal
PAYUPayU pay-by link
PAYUBLKBLIK
PAYUTWSTTWISTO Pay Later
PAYUINSTPayU Installments
PREPMNTPrepayment
SEPADDB2BSEPA Direct Debit B2B
SEPADDCORE *SEPA Direct Debit core
VISAVISA
VISADBITVISA Debit
VISAELTRNVISA 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

FieldDescriptionTypeLengthMandatory
externalOrderReferenceOrder identifier in your system.string225Yes
linesArray of order linesOrder line-Yes
totalsAn object, which sums up the order totals.Totals-No

Order line

FieldDescriptionTypeLengthMandatory
lineNumberIndex number of the position in the order.intMin: 1No
lineTypeType of goods or services being offered. Possible values are:"Classic", "Instalment", "Micropayment", "Subscription", "Voucher", "Voucher purchase", "Compensation Voucher", "Dealer Voucher Purchase", "Dealer Voucher Redemption"string50No
itemArticleIdLine article number / identifier.string20Yes
itemNameLine item name in local language.string135Yes
itemNumberAn item number that is assigned internally.string50No
quantityQuantity of the sales items in the position. (e.g. 2)Decimal18.5Yes
unitPriceNet sales amount of one unit of the line. (e.g. 90,91€)Decimal18.2Yes
vatPercentTax rate of the sales item in percent. (e.g. 10%)Decimal18.2Yes
unitVatPriceTax amount of one unit of the order position. (e.g. 9,09€ = 90,91€ * 10%)Decimal18.2No
unitGrossPriceGross sales amount of one unit of the order position. (e.g. 100,00€ = 90,91€ + 9,09€)Decimal18.2No
discountPercentAny discount percent which is applied on the entire line.Decimal18.2No
discountAmountAny discount amount which is applied on the entire line.Decimal18.2No
netAmountNet amount of the entire line (e.g. 181,82€ = 2 * 90,91€)Decimal18.2Yes
vatAmountTax price of the position. (e.g. 18,18 = 181,82 * 10%)Decimal18.2Yes
grossAmountGross amount of the entire line.(e.g. 200,00€= 181,82€ + 18,18€)Decimal18.2Yes
additionalDataAdditional data, provided as a list of objects with key/value pairs.Array of Additional data objects-No

Additional data

FieldDescriptionTypeLength
nameAny additional information linked with the order can be stored as additional data (such as contract numbers, references and internal identification).String100
valueThe value linked with the name provided. For example - if the name is "contractNumber" then this property will contain the contract number itself.String255

Totals

FieldDescriptionTypeLength
vatAmountTotal VAT amount of the order. If not provided, the sum of all vatAmount properties at line level is used to populate the property.Decimal18,2
netAmountTotal net amount of the order. If not provided, the sum of all netAmount properties at line level is used to populate the property.Decimal18,2
grossAmountTotal gross amount of the order. If not provided, the sum of all grossAmount properties at line level is used to populate the property.Decimal18,2

Update account

Request objects

FieldDescriptionTypeLengthMandatory
customerAccountIdClient's identifier of the consumer for which the account will be updated.String255Yes
consumerConsumer'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.
billingAddressConsumer's billing address data. See Address.Object-Yes
businessConsumerCompany 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

FieldDescriptionTypeLength
partnerReferencePartner service call identifier.String64
statusCodeStatus code of the account. Possible values are: ACTIVE CLOSED INACTIVE REJECTEDString10
accFlowStatusCodeStatus code of the account flowString10
twoFAStatusCodeTwo 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.String10
isTwoFASetupCodeRequiredWhether a confirmation of Two-Factor Authentication setup with a verification code is required or not (this code is sent to the user email).Boolean-
providerResponseExternal provider data.Object-
providerResponse.complianceDataCompliance data. Check Compliance data below for more info.Array-
requestDateTimeTimestamp of the request in the format defined by ISO 8601.YYYY-MM-DD-
responseCodeThe response code.String4
responseDescriptionThe response description.String512

Compliance data

FieldDescriptionTypeLength
archiveIdArchived check result identifier.String50
trafficLightThe following options are possible: "RED" – hit, "YELLOW" – unsure hit, "GREEN" – no hit.String10
hitTypeThe following options are possible "SL" – sanctions list, "BL" – black list, "PEP" – publicly exposed person.String10
manualReviewWhether a manual review is required or not.Boolean-
detailsList of compliance check details.Array-

Payment

FieldDescriptionTypeLengthMandatory
descriptionA 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.string127Yes
amountTransaction modification amountdecimal18.2Yes
currencyCodeTransaction modification currency. The 3-letter currency ISO-4217 code.string3Yes

Consumer

FieldDescriptionTypeLengthMandatory
firstNamePerson first name.String60Yes
lastNamePerson last name.String60Yes
middleNameThe customer's middle name.String60No
emailAddressCustomer's email address.String255Yes
titlePerson title (Mr,Ms,Mrs).String3No for guest / Yes for stored payment option, dummy data acceptable
culturePreferred culture code. Consists of ISO 639-1 language code and ISO 3166-1 alpha-2 country code separated by dash.String5No
dateOfBirthDate of birth. Format: YYYY-MM-DDDate-No for guest / Yes for stored payment option, dummy data acceptable
genderPerson genderString6No
mobilePhonePerson's mobile phone number (including the country code).String30No
homePhonePerson's home phone number (including the country code).String30No
workPhonePerson's work phone number (including the country code).String30No
taxIdPerson's tax identification number.String30No

Business Consumer

FieldDescriptionTypeLengthMandatory
companyNameCompany legal entity name.String100Yes
companyTypeCompany legal entity type (e.g. GmbH).String100Yes
emailAddressCompany email address.String255Yes
taxIdTax identification number.String30No
culturePreferred culture code. Consists of ISO 639-1 language code and ISO 3166-1 alpha-2 country code separated by dash.String5No
companyRegistrationNumberCompany registration numberString50No
companyRegistrationCountryCodeISO 3166-1 alpha-2 or ISO 3166-1 alpha-3 code of the address country.string[2, 3]No

Custom References

FieldDescriptionTypeLengthMandatory
custom1custom reference for external party usagestring255NO
custom2custom reference for external party usagestring255NO
custom3custom reference for external party usagestring255NO

Criterion

Collection of additional request parameters

FieldDescriptionTypeLengthMandatory
nameParameter name Example for SEPA B2B "requestedCollectionDate"string50Yes
valueParameter valuestring100Yes

Mandate management

Mandate - root object

FieldDescriptionTypeLengthMandatory (in create request)Required prior Activation
idUnique read-only identifier for the object.string39Generated by systemn/a
objectRead-only string representing the object's type. For mandate "MANDATE"string-Generated by systemn/a
createdAtDate and time when the object were created. Example: 2023-03-02T14:25:59.078Zstring (date-time)-Generated by systemn/a
mandateSchemeMandate scheme, currently supported: SEPA_B2Bstring-YesYes
mandateReferenceMandate reference, will be generated by system if generatedReference = truestring35ConditionalYes
referenceInstructionsInstructions for mandate reference generation. See reference Instructions.object-YesYes
MandateStatusStatus 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 systemn/a
debtorNameDebtor's full name / company name as on the mandate.string70NoYes
debtorAddressDebtor's address information, as printed on the mandate. See Address.object-NoYes
debtorBankDebtor's bank details. See Debtor bank.object-NoYes
creditorNameCreditor's name.string70ConditionalYes
creditorIdentifierCreditor Identifier to be used with mandate. Check with implementation manager..string35ConditionalYes
creditorAddressCreditor's address, check with implementation manager. Object details, see address.object-ConditionalYes
acceptanceMandate activation request object. See Mandate Activation.object-Generated by systemn/a
accountSee Account.object-NoYes

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

FieldDescriptionTypeLengthMandatory (in create request)Required prior Activation
mandatePrefixIf specified, this prefix will be used when mandate reference is generated.string14NoNo

Debtor bank

FieldDescriptionTypeLengthMandatory (in create request)Required prior Activation
ibanDebtor's IBAN. Must conform to IBAN format.string34NoYes
bankNameDebtor's bank name.string70NoYes
bicDebtor's bank BIC.string11NoYes

Mandate Activation

FieldDescriptionTypeLengthMandatory (in /activate request)
idUnique read-only identifier for the object.string39Generated by system
objectRead-only string representing the object's type. For mandate "MANDATE_ACTIVATION"string-Generated by system
createdAtDate and time when the object were created. Example: 2023-03-02T14:25:59.078Zstring (date-time)string (date-time)Generated by system
storedPaymentOptionReferenceThe "storedPaymentOptionReference" parameter is used to identify the tokenized payment option as part of other API methods.string70Generated by system
mandateSignedLocationMandate signed location, optional, only for offline mandates (mandateAcceptance = OFFLINE).string14No
mandateDateOfSignatureMandate date of the signature. Must be in ISO date format (e.g., "YYYY-MM-DD").string11Yes
mandateAcceptanceMandate acceptance. Should be either "ONLINE" or "OFFLINE".string-Yes

Account

FieldDescriptionTypeLengthMandatory Mandatory (in create request)Required prior Activation
idUnique read-only identifier for the object.string39Generated by system after activationn/a
objectRead-only string representing the object's type. For mandate "CREDENTIAL_VAULT"string-Generated by system after activationn/a
createdAtDate and time when the object were created. Example: 2023-03-02T14:25:59.078Zstring (date-time)string (date-time)Generated by system after activationn/a
customerAccountIdClient's identifier of the consumer for which the mandate shall be stored.string125NoYes
billingAddressBilling address of the consumer. See Address.object-NoYes
isBusinessUserSet to true of consumer is a legal entity.boolean-NoYes
businessConsumerBusinessConsumer object, see Business Consumer.object-NoYes, if isBusinessUser = true
consumerConsumer object. See Consumer.object-NoYes, if isBusinessUser = false

Deal

Deal parameters

FieldDescriptionTypeLengthMandatory
amountThe 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.Decimal18,2For Create Checkout: CONDITIONAL mandatory when typecode="3RIPSS" -- For Create MIT Transaction: NO (will be ignored if submitted)
typeCodeType of the deal. Possible values (enum) are: "3RIPSS" - Partial/Split shipment and "3RIDS" - Delayed shipmentEnum6For Create Checkout YES -- For Create MIT Transaction: NO (will be ignored if submitted)
dealReferenceDeal identifier.String21For 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.

FieldDescriptionTypeLengthMandatory
messageContains 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.

FieldDescriptionTypeLengthMandatory
errorError category code assigned by SmartPay when an external party rejects the payment.String-Yes, in case there is an error.
errorDetailsError description as received from the external party. More info below.Object-No

Error details

FieldDescriptionTypeLengthMandatory
gatewayDescriptionError description, as received from any payment gateway.String-No
paymentProviderDescriptionError description, as received from the external payment provider behind the payment gateway, if any provided in the response from gateway.String-No
contextAdditional error details, as received from the third party.Object-No

Network token

Network token object

FieldDescriptionTypeLengthMandatory
tokenNumberNetwork Token PAN. It is stored encrypted, then it is decrypted when displayed.String10Yes
tokenExpiryMonthExpiry month of the network token.String2Yes
tokenExpiryYearExpiry year of the network token.String2Yes

Network token with Cryptogram

FieldDescriptionTypeLengthMandatory
tokenNumberNetwork Token PAN. It is stored encrypted; then it is decrypted when displayed.String10Yes
tokenExpiryMonthExpiry month of the network token.String2Yes
tokenExpiryYearExpiry year of the network token.String2Yes
cryptogramThe cryptogram generated by the network token service. Example: ACLVjiemjIDEAATf4U8pAAADFA==String100Yes