Data Model
Last changes: 12-08-2023
All Subscription APIs use a unified data model which describes the data objects and properties.
| Field | Description | Type | Length | Mandatory |
| billingAddress | Parent element. | Object | - | Yes |
| 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 |
| Field | Description | Type | Length | Mandatory |
| shippingAddress | Parent element. | Object | - | No |
| 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 |
| Field | Description | Type | Length | Mandatory |
| consumer | Parent element. | Object | - | Yes |
| 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 | Culture. 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. | 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 |
| 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 | 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 |
| 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 |
| Field | Description | Type | Length | Mandatory |
| payment | Parent element. | Object | - | Yes |
| 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 |
| Field | Description | Type | Length | Mandatory |
| billingAgreement | Parent element. | Object | - | Yes |
| 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 |
| Field | Description | Type | Length | Mandatory |
| id | Billing Cycle ID, automatically generated by the system Format: "BillingCycle" + "-" + <UUID> | AN | 49 | Yes |
| createdAt | Timestamp of when the Subscription was created Format: yyyy-MM-dd'T'HH:mm:ss.SS'Z | AN | 24 | Yes |
| updatedAt | Timestamp of when the Subscription was last updated Format: yyyy-MM-dd'T'HH:mm:ss.SS'Z | AN | 24 | Yes |
| paidAt | Timestamp of when the Subscription was paid, if applicable
| 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.
| AN | 255 | Yes |
| billingAgreementName | Display name of the payment option which has been stored Example: "Mastercard" | AN | 255 | Yes |
| transactions | Parent element Please refer to the presentation below for "transactions" | Object | - | Yes |
| Field | Description | Type | Length | Mandatory |
| id | Transaction ID, automatically generated by the system Format: "Transaction" + "-" + <UUID> | 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 | String | 255 | Yes |
payment | Parent element Please refer to "payment" object above | Object | - | Yes |
| billingAddress | Parent element Please refer to "billingAddress" object above | Object | - | Yes |
| shippingAddress | Parent element Please refer to "shippingAddress" object above | Object | - | Yes |
| consumer | Please refer to "consumer" object above | Object | - | Yes |
| transactionLogs | Parent element Please refer to the presentation below for "transactionLogs" | Object | - | Yes |
| Field | Description | Type | Length | Mandatory |
| id | Transaction Log ID, automatically generated by the system Format: "TransactionLog" + "-" + <UUID> | String | 51 | Yes |
| createdAt | Timestamp of when the transaction log was created Format: yyyy-MM-dd'T'HH:mm:ss.SS'Z | String | 24 | Yes |
| updatedAt | Timestamp of when the transaction log was last updated Format: yyyy-MM-dd'T'HH:mm:ss.SS'Z | String | 24 | Yes |
| status | Status of the retried transaction | String | 255 | Yes |
| description | Description of the retry result | String | 255 | Yes |
Collection of additional request parameters.
| Field | Description | Type | Length | Mandatory |
| name | Parameter name | String | 50 | Yes |
| value | Parameter value | String | 100 | Yes |