Create MIT Transaction

POST 
/payment/mit

Authorize a payment in a one-step direct flow.

This method allows the creation and performing of a merchant-initiated transaction (MIT). It authorizes (and optionally auto-captures) a MIT transaction.

important

In case of payments to different target merchant accounts in the same marketplace, the target merchant accounts references should be provided by merchant to their dedicated Product Solution Specialist.

The table below shows you the minimum data object requirements per payment option to be provided in checkout API. As SmartPay is handling the payment option selection for you, please always send the full data required.

Payment option	payment	billingAddress	shippingAddress	consumer
Credit cards	Yes	Yes	For physical goods	Yes
IDEAL	Yes	Yes	Optional	Yes
PayPal	Yes	Yes	For physical goods	Yes
PayU	Yes	Yes	Optional	Yes
SEPA DD	Yes	Yes	Optional	Yes

info

Minimum data requirements are determined by regulatory and payment provider requirements. Please reach out to your Product Solution Specialist for further details.

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

Bodyrequired

merchantKeystring<uuid>required

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

Possible values: <= 36 characters

modificationIdstringrequired

Merchant unique request identifier.

Possible values: <= 64 characters

storedPaymentOptionReferencestring

Stored payment option reference. Required unless dealReference is provided.

Possible values: <= 36 characters

customerAccountIdcustomerAccountId

A unique identifier provided by the integrating merchant by which the user's account can be identified e.g., customer number. Required for Create MIT transaction, unless dealReference is provided.

Possible values: <= 255 characters

payment objectrequired

The payment amount to be charged against the payment option.

amountnumber<decimal>required

currencyCodestringrequired

Possible values: <= 3 characters

descriptionstringrequired

Possible values: <= 127 characters

billingAddress objectrequired

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

addressLine1stringrequired

Street name.

Possible values: <= 60 characters

Example: Max-Planck-Straße

addressLine2string

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

Possible values: <= 60 characters

addressLine3string

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

Possible values: <= 60 characters

citystringrequired

The city or localitly of the address.

Possible values: <= 50 characters

Example: Berlin

countryCodestringrequired

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

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

Example: DEU

numberstring

The house or building number corresponding to the street address.

Possible values: <= 10 characters

Example: 30

postCodestringrequired

The postal or ZIP code of the address.

Possible values: <= 10 characters

Example: 14473

statestring

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

Possible values: <= 3 characters

shippingAddress object

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

addressLine1stringrequired

Street name.

Possible values: <= 60 characters

Example: Max-Planck-Straße

addressLine2string

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

Possible values: <= 60 characters

addressLine3string

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

Possible values: <= 60 characters

citystringrequired

The city or localitly of the address.

Possible values: <= 50 characters

Example: Berlin

countryCodestringrequired

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

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

Example: DEU

numberstring

The house or building number corresponding to the street address.

Possible values: <= 10 characters

Example: 30

postCodestringrequired

The postal or ZIP code of the address.

Possible values: <= 10 characters

Example: 14473

statestring

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

Possible values: <= 3 characters

consumer objectnullable
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.
culturestring
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.
Possible values: <= 5 characters
Example: en-EN
dateOfBirthstring<date>
Date of birth. Format - YYYY-MM-DD. Mandatory for payment option registration flow. Minimum date allowed is 1900-01-01
Possible values: <= 10 characters, Value must match regular expression ^\d{4}-\d{2}-\d{2}$
Example: 1989-11-08
emailAddressstring<email>required
Customer email address for any notification
Possible values: <= 255 characters
Example: john.doe@gmail.com
firstNamestringrequired
Person first name
Possible values: <= 60 characters
Example: John
genderstring
Person gender
Possible values: <= 6 characters
Example: Mr
homePhonestring
Person's home phone number (including the country code)
Possible values: <= 30 characters
Example: 496912345678
lastNamestringrequired
Person last name
Possible values: <= 60 characters
Example: Doe
merchantCustomerIdstring
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.
Possible values: <= 255 characters
Example: abcd123
middleNamestring
The customer's middle name
Possible values: <= 60 characters
Example: Robert
mobilePhonestring
Person's mobile phone number (including the country code)
Possible values: <= 30 characters
Example: 496912345678
taxIdstring
Person's tax identification number
Possible values: <= 30 characters
Example: 123456789
timezonestring
Preferred timezone name
Possible values: <= 50 characters
Example: CET
titlestring
Person title
Possible values: <= 3 characters
Example: Mr
workPhonestring
Person's work phone number (including the country code)
Possible values: <= 30 characters
Example: 496912345678
businessConsumer objectnullable

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.

