Skip to main content

Data Model

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

billingAddress

FieldDescriptionTypeLengthMandatory
billingAddressParent element.Object-Yes
addressLine1Billing address line 1.String60Yes
addressLine2Billing address line 2.String60No
addressLine3Billing address line 3.String60No
numberHouse number/building number.String10Yes
cityCity name of the billing address.String50Yes
postCodePostal code of the address.String10Yes
countryCodeCountry code. Could be 2 or 3 characters depending on the format used. Format: ISO 3166 ALPHA-2 or ISO 3166 ALPHA-3 (E.g: DEU, DE)String3Yes
stateState. Could be 2 or 3 characters depending on the state. This field is mandatory when the countryCode is US, USA, CA or CANString3No

shippingAddress

FieldDescriptionTypeLengthMandatory
shippingAddressParent element.Object-No
addressLine1Billing address line 1.String60Yes
addressLine2Billing address line 2.String60No
addressLine3Billing address line 3.String60No
numberHouse number/building number.String10Yes
cityCity name of the billing address.String50Yes
postCodePostal code of the address.String10Yes
countryCodeCountry code. Could be 2 or 3 characters depending on the format used. Format: ISO 3166 ALPHA-2 or ISO 3166 ALPHA-3 (E.g: DEU, DE)String3Yes
stateState. Could be 2 or 3 characters depending on the state. This field is mandatory when the countryCode is US, USA, CA or CANString3No

consumer

FieldDescriptionTypeLengthMandatory
consumerParent element.Object-Yes
firstNameFirst name of the consumer.String60Yes
lastNameLast name of the consumer.String60Yes
middleNameMiddle name of the consumer.String60No
emailAddressEmail address of the customer.String255Yes
titlePossible values: Mr, Mrs, Ms. This field is not case sensitive.String3Yes
cultureCulture. If this value is not provided the browser culture is used. Default culture is English (E.g: de-en). This field is not case sensitive.String5No
dateOfBirthDate of birth. (E.g: 1979-12-22). Dummy data acceptable.YYYY-MM-DD10Yes
genderPossible values: M, F, D. This field is not case sensitive.String1No
mobilePhoneMobile phone of the customer.String30No
homePhoneHome phone of the customer.String30No
workPhoneWork phone of the customer.String30No
taxIdTax IDString30No

businessConsumer

FieldDescriptionTypeLengthMandatory
companyNameCompany legal entity name.String100Yes
companyTypeCompany legal entity type (e.g. GmbH).String100Yes
emailAddressCustomer's 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

extraInfo

FieldDescriptionTypeLengthMandatory
productGroupProduct group labelstring100No

customReferences

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

payment

FieldDescriptionTypeLengthMandatory
paymentParent element.Object-Yes
recurrentAmountRecurrent amount to charge the customer.String60Yes
currencyCodeCurrency of the charges.String60Yes
descriptionDescription of the plan.String60No

billingAgreement

FieldDescriptionTypeLengthMandatory
billingAgreementParent element.Object-Yes
paymentObjectIdPaymentObject used for billing this subscription.String125Yes
idUUID of the billing agreement. Format:"BillingAgreement" + "-" + <UUID> (E.g. BillingAgreement-35564da2-3d05-4129-a93d-2f1f9deb0771)String53Yes
billingAgreementDateDate when the billing agreement was created. This means when a payment instrument was added for the specific subscription. Format: yyyy-MM-dd'T'HH:mm:ss.SS'Z (E.g. 2021-01-26T14:29:05.994Z)DateTime24Yes
nameDisplay name of the payment option which has been stored. (E.g. Mastercard)String255No
codeCode of the payment option which has been stored. (E.g. MSTRCRD)String255Yes
carrierNumberMasked carrier number of the payment instrument which has been stored. (E.g. 401288****1881)String255No
isExpiredPossible values: TRUE, FALSE. If a card is used as a payment option this would show if it is expired or not.Boolean5No
expiryDateIf a card is used as a payment option this would show its expiry date. Format: MM/YYYY Example: 04/2024String7No

