Create Subscription Checkout API

Last changes: 05-31-2023

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

API Parameters

The request must have the following headers:

Content-Type: application/json

Accept-Language: en-US

Origin: { Origin }

Field	Mandatory	Description	Type	Length
merchantKey	Yes	The Merchant Key is the unique identifier for your integration, keep this credential secure, do not store client side.	GUID	36
customerAccountId	Yes	Customer Account ID – A unique identifier provided by the integrating merchant by which the user’s account can be identified e.g. customer number.	String	255
selectedStoredPaymentOption	No	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.	String	36
payment	Yes	Includes currency, average payment amount of the later MIT transactions and description. Use "0" as amount, in case an average amount can not be determined.	Payment	Object
billingAddress	Yes	Billing address of the consumer.	Address	Object
consumer	Yes	Consumer's personal information.	Person	Object
partnerReference	No	Merchant internal transaction reference. If provided, enables SmartPay to block cases of double processing	String	64

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.

Please refer to our data model for details regarding the referenced objects.

Example

Request

Path:: POST {Base URL}/payment/mit/subscription/creation
Header:: Content-Type: application/json
Accept-Language: en-US

{
    "merchantKey": "73afeb44-432e-4b91-be37-a6b3d2fb7447",
    "customerAccountId": "Test-123",
    "payment": {
        "amount": 0.00,
        "currencyCode": "EUR",
        "description": "SMP*SUBSCR*MIT"
    },
    "billingAddress": {
        "addressLine1": "Leopoldstrasse",
        "city": "München",
        "countryCode": "DE",
        "number": "244",
        "postCode": "80807",
        "homePhone": "333444555"
    },
    "consumer": {
        "dateOfBirth": "1980-01-01",
        "title": "Mr",
        "mobilePhone": "333444555",
        "culture": "en-US",
        "firstName": "John",
        "lastName": "Doe",
        "emailAddress": "john.doe@mail.com"
  }
}

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

Response

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

Response on failure

Status Code:: 400 (Bad Request)
Header:: Content-Type: application/json
Accept-Language: en-US

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

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

Document version 1.0 - 2021-03-10 - initial version

Previous

Next