Payment Link Creation API

Last changes: 07-03-2023

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	Mandatory	Description	Type	Length
instantPayment	Yes	A flag, which represents if the order confirmation is required, before continuing with the payment processing.	Boolean	5
successUrl	No	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
failureUrl	No	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
customerAccountId	No	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
payment	Yes	The payment amount to be charged against the payment option.	Payment	Object
billingAddress	Yes	Billing address of the consumer.	Address	Object
shippingAddress	No	Shipping address of the consumer.	Address	Object
consumer	Yes	Consumer's personal information.	Person	Object
order	No	Order details for the payment transaction.	Order	Object

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 choosen 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://google.com/",
    "failureUrl": "https://yahoo.com/",
    "payment": {
        "currencyCode": "EUR",
        "amount": 800.2,
        "description": "VWFS*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.int.smartpay.vwfs.io/f69e6ca5bbdc19d23537c7323ddda81ea7bbb74113d1cd27fbd842cf2c6a6f2f",
    "qrCodeUrl": "https://hpp.int.smartpay.vwfs.io/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.

Document version 1.0 - 2022-11-30 - HPP documentation

Previous

Next