billingCycles

FieldDescriptionTypeLengthMandatory
idBilling Cycle ID, automatically generated by the system Format: "BillingCycle" + "-" + <UUID> Example: "BillingCycle-90d9e9bc-fd51-4698-b254-b8a57d3a72d9"AN49Yes
createdAtTimestamp of when the Subscription was created Format: yyyy-MM-dd'T'HH:mm:ss.SS'Z Example: 2021-02-11T15:00:44.718ZAN24Yes
updatedAtTimestamp of when the Subscription was last updated Format: yyyy-MM-dd'T'HH:mm:ss.SS'Z Example: 2021-02-11T15:00:44.718ZAN24Yes
paidAtTimestamp of when the Subscription was paid, if applicable Format: yyyy-MM-dd'T'HH:mm:ss.SS'Z Example: 2021-02-11T15:00:44.718ZAN24Yes
billingDateFormat: YYYY-MM-DD Example: "2021-03-31"AN10Yes
billingPeriodStartFormat: YYYY-MM-DD Example: "2021-03-01"AN10Yes
billingPeriodEndFormat: YYYY-MM-DD Example: "2021-03-31"AN10Yes
statusExample: Captured, Failed, ErrorA255Yes
amountAmount of the transactionN18.2Yes
currencyCurrency code of the transaction Format: ISO 4217 Example: "EUR"A3Yes
shortCardNumber (carrierNumber)This fields value depends on the type of the payment option. Card: this field would be the masked PAN SEPA: this field would contain the masked IBAN PayPal: this field would be the masked emailAN255Yes
billingAgreementNameDisplay name of the payment option which has been stored Example: "Mastercard"AN255Yes

transaction

FieldDescriptionTypeLengthMandatory
idTransaction ID, automatically generated by the system Format: "Transaction" + "-" + <UUID> Example: "Transaction-5f391daa-80a8-4292-96d9-3fdc1a12192b"String48Yes
customerAccountIdCustomer Account ID - A unique identifier provided by the integrating merchant by which the user's account could be identified e.g. customer number For subscription Module, SmartPay checks if an account exists, if so, your end customer would be able to see their previously stored payment instruments, if any.String255Yes
storedPaymentOptionReferenceThe stored payment instrument referenceString255Yes
modificationIdYour unique reference for the requested transaction. Used to distinguish between submits and new retries.String255Yes
transactionReferenceIdSmartPay transaction Id, could be used to call SmartPay modification APIs (e.g refund)String255Yes
reconciliationReferenceIdExternal payment provider unique transaction identifier.String255Yes
paymentStatusStatus of the transaction Example: "Captured"String255Yes
paymentParent element Please refer to "payment" object aboveObject-Yes
billingAddressParent element Please refer to "billingAddress" object aboveObject-Yes
shippingAddressParent element Please refer to "shippingAddress" object aboveObject-Yes
consumerPlease refer to "consumer" object aboveObject-Yes
transactionLogsParent element Please refer to the presentation below for "transactionLogs"Object-Yes

transactionLogs

FieldDescriptionTypeLengthMandatory
idTransaction Log ID, automatically generated by the system
Format: "TransactionLog" + "-" + <UUID>
Example: "TransactionLog-3c2e60ea-2eb9-4162-bcb1-7034f5d4c27f"
String51Yes
createdAtTimestamp of when the transaction log was created
Format: yyyy-MM-dd'T'HH:mm:ss.SS'Z
Example: 2021-02-11T15:00:44.718Z
String24Yes
updatedAtTimestamp of when the transaction log was last updated
Format: yyyy-MM-dd'T'HH:mm:ss.SS'Z
Example: 2021-02-11T15:00:44.718Z
String24Yes
statusStatus of the retried transactionString255Yes
descriptionDescription of the retry resultString255Yes

Criteria

Collection of additional request parameters.

FieldDescriptionTypeLengthMandatory
nameParameter name
Example for SEPA B2B "recollectionDate"
String50Yes
valueParameter valueString100Yes