companyNamestringrequired

Name of the legal entity

Possible values: <= 100 characters

companyRegistrationCountryCodestring

Company registration country ISO2 or ISO3 code

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

companyRegistrationNumberstring

Company registration number

Possible values: <= 50 characters

companyTypestringrequired

Possible values: <= 100 characters

culturestring

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.

Possible values: <= 5 characters

Example: en-EN

emailAddressstringrequired

Customer email address for any notification

Possible values: <= 255 characters

taxIdstring

Person's tax identification number

Possible values: <= 30 characters

orderDetails object

Order details for the payment transaction.

externalOrderReferencestringrequired

Possible values: <= 225 characters

lines orderLine[]required

Array [

additionalData object[]

Array [

namestring

Possible values: <= 100 characters

valuestring

Possible values: <= 255 characters

]

lines object[]

List of purchased items associated with the order.

Array [

lineNumberintegerrequired

Sequential line number of the item in the order.

itemArticleIdstringrequired

Unique identifier or SKU of the purchased item.

Possible values: <= 64 characters

itemNamestringrequired

Name or description of the purchased item.

Possible values: <= 255 characters

quantityintegerrequired

Quantity of the item purchased.

unitPricenumber<decimal>required

Unit net price (excluding VAT) of a single item.

Possible values: >= 0

unitVatPricenumber<decimal>

VAT amount per unit item.

Possible values: >= 0

unitGrossPricenumber<decimal>required

Unit gross price (net price + VAT) of a single item.

Possible values: >= 0

vatPercentnumber<decimal>required

VAT percentage applied to the item.

Possible values: >= 0 and <= 100

netAmountnumber<decimal>required

Total net amount for the line (quantity × unit net price).

Possible values: >= 0

vatAmountnumber<decimal>required

Total VAT amount for the line (quantity × unit VAT price).

Possible values: >= 0

grossAmountnumber<decimal>required

Total gross amount for the line (net amount + VAT amount).

Possible values: >= 0

]

]

totals object

grossAmountnumber<decimal>

Total gross amount for the line (net amount + VAT amount).

Possible values: >= 0

netAmountnumber<decimal>

Total net amount for the line (quantity × unit net price).

Possible values: >= 0

vatAmountnumber<decimal>

Total VAT amount for the line (quantity × unit VAT price).

Possible values: >= 0

partnerReferencestring

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

Possible values: <= 64 characters

criteria object[]
List of custom key-value pairs that the merchant can submit.
The names callBackUrl and redirectUrl will be disregarded.
Array [
namestringrequired
Possible values: <= 50 characters
valuestringrequired
Possible values: <= 100 characters
]
deal object
Details of the deal. Used only for 3RI payments (Partial/split shipment and Delayed shipment use cases).
amountnumber<decimal>
The total amount of the deal. The sum of all payments with the same dealReference may not exceed this amount. Used only for Split Shipment flow.
Possible values: >= 0.01, Value must match regular expression ^\d{1,18}\.\d{2}$
Example: 19.99
dealReferencestring
Deal identifier.
Possible values: <= 21 characters
Example: rJIUUztdDPPqh4Zaw98pq
typeCodestring
Deal type
Possible values: <= 6 characters, [3RIPSS, 3RIDS]
Example: 3RIPSS
targetMerchantAccountReferencestring

If provided, the payment is processed in favour of the indicated submerchant account, and the main merchant account number is ignored.

Possible values: <= 127 characters

Example

