Create Subscription Checkout API

Last changes: 01-18-2024

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	Description	Type	Length	Mandatory
merchantKey	The Merchant Key is the unique identifier for your integration, keep this credential secure, do not store client side.	GUID	36	Yes
customerAccountId	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	Yes
selectedStoredPaymentOption	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	No
payment	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	Yes
billingAddress	Billing address of the consumer.	Address	Object	Yes
consumer	Mandatory if "businessConsumer" object is not provided. Consumer's personal information.	consumer	Object	Conditional
businessConsumer	Mandatory if "consumer" object is not provided. Business/Company information.	businessConsumer	Object	Conditional
partnerReference	Merchant internal transaction reference. If provided, enables SmartPay to block cases of double processing	String	64	No
criteria	List of custom key-value pairs that the merchant can submit. the names "callBackUrl" and "redirectUrl" will be disregarded.	Array	Object	No

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