Data Model
All Subscription APIs use a unified data model which describes the data objects and properties.
billingAddress
| Field | Description | Type | Length | Mandatory |
|---|---|---|---|---|
| addressLine1 | Billing address line 1. | String | 60 | Yes |
| addressLine2 | Billing address line 2. | String | 60 | No |
| addressLine3 | Billing address line 3. | String | 60 | No |
| number | House number/building number. | String | 10 | Yes |
| city | City name of the billing address. | String | 50 | Yes |
| postCode | Postal code of the address. | String | 10 | Yes |
| countryCode | Country 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). | String | 3 | Yes |
| state | State. Could be 2 or 3 characters depending on the state. This field is mandatory when the countryCode is US, USA, CA or CAN. | String | 3 | No |
shippingAddress
| Field | Description | Type | Length | Mandatory |
|---|---|---|---|---|
| addressLine1 | Billing address line 1. | String | 60 | Yes |
| addressLine2 | Billing address line 2. | String | 60 | No |
| addressLine3 | Billing address line 3. | String | 60 | No |
| number | House number/building number. | String | 10 | Yes |
| city | City name of the billing address. | String | 50 | Yes |
| postCode | Postal code of the address. | String | 10 | Yes |
| countryCode | Country 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) | String | 3 | Yes |
| state | State. Could be 2 or 3 characters depending on the state. This field is mandatory when the countryCode is US, USA, CA or CAN. | String | 3 | No |
consumer
| Field | Description | Type | Length | Mandatory |
|---|---|---|---|---|
| firstName | First name of the consumer. | String | 60 | Yes |
| lastName | Last name of the consumer. | String | 60 | Yes |
| middleName | Middle name of the consumer. | String | 60 | No |
| emailAddress | Email address of the customer. | String | 255 | Yes |
| title | Possible values: Mr, Mrs, Ms. This field is not case sensitive. | String | 3 | Yes |
| 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. (e.g., 1979-12-22). Dummy data acceptable. | YYYY-MM-DD | 10 | Yes |
| gender | Possible values: M, F, D. This field is not case sensitive. | String | 1 | No |
| mobilePhone | Mobile phone of the customer. | String | 30 | No |
| homePhone | Home phone of the customer. | String | 30 | No |
| workPhone | Work phone of the customer. | String | 30 | No |
| taxId | Tax ID. | String | 30 | No |
businessConsumer
| 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 | Customer's 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 |
extraInfo
| Field | Description | Type | Length | Mandatory |
|---|---|---|---|---|
| productGroup | Product group label | string | 100 | No |
customReferences
Optional object in Create and 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 |
payment
| Field | Description | Type | Length | Mandatory |
|---|---|---|---|---|
| recurrentAmount | Recurrent amount to charge the customer. | String | 60 | Yes |
| currencyCode | Currency of the charges. | String | 60 | Yes |
| description | Description of the plan. | String | 60 | No |
billingAgreement
| Field | Description | Type | Length | Mandatory |
|---|---|---|---|---|
| paymentObjectId | PaymentObject used for billing this subscription. | String | 125 | Yes |
| id | UUID of the billing agreement. Format:"BillingAgreement" + "-" + <UUID> (e.g., BillingAgreement-35564da2-3d05-4129-a93d-2f1f9deb0771) | String | 53 | Yes |
| billingAgreementDate | Date 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). | DateTime | 24 | Yes |
| name | Display name of the payment option which has been stored (e.g., Mastercard). | String | 255 | No |
| code | Code of the payment option which has been stored (e.g., MSTRCRD). | String | 255 | Yes |
| carrierNumber | Masked carrier number of the payment instrument which has been stored (e.g., 401288****1881). | String | 255 | No |
| isExpired | Possible values: TRUE, FALSE. If a card is used as a payment option this would show if it is expired or not. | Boolean | 5 | No |
| expiryDate | If a card is used as a payment option this would show its expiry date. Format: MM/YYYY Example: 04/2024 | String | 7 | No |
billingCycles
| Field | Description | Type | Length | Mandatory |
|---|---|---|---|---|
| id | Billing Cycle ID, automatically generated by the system. Format: "BillingCycle" + "-" + <UUID> Example: "BillingCycle-90d9e9bc-fd51-4698-b254-b8a57d3a72d9" | AN | 49 | Yes |
| createdAt | Timestamp of when the Subscription was created. Format: yyyy-MM-dd'T'HH:mm:ss.SS'Z Example: 2021-02-11T15:00:44.718Z | AN | 24 | Yes |
| updatedAt | Timestamp of when the Subscription was last updated. Format: yyyy-MM-dd'T'HH:mm:ss.SS'Z Example: 2021-02-11T15:00:44.718Z | AN | 24 | Yes |
| paidAt | Timestamp of when the Subscription was paid, if applicable Format: yyyy-MM-dd'T'HH:mm:ss.SS'Z Example: 2021-02-11T15:00:44.718Z | AN | 24 | Yes |
| billingDate | Format: YYYY-MM-DD Example: "2021-03-31" | AN | 10 | Yes |
| billingPeriodStart | Format: YYYY-MM-DD Example: "2021-03-01" | AN | 10 | Yes |
| billingPeriodEnd | Format: YYYY-MM-DD Example: "2021-03-31" | AN | 10 | Yes |
| status | Example: Captured, Failed, Error | A | 255 | Yes |
| amount | Amount of the transaction | N | 18.2 | Yes |
| currency | Currency code of the transaction. Format: ISO 4217 Example: "EUR" | A | 3 | Yes |
| 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 email | AN | 255 | Yes |
| billingAgreementName | Display name of the payment option which has been stored. Example: "Mastercard" | AN | 255 | Yes |
transaction
| Field | Description | Type | Length | Mandatory |
|---|---|---|---|---|
| id | Transaction ID, automatically generated by the system. Format: "Transaction" + "-" + <UUID> Example: "Transaction-5f391daa-80a8-4292-96d9-3fdc1a12192b" | String | 48 | Yes |
| customerAccountId | Customer 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. | String | 255 | Yes |
| storedPaymentOptionReference | The stored payment instrument reference. | String | 255 | Yes |
| modificationId | Your unique reference for the requested transaction. Used to distinguish between submits and new retries. | String | 255 | Yes |
| transactionReferenceId | SmartPay transaction Id, could be used to call SmartPay modification APIs (e.g refund). | String | 255 | Yes |
| reconciliationReferenceId | External payment provider unique transaction identifier. | String | 255 | Yes |
| paymentStatus | Status of the transaction. Example: "Captured". | String | 255 | Yes |
| payment | Please refer to "payment" object above. | Object | - | Yes |
| billingAddress | Please refer to "billingAddress" object above. | Object | - | Yes |
| shippingAddress | Please refer to "shippingAddress" object above. | Object | - | Yes |
| consumer | Please refer to "consumer" object above. | Object | - | Yes |
| transactionLogs | Please refer to the presentation below for "transactionLogs". | Object | - | Yes |
transactionLogs
| Field | Description | Type | Length | Mandatory |
|---|---|---|---|---|
| id | Transaction Log ID, automatically generated by the system. Format: "TransactionLog" + "-" + <UUID>Example: "TransactionLog-3c2e60ea-2eb9-4162-bcb1-7034f5d4c27f" | String | 51 | Yes |
| createdAt | Timestamp of when the transaction log was created. Format: yyyy-MM-dd'T'HH:mm:ss.SS'Z Example: 2021-02-11T15:00:44.718Z | String | 24 | Yes |
| updatedAt | Timestamp 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 | String | 24 | Yes |
| status | Status of the retried transaction. | String | 255 | Yes |
| description | Description of the retry result. | String | 255 | Yes |
Criteria
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 |
info
* For SEPA Direct Debit transactions, please consider a requested collection date no earlier than 3 days according to the SEPA organizational guideline.