{
  "merchantKey": "73afeb44-432e-4b91-be37-a6b3d2fb7447",
  "storedPaymentOptionReference": "8ac7a4a1750295aa0175074a2eb366d4",
  "modificationId": "Payment-123",
  "customerAccountId": "Test-123",
  "payment": {
    "currencyCode": "EUR",
    "amount": 50.99,
    "description": "SMP-Transaction-01"
  },
  "billingAddress": {
    "addressLine1": "Leopoldstrasse",
    "number": "244",
    "city": "Munich",
    "postCode": "80807",
    "countryCode": "DE"
  },
  "shippingAddress": {
    "addressLine1": "Leopoldstrasse",
    "number": "244",
    "city": "Munich",
    "postCode": "80807",
    "countryCode": "DE"
  },
  "consumer": {
    "emailAddress": "hells.butcher_001@mail.com",
    "gender": "f",
    "lastName": "Hells",
    "firstName": "Butcher",
    "middleName": "fon",
    "title": "Mrs",
    "culture": "en-de",
    "dateOfBirth": "2000-01-01",
    "mobilePhone": "015xx22-2135466",
    "taxId": "00745948504594"
  },
  "orderDetails": {
    "externalOrderReference": "Test 123",
    "orderPositions": [
      {
        "positionNumber": "1",
        "positionType": "Physical",
        "articleId": "321456",
        "articleName": "tire",
        "quantity": 4,
        "netAmount": 384,
        "taxAmount": 16,
        "grossAmount": 400,
        "taxRatePercent": 4,
        "netPrice": 1536,
        "taxPrice": 64,
        "grossPrice": 1600
      }
    ]
  }
}

Responses

201

MIT payment successfully created

info

The Create Checkout response includes the 36-character GUID of the transaction-ID.

application/json

Schema

Schema

partnerReferencestring
Merchant-provided unique reference for the transaction.
Possible values: <= 64 characters
Example: 5436543345876
descriptionstring
Short description of the transaction.
Possible values: <= 255 characters
Example: SMP-UAT-02*k2t3gn
reconcialationReferenceIdstring
Payment provider reconciliation identifier.
Possible values: <= 64 characters
Example: FJ9wbkRjJZsRYCrjgaGGY
modificationIdstring
Unique identifier for the modification request.
Possible values: <= 64 characters
Example: mod-id-000002
paymentStatusstring
Status of the payment transaction (e.g., AUTHORIZATION_COMPLETED).
Possible values: <= 32 characters, [CREATED, CAPTURED, AUTHORIZATION_PENDING, AUTHORIZATION_COMPLETED, FAILED, CAPTURE_PENDING, CANCELLATION_PENDING, EXPIRED, CANCELLED, SETTLED, CHARGEBACK]
Example: AUTHORIZATION_COMPLETED
creationDatestring<date-time>
Date and time when the transaction was created, in ISO 8601 format.
Example: 2020-12-15T14:35:44.532Z
lastStatusDatestring<date-time>
Date and time when the transaction status was last updated, in ISO 8601 format.
Example: 2020-12-15T14:36:45.031Z
transactionOverview object
Overview of the transaction.
amountnumber<decimal>
Authorized transaction amount.
Example: 35.99
currencyCodestring
Currency in ISO 4217 format.
Possible values: Value must match regular expression ^[A-Z]{3}$
Example: EUR
mitboolean
Indicates if the transaction was a Merchant Initiated Transaction (MIT).
Example: true
transactionIdstring<uuid>
Unique identifier of the transaction.
Example: 8b52a0f0-471b-4721-8677-cf2005ae195f
paymentMethodstring
Payment method used (e.g., VISA, MASTERCARD).
Possible values: <= 32 characters
Example: VISA
customerAccountIdstring
External customer account reference.
Possible values: <= 255 characters
Example: Test-123

Example (auto)

{
  "partnerReference": "5436543345876",
  "description": "SMP-UAT-02*k2t3gn",
  "reconcialationReferenceId": "FJ9wbkRjJZsRYCrjgaGGY",
  "modificationId": "mod-id-000002",
  "paymentStatus": "AUTHORIZATION_COMPLETED",
  "creationDate": "2020-12-15T14:35:44.532Z",
  "lastStatusDate": "2020-12-15T14:36:45.031Z",
  "transactionOverview": {
    "amount": 35.99,
    "currencyCode": "EUR",
    "mit": true,
    "transactionId": "8b52a0f0-471b-4721-8677-cf2005ae195f",
    "paymentMethod": "VISA",
    "customerAccountId": "Test-123"
  }
}

Example

{
  "partnerReference": "5436543345876",
  "description": "SMP-UAT-02*k2t3gn",
  "reconciliationReferenceId": "FJ9wbkRjJZsRYCrjgaGGY",
  "modificationId": "mod-id-000002",
  "paymentStatus": "AUTHORIZATION_COMPLETED",
  "creationDate": "2020-12-15T14:35:44.532Z",
  "lastStatusDate": "2020-12-15T14:36:45.031Z",
  "transactionOverview": {
    "amount": 35.99,
    "currencyCode": "EUR",
    "mit": true,
    "transactionId": "8b52a0f0-471b-4721-8677-cf2005ae195f",
    "paymentMethod": "VISA",
    "customerAccountId": "Test-123"
  }
}

