Payment Link Creation API
The API method Creates a Payment Link and a linked QR code.
API Parameters
The request must have the following headers:
- Content-Type:
application/json - Accept-Language:
en-US - Origin:
{ Origin }
| Field | Description | Type | Length | Mandatory |
|---|---|---|---|---|
| instantPayment | A flag, which represents if the order confirmation is required; before continuing with the payment processing. | Boolean | 5 | Yes |
| successUrl | 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. | String | 255 | No |
| failureUrl | 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. | String | 255 | No |
| customerAccountId | Customer 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. | String | 255 | No |
| payment | The payment amount to be charged against the payment option. | Payment | Object | Yes |
| billingAddress | Billing address of the consumer. | Address | Object | Yes |
| shippingAddress | Shipping address of the consumer. | Address | Object | No |
| consumer | Consumer's personal information. | Person | Object | Conditional. Mandatory if "businessConsumer" object is not provided. |
| businessConsumer | Business/Company information. | businessConsumer | Object | Conditional. Mandatory if "consumer" object is not provided. |
| order | Order details for the payment transaction. | Order | Object | No |
| targetMerchantAccountReference | If provided; the payment is processed in favour of the indicated submerchant account; and the main merchant account number is ignored. | String | 127 | No |
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.
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.
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.
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
}
]
}
}
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"
}
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.