Create MIT Subscription

POST 
/payment/mit/subscription/creation

The API method Create Subscription Checkout initiates the subscription creation request.

info

Financial institution's risk management is applicable on storing and verifying payment options, even though no charge is made at that point in time. Therefore, your consumer's personal information is already required within this initialization request.

important

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 the object criteria.

Request

Header Parameters

Content-Type stringrequired

Must be application/json

Accept-Language stringrequired

Must be be en-US

Origin stringrequired

The origin of the request

User-Agent stringrequired

The client making the request

application/json

Body

required

merchantKey uuidrequired

Possible values: <= 36 characters

The Merchant Key is the unique identifier for your integration. Keep this credential secure, do not store client side.

customerAccountId customerAccountId (string)required

Possible values: <= 255 characters

A unique identifier provided by the integrating merchant by which the user's account can be identified e.g., customer number.

selectedStoredPaymentOption string

Possible values: <= 36 characters

Consumer's stored payment option reference. When provided, SmartPay Widget will pre-select stored option with given reference in the list of options when it gets rendered. Suppresses the 'Default' payment option highlighting and 'Set default' functionality.
If the preselected SPO is deleted during the checkout process, the system will move the selection mark to the default payment option, if one exists. If no payment option is defined, the system will move the selection mark to another available payment option from the list.

payment

object

required

Includes currency, average payment amount of the later MIT transactions and description. Use "0" as amount, in case an average amount cannot be determined.

amount decimalrequired

currencyCode stringrequired

Possible values: <= 3 characters

description stringrequired

Possible values: <= 127 characters

billingAddress

object

required

Consumer's billing address data. See Address in Data model.

addressLine1 stringrequired

Possible values: <= 60 characters

Street name.

addressLine2 string

Possible values: <= 60 characters

Apartment, suite, unit, building, floor or other secondary address information.

addressLine3 string

Possible values: <= 60 characters

Specific delivery instructions, department names, or additional floor information.

city stringrequired

Possible values: <= 50 characters

The city or localitly of the address.

countryCode stringrequired

Possible values: >= 3 characters and <= 3 characters

ISO-3 code of the address country (e.g., DEU for Germany).

number string

Possible values: <= 10 characters

The house or building number corresponding to the street address.

postCode stringrequired

Possible values: <= 10 characters

The postal or ZIP code of the address.

state string

Possible values: <= 3 characters

3-letter code of the address state. Mandatory when countryCode corresponds to Canada or USA.

consumer

object

required

Consumer's personal data, in case the consumer is a physical person. See consumer in Data model.
Conditional. Can be present if businessConsumer is missing from the request.

culture string

Possible values: <= 5 characters

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.

dateOfBirth date

Possible values: <= 10 characters, Value must match regular expression ^\d{4}-\d{2}-\d{2}$

Date of birth. Format - YYYY-MM-DD. Mandatory for payment option registration flow. Minimum date allowed is 1900-01-01

emailAddress emailrequired

Possible values: <= 255 characters

Customer email address for any notification

firstName stringrequired

Possible values: <= 60 characters

Person first name

gender string

Possible values: <= 6 characters

Person gender

homePhone string

Possible values: <= 30 characters

Person's home phone number (including the country code)

lastName stringrequired

Possible values: <= 60 characters

Person last name

merchantCustomerId string

Possible values: <= 255 characters

Consumer/Customer Account Id in the merchant system. When provided into the Create Checkout API, SmartPay will request e-wallet account creation which will have external account reference equals to the given merchantCustomerId value.

middleName string

Possible values: <= 60 characters

The customer's middle name

mobilePhone string

Possible values: <= 30 characters

Person's mobile phone number (including the country code)

taxId string

Possible values: <= 30 characters

Person's tax identification number

timezone string

Possible values: <= 50 characters

Preferred timezone name

title string

Possible values: <= 3 characters

Person title

workPhone string

Possible values: <= 30 characters

Person's work phone number (including the country code)

businessConsumer

object

required

Company data, in case the consumer is a business or a legal entity. See businessConsumer in Data model.
Conditional. Can be present if consumer is missing from the request.

companyName stringrequired

Possible values: <= 100 characters

Name of the legal entity

companyRegistrationCountryCode string

Possible values: >= 2 characters and <= 3 characters

Company registration country ISO2 or ISO3 code

companyRegistrationNumber string

Possible values: <= 50 characters

Company registration number

companyType stringrequired

Possible values: <= 100 characters

culture string

Possible values: <= 5 characters

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.

emailAddress stringrequired

Possible values: <= 255 characters

