Create Payment Link

POST /payment-links

This endpoint creates a payment link and a QR code. The payment link can be used to redirect customers to a payment page, while the QR code can be scanned for quick access to the payment.

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.

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.

info

Please note that if you opt to use the SmartPay default success page, and in case the payment option chosen by the end consumer is 'Pre-payment' or 'Pay Upon Invoice', the transactionReference would be displayed on the success page. The transactionReference is the transaction identifier, that must be used by the end-customer, as a reference/usage (Verwendungszweck), while initiating their bank transfer.

In case you are using your own success page, then this information can be retrieved from the success handler.

info

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

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
Example

Bodyrequired

instantPaymentbooleanrequired

A flag which represents if the order confirmation is required before continuing with the payment processing.

successUrlstring

URL that will be used to redirect the consumer in case the payment is processed successfully. If not provided, the end consumer would be redirected to the SmartPay default success page.

Possible values: <= 255 characters

failureUrlstring

URL that will be used to redirect the consumer in case the payment fails. If not provided, the end consumer would be redirected to the SmartPay default failure page.

Possible values: <= 255 characters

customerAccountIdcustomerAccountId

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

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 shipping 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 objectnullablerequired

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 objectnullablerequired

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

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

order object

Purchased order details.

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

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

{
  "instantPayment": false,
  "successUrl": "https://successexample.com/",
  "failureUrl": "https://failureexample.com/",
  "payment": {
    "currencyCode": "EUR",
    "amount": 800.2,
    "description": "MPS*SMARTPAY*01BA"
  },
  "billingAddress": {
    "addressLine1": "Leopoldstrasse",
    "addressLine2": "line 2",
    "addressLine3": "line 3",
    "number": "244",
    "city": "Munich",
    "postCode": "80807",
    "countryCode": "DE"
  },
  "customerAccountId": "test6gN4aJIR7B",
  "consumer": {
    "lastName": "Johny",
    "firstName": "Doe",
    "emailAddress": "test6gN4aJIR7B@mail.com",
    "dateOfBirth": "1980-10-19"
  },
  "order": {
    "externalOrderReference": "123-333",
    "lines": [
      {
        "lineNumber": 1,
        "itemArticleId": "321456",
        "itemName": "tires A",
        "quantity": 2,
        "unitPrice": 125,
        "unitVatPrice": 0,
        "unitGrossPrice": 125,
        "vatPercent": 0,
        "netAmount": 250,
        "vatAmount": 0,
        "grossAmount": 250
      },
      {
        "lineNumber": 2,
        "itemArticleId": "321456",
        "itemName": "tires B",
        "quantity": 2,
        "unitPrice": 125,
        "unitVatPrice": 0,
        "unitGrossPrice": 125,
        "vatPercent": 0,
        "netAmount": 250,
        "vatAmount": 0,
        "grossAmount": 250
      }
    ]
  }
}

Responses

Successful response

info

The Payment Link Creation response includes the Payment URL and the QR code URL, pointing to the QR code as a PNG image.

info

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
Example (auto)
Example

Schema

idstring

Unique identifier for the payment link.

creationDatestring<date-time>

Date and time when the payment link was created.

paymentUrlstring<uri>

Hosted payment page URL where the customer can complete the payment.

Possible values: <= 512 characters

qrCodeUrlstring<uri>

QR code image URL representing the payment link.

Possible values: <= 512 characters

{
  "id": "string",
  "creationDate": "2024-07-29T15:51:28.071Z",
  "paymentUrl": "string",
  "qrCodeUrl": "string"
}

{
  "id": "f69e6ca5bbdc19d23537c7323ddda81ea7bbb74113d1cd27fbd842cf2c6a6f2f",
  "creationDate": "2023-04-17T10:14:59.742Z",
  "paymentUrl": "https://hpp.cons.smartpay.jpmmps.com/f69e6ca5bbdc19d23537c7323ddda81ea7bbb74113d1cd27fbd842cf2c6a6f2f",
  "qrCodeUrl": "https://hpp.cons.smartpay.jpmmps.com/assets/eef298c1-6ed3-4bf3-a9c0-31e5d96182c7/qrCodes/f69e6ca5bbdc19d23537c7323ddda81ea7bbb74113d1cd27fbd842cf2c6a6f2f.png"
}

Bad Request

info

For error handling, please refer to this section.

application/json

Schema
Example (auto)
Example

Schema

errorstring

errorDetails object

contextobject

gatewayDescriptionstring

paymentProviderDescriptionstring

message object

oneOf

string
string[]

string

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

{
  "traceId": "00-1234567890abcdef0123456789abcdef-0123456789abcdef-00",
  "errors": [
    {
      "message": "Value out of bounds. Value must be between 1 and 100",
      "code": "value_out_of_bounds",
      "property": "someField",
      "context": {
        "minimum": 1,
        "maximum": 100
      }
    }
  ]
}

Unauthenticated

info

For error handling, please refer to this section.

application/json

Schema
Example (auto)
Example

Schema

errorstring

errorDetails object

contextobject

gatewayDescriptionstring

paymentProviderDescriptionstring

message object

oneOf

string
string[]

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 (auto)
Example

Schema

errorstring

errorDetails object

contextobject

gatewayDescriptionstring

paymentProviderDescriptionstring

message object

oneOf

string
string[]

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 (auto)
Example

Schema

errorstring

errorDetails object

contextobject

gatewayDescriptionstring

paymentProviderDescriptionstring

message object

oneOf

string
string[]

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 (auto)
Example

Schema

errorstring

errorDetails object

contextobject

gatewayDescriptionstring

paymentProviderDescriptionstring

message object

oneOf

string
string[]

string

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

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

Create Payment Link

/payment-links

Request​

Header Parameters

Bodyrequired

Responses​

Request

Responses