400

Bad Request

info

For error handling, please refer to this section.

application/json

Schema

Schema

descriptionstring
Short description of the transaction.
Possible values: <= 255 characters
Example: SMP-UAT-02*k2t3gn
reconcialationReferenceIdstring
Payment provider reconciliation identifier.
Possible values: <= 64 characters
Example: FJ9wbkRjJZsRYCrjgaGGY
modificationIdstring
Unique identifier for the modification request.
Possible values: <= 64 characters
Example: mod-id-000002
paymentStatusstring
Status of the payment transaction (e.g., FAILED).
Possible values: <= 32 characters
Example: FAILED
creationDatestring<date-time>
Date and time when the transaction was created.
Example: 2020-12-15T14:35:44.532Z
lastStatusDatestring<date-time>
Date and time when the transaction status was last updated.
Example: 2020-12-15T14:36:45.031Z
errorstring
Reason for transaction failure.
Possible values: <= 255 characters
Example: Payment provider failed.
transactionOverview object
Overview of the failed transaction.
amountnumber<decimal>
Authorized transaction amount.
Example: 35.99
currencyCodestring
Currency in ISO 4217 format.
Possible values: Value must match regular expression ^[A-Z]{3}$
Example: EUR
mitboolean
Indicates if the transaction was a Merchant Initiated Transaction (MIT).
Example: true
transactionIdstring<uuid>
Unique identifier of the transaction.
Example: 8b52a0f0-471b-4721-8677-cf2005ae195f
paymentMethodstring
Payment method used (e.g., VISA, MASTERCARD).
Possible values: <= 32 characters
Example: VISA
customerAccountIdstring
External customer account reference.
Possible values: <= 255 characters
Example: Test-123

Example (auto)

{
  "description": "SMP-UAT-02*k2t3gn",
  "reconcialationReferenceId": "FJ9wbkRjJZsRYCrjgaGGY",
  "modificationId": "mod-id-000002",
  "paymentStatus": "FAILED",
  "creationDate": "2020-12-15T14:35:44.532Z",
  "lastStatusDate": "2020-12-15T14:36:45.031Z",
  "error": "Payment provider failed.",
  "transactionOverview": {
    "amount": 35.99,
    "currencyCode": "EUR",
    "mit": true,
    "transactionId": "8b52a0f0-471b-4721-8677-cf2005ae195f",
    "paymentMethod": "VISA",
    "customerAccountId": "Test-123"
  }
}

Example

{
  "description": "SMP-UAT-02*k2t3gn",
  "reconciliationReferenceId": "FJ9wbkRjJZsRYCrjgaGGY",
  "modificationId": "mod-id-000002",
  "paymentStatus": "FAILED",
  "creationDate": "2020-12-15T14:35:44.532Z",
  "lastStatusDate": "2020-12-15T14:36:45.031Z",
  "error": "Payment provider failed.",
  "transactionOverview": {
    "amount": 35.99,
    "currencyCode": "EUR",
    "mit": true,
    "transactionId": "8b52a0f0-471b-4721-8677-cf2005ae195f",
    "paymentMethod": "VISA",
    "customerAccountId": "Test-123"
  }
}

401

Unauthenticated

info

For error handling, please refer to this section.

application/json

Schema

Schema

errorstring
errorDetails object
contextobject
gatewayDescriptionstring
paymentProviderDescriptionstring
message object
oneOf
• string
• string[]
string

Example (auto)

{
  "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

errorstring
errorDetails object
contextobject
gatewayDescriptionstring
paymentProviderDescriptionstring
message object
oneOf
• string
• string[]
string

Example (auto)

{
  "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

errorstring
errorDetails object
contextobject
gatewayDescriptionstring
paymentProviderDescriptionstring
message object
oneOf
• string
• string[]
string

Example (auto)

{
  "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

errorstring
errorDetails object
contextobject
gatewayDescriptionstring
paymentProviderDescriptionstring
message object
oneOf
• string
• string[]
string

Example (auto)

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

Example

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