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

required

instantPayment booleanrequired

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

successUrl string

Possible values: <= 255 characters

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.

failureUrl string

Possible values: <= 255 characters

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.

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

required

Consumer's personal data, in case the consumer is a physical person.
Mandatory, unless businessConsumer is provided.
consumer and businessConsumer objects may not be submitted together.

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

required

Company data, in case the consumer is a business or a legal entity.
Mandatory, unless consumer is provided.
consumer and businessConsumer objects may not be submitted together.

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

order

object

Purchased order details.

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).

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

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 (from schema)
Example

Schema

id string

Unique identifier for the payment link.

creationDate date-time

Date and time when the payment link was created.

paymentUrl uri

Possible values: <= 512 characters

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

qrCodeUrl uri

Possible values: <= 512 characters

QR code image URL representing the payment link.

{
  "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 (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": "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 (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 Payment Link

/payment-links

Request​

Header Parameters

Body

Responses​

Request

Responses