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
Apple Pay	Yes	Optional	Optional	Yes
Credit cards	Yes	Yes	For physical goods	Yes
Google Pay	Yes	Optional	Optional	Yes
IDEAL	Yes	Yes	Optional	Yes
Pay-by-Bank	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

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.

modificationId stringrequired

Possible values: <= 64 characters

Merchant unique request identifier.

storedPaymentOptionReference string

Possible values: <= 36 characters

Stored payment option reference. Required unless dealReference is provided.

customerAccountId customerAccountId (string)

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.

payment

object

required

The payment amount to be charged against the payment option.

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.

shippingAddress

object

Consumer's shippinh 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

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

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

emailAddress stringrequired

Possible values: <= 255 characters

Customer email address for any notification

taxId string

Possible values: <= 30 characters

Person's tax identification number

orderDetails

object

Order details for the payment transaction.

externalOrderReference stringrequired

Possible values: <= 225 characters

lines

orderLine[]

required

Array [

additionalData

object[]

Array [

name string

Possible values: <= 100 characters

value string

Possible values: <= 255 characters

]

lines

object[]

List of purchased items associated with the order.

Array [

lineNumber integerrequired

Sequential line number of the item in the order.

itemArticleId stringrequired

Possible values: <= 64 characters

Unique identifier or SKU of the purchased item.

itemName stringrequired

Possible values: <= 255 characters

Name or description of the purchased item.

quantity integerrequired

Quantity of the item purchased.

unitPrice decimalrequired

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

unitVatPrice decimal

VAT amount per unit item.

unitGrossPrice decimalrequired

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

vatPercent decimalrequired

Possible values: <= 100

VAT percentage applied to the item.

netAmount decimalrequired

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

vatAmount decimalrequired

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

grossAmount decimalrequired

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

]

totals

object

grossAmount decimal

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

netAmount decimal

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

vatAmount decimal

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

partnerReference string

Possible values: <= 64 characters

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

]

deal

object

Details of the deal. Used only for 3RI payments (Partial/split shipment and Delayed shipment use cases).

amount decimal

Possible values: >= 0.01, Value must match regular expression ^\d{1,18}\.\d{2}$

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.

dealReference string

Possible values: <= 21 characters

Deal identifier.

typeCode string

Possible values: <= 6 characters, [3RIPSS, 3RIDS]

Deal type

targetMerchantAccountReference string

Possible values: <= 127 characters

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

Responses

MIT payment successfully created

info

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

application/json

Schema
Example (from schema)
Example

Schema

partnerReference string

Possible values: <= 64 characters

Merchant-provided unique reference for the transaction.

description string

Possible values: <= 255 characters

Short description of the transaction.

reconcialationReferenceId string

Possible values: <= 64 characters

Payment provider reconciliation identifier.

modificationId string

Possible values: <= 64 characters

Unique identifier for the modification request.

paymentStatus string

Possible values: <= 32 characters, [CREATED, CAPTURED, AUTHORIZATION_PENDING, AUTHORIZATION_COMPLETED, FAILED, CAPTURE_PENDING, CANCELLATION_PENDING, EXPIRED, CANCELLED]

Status of the payment transaction (e.g., AUTHORIZATION COMPLETED).

creationDate date-time

Date and time when the transaction was created, in ISO 8601 format.

lastStatusDate date-time

Date and time when the transaction status was last updated, in ISO 8601 format.

transactionOverview

object

Overview of the transaction.

amount decimal

Authorized transaction amount.

currencyCode string

Possible values: Value must match regular expression ^[A-Z]{3}$

Currency in ISO 4217 format.

mit boolean

Indicates if the transaction was a Merchant Initiated Transaction (MIT).

transactionId uuid

Unique identifier of the transaction.

paymentMethod string

Possible values: <= 32 characters

Payment method used (e.g., VISA, MASTERCARD).

customerAccountId string

Possible values: <= 255 characters

External customer account reference.

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

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

Bad Request

info

For error handling, please refer to this section.

application/json

Schema
Example (from schema)
Example

Schema

description string

Possible values: <= 255 characters

Short description of the transaction.

reconcialationReferenceId string

Possible values: <= 64 characters

Payment provider reconciliation identifier.

modificationId string

Possible values: <= 64 characters

Unique identifier for the modification request.

paymentStatus string

Possible values: <= 32 characters

Status of the payment transaction (e.g., FAILED).

creationDate date-time

Date and time when the transaction was created.

lastStatusDate date-time

Date and time when the transaction status was last updated.

error string

Possible values: <= 255 characters

Reason for transaction failure.

transactionOverview

object

Overview of the failed transaction.

amount decimal

Authorized transaction amount.

currencyCode string

Possible values: Value must match regular expression ^[A-Z]{3}$

Currency in ISO 4217 format.

mit boolean

Indicates if the transaction was a Merchant Initiated Transaction (MIT).

transactionId uuid

Unique identifier of the transaction.

paymentMethod string

Possible values: <= 32 characters

Payment method used (e.g., VISA, MASTERCARD).

customerAccountId string

Possible values: <= 255 characters

External customer account reference.

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

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

Unauthenticated

info

For error handling, please refer to this section.

application/json

Schema
Example (from schema)
Example

Schema

error string

errorDetails

object

context object

gatewayDescription string

paymentProviderDescription string

message

object

oneOf

MOD1
MOD2

string

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

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

Forbidden

info

For error handling, please refer to this section.

application/json

Schema
Example (from schema)
Example

Schema

error string

errorDetails

object

context object

gatewayDescription string

paymentProviderDescription string

message

object

oneOf

MOD1
MOD2

string

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

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

Not Found

info

For error handling, please refer to this section.

application/json

Schema
Example (from schema)
Example

Schema

error string

errorDetails

object

context object

gatewayDescription string

paymentProviderDescription string

message

object

oneOf

MOD1
MOD2

string

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

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

Internal Server Error

info

For error handling, please refer to this section.

application/json

Schema
Example (from schema)
Example

Schema

error string

errorDetails

object

context object

gatewayDescription string

paymentProviderDescription string

message

object

oneOf

MOD1
MOD2

string

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

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

Create MIT Transaction

/payment/mit

Request​

Header Parameters

Body

Responses​

Request

Responses