Skip to main content

Payment Link Creation API

The API method Creates a Payment Link and a linked QR code.

API Parameters

info

The request must have the following headers:

  • Content-Type: application/json
  • Accept-Language: en-US
  • Origin: { Origin }
FieldDescriptionTypeLengthMandatory
instantPaymentA flag, which represents if the order confirmation is required; before continuing with the payment processing.Boolean5Yes
successUrlURL 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.String255No
failureUrlURL 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.String255No
customerAccountIdCustomer Account ID – A unique identifier provided by the integrating merchant by which the user's account can be identified e.g. customer number.

If provided, SmartPay checks if an account exists. If it does it processes the transaction using the account or alternatively it creates a new account using the identifier.

If this parameter is omitted the transaction is processed as a guest payment; without the option to persists the payment option for future payments.
String255No
paymentThe payment amount to be charged against the payment option.PaymentObjectYes
billingAddressBilling address of the consumer.AddressObjectYes
shippingAddressShipping address of the consumer.AddressObjectNo
consumerConsumer's personal information.PersonObjectConditional. Mandatory if "businessConsumer" object is not provided.
businessConsumerBusiness/Company information.businessConsumerObjectConditional. Mandatory if "consumer" object is not provided.
orderOrder details for the payment transaction.OrderObjectNo
targetMerchantAccountReferenceIf provided; the payment is processed in favour of the indicated submerchant account; and the main merchant account number is ignored.String127No
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 Solutions 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.

tip

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

Example

Request

Path:

POST {Base URL}/payment-links

Header:

Content-Type: application/json
Accept-Language: en-US
{
"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": 1,
"itemArticleId":"321456",
"itemName":"tires B",
"quantity":2,
"unitPrice":125,
"unitVatPrice":0,
"unitGrossPrice":125,
"vatPercent":0,
"netAmount":250,
"vatAmount":0,
"grossAmount":250
}
]
}
}
tip

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

Response

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

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.