Customer email address for any notification

taxId string

Possible values: <= 30 characters

Person's tax identification number

partnerReference string

Possible values: <= 64 characters, Value must match regular expression ^[a-zA-Z0-9\-_]+$

Merchant internal transaction reference. If provided, enables SmartPay to block cases of double processing.

criteria

object[]

List of custom key-value pairs that the merchant can submit.
The names callBackUrl and redirectUrl will be disregarded.
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.

Array [

name stringrequired

Possible values: <= 50 characters

value stringrequired

Possible values: <= 100 characters

]

Responses

200

Successful response

info

The Create Subscription Checkout response includes checkoutToken which should be used for web widget rendering.

application/json

Schema

Schema

subscriptionId uuid

Unique identifier for the subscription.

checkoutToken string

Token for web widget rendering.

requestTime date-time

Time of the request.

Example (from schema)

{
  "subscriptionId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "checkoutToken": "string",
  "requestTime": "2024-07-29T15:51:28.071Z"
}

Example

{
  "subscriptionId": "9038cf01-e066-4cf9-b62b-df19b5590eed",
  "checkoutToken": "VpyBoZj54PNRfpWNkQQN7FnTzAb2UcXF4kfRpviAXPxq5WnhHwXIdY3dqRV9MGXM",
  "requestTime": "2023-04-06T14:45:24.429Z"
}

400

Bad Request

info

For error handling, please refer to this section.

If you receive an HTTP status other than 2xx, the request failed. Please try to interpret the response message to correct your request and contact Customer Support in case of further questions.

application/json

Schema

Schema

any

Example (from schema)

{
  "message": {
    "message": [
      {
        "consumer": [
          "Invalid date of birth"
        ]
      }
    ]
  }
}

Example

{
  "message": {
    "message": [
      {
        "consumer": [
          "Invalid date of birth"
        ]
      }
    ]
  }
}

401

Unauthenticated

info

For error handling, please refer to this section.

application/json

Schema

Schema

error string

errorDetails

object

context object

gatewayDescription string

paymentProviderDescription string

message

object

oneOf

MOD1

string

MOD2

Array [

string

]

Example (from schema)

{
  "error": "string",
  "errorDetails": {
    "context": {},
    "gatewayDescription": "string",
    "paymentProviderDescription": "string"
  },
  "message": "string"
}

Example

{
  "traceId": "00-1234567890abcdef0123456789abcdef-0123456789abcdef-00",
  "errors": [
    {
      "message": "You are not authenticated to perform this request.",
      "code": "unauthorized"
    }
  ]
}

403

Forbidden

info

For error handling, please refer to this section.

application/json

Schema

Schema

error string

errorDetails

object

context object

gatewayDescription string

paymentProviderDescription string

message

object

oneOf

MOD1

string

MOD2

Array [

string

]

Example (from schema)

{
  "error": "string",
  "errorDetails": {
    "context": {},
    "gatewayDescription": "string",
    "paymentProviderDescription": "string"
  },
  "message": "string"
}

Example

{
  "traceId": "00-1234567890abcdef0123456789abcdef-0123456789abcdef-00",
  "errors": [
    {
      "message": "You do not have permissions to perform this request.",
      "code": "forbidden"
    }
  ]
}

404

Not Found

info

For error handling, please refer to this section.

application/json

Schema

Schema

error string

errorDetails

object

context object

gatewayDescription string

paymentProviderDescription string

message

object

oneOf

MOD1

string

MOD2

Array [

string

]

Example (from schema)

{
  "error": "string",
  "errorDetails": {
    "context": {},
    "gatewayDescription": "string",
    "paymentProviderDescription": "string"
  },
  "message": "string"
}

Example

{
  "traceId": "00-1234567890abcdef0123456789abcdef-0123456789abcdef-00",
  "errors": [
    {
      "message": "Resource not found.",
      "code": "not_found"
    }
  ]
}

500

Internal Server Error

info

For error handling, please refer to this section.

application/json

Schema

Schema

error string

errorDetails

object

context object

gatewayDescription string

paymentProviderDescription string

message

object

oneOf

MOD1

string

MOD2

Array [

string

]

Example (from schema)

{
  "error": "string",
  "errorDetails": {
    "context": {},
    "gatewayDescription": "string",
    "paymentProviderDescription": "string"
  },
  "message": "string"
}

Example

{
  "traceId": "00-1234567890abcdef0123456789abcdef-0123456789abcdef-00",
  "errors": [
    {
      "message": "Internal server error."
    }
  ]
}

Loading...