Documentazione
Documentazione
Link per il pagamento

1What are payment links?

Payment links help to collect payments when there is no backend / shop available for processing the payments on the merchant side. Therefore, payment links allow you as a merchant to collect payments without any server side programming. The payment is created through invoking an URL with specific parameters. The parameters are regular HTTP GET or POST parameters. For example: the billing address will be taken from the parameters in the HTTP request to the URL.

The payment links can be used for a wide range of uses cases. The following list gives you a non-conclusive list of uses cases:

  • If you want to sell a simple product on your website but you do not want to implement any backend or use a shopping cart for product management or stock management, you can use these payment links. This can be a very good solutions in order to process flash sales where you do not want to create a shop, static content websites, etc. In case you use payment links you can put a simple HTML form on your website, which points to our platform that processes the payment and checks the billing details. In addition, you can set a limit in terms of purchases for this particular product. The product and all the shipping costs can be predefined within the payment link. All confirmation email messages can be sent by our system.

  • In case you want to collect donations on your website, you can put a simple form on your website, which is pointing to our platform. The amount can be set dynamically within the form hosted on your website. You can collect any contact details and store those data in our system if you like to. All e-mails will be sent from our system. You can adjust and customize them as you wish.

Note
 Please use Charge Flows in case you want to collect payments via email and you do not want to care about sending multiple e-mails and managing different reminder levels when your client does not click on the link.

2How can I setup a payment link?

Go to Space > Payment Links > Create and provide the required data. If you have to setup numerous payment links in an automated way, you may consider using the payment link web service.

A name is required for creating the payment link as it is shown in the admin interface. Any other additional details are optional. However, in case you do not provide this kind of information it may be altered by the user. So if you want to collect the payments only in a specific currency you have to provide this detail. Otherwise we will take the currency you provided within the request to the URL. The same applies also for the line items: If they are not provided, we take the ones provided within the request.

Note
 The request can be altered by the buyer and the charged amount may be differ from what you have intended.

3How can I use a payment link? How can I integrate it into my website?

Once you have created a payment link you can take the provided URL and start invoking it. Depending on how you have setup the payment link, you have to provide additional parameters in the request which invokes the payment link URL.

If you want to use a form on your website to invoke it you can do it like this:

<form action="<< put here payment link url >>" method="POST">

	<input type="text" name="billingAddress[givenName]" placeholder="Given Name" />
	<input type="text" name="billingAddress[familyName]" placeholder="Family Name" />
	<input type="text" name="billingAddress[street]" placeholder="Street" />
	<input type="text" name="billingAddress[postcode]" placeholder="Postcode" />
	<input type="text" name="billingAddress[city]" placeholder="City Name" />
	<input type="text" name="billingAddress[country]" placeholder="Country Code" />

	<input type="hidden" name="lineItems[0][uniqueId]" value="test" />
	<input type="hidden" name="lineItems[0][sku]" value="test" />
	<input type="hidden" name="lineItems[0][name]" value="Test" />
	<input type="hidden" name="lineItems[0][amountIncludingTax]" value="10.87" />
	<input type="hidden" name="lineItems[0][type]" value="PRODUCT" />
	<input type="hidden" name="lineItems[0][quantity]" value="1" />

	<input type="hidden" name="metaData[additionalData]" value="Further data you want to store along the transaction." />

	<input type="hidden" name="currency" value="CHF" />

	<!-- Further parameters as you need. -->

	<input type="submit" value="Pay" />
</form>

We recommend to use the method POST and not GET because the form parameter will be appended to the URL. The URL length cannot be longer than 2000 chars because some browsers do not support it. So by using POST you will not run into such issues.

4What parameters can I send?

In essence, you can send any parameter you can send through the web service API when you create a transaction. Essentially, the JSON has to be mapped into a format which can be produced by regular HTML forms. The data has to be transmitted in UTF-8 encoding. We describe the parameters and their format below:

4.1Billing Address and Shipping Address

The billing and shipping address have the same fields. When an address is provided, we validate if a minimal set of fields are provided, which allows a delivery. The required parameters and their format depend on the country. Below, you can find a list of all fields, which are required for an address:

  • country: The ISO 3166-1 two letter country code determines how the address is validated.

  • givenName: The given name contains the name of the customer’s given name.

  • familyName: The family name contains the name of the customer’s family name.

  • street: The street name including any street number etc. of the address.

  • postCode: The post code of the address is normally required.

  • city: The name of the city is normally also required.

Please see also address model definition for more information on which fields are also available and how we validate them.

To simplify address validation you can embed our JavaScript library which allows to validate the address directly on your website. You may want to take a look into the address validation documentation. The address validation provides also the option to fetch the available country states and countries. This allows to provide a select input field to the buyer from which the allowed options can be selected from. Additionally we indicate within the country list also which fields are required depending on the country. This allows to update the form to mark the country dependent fields as required.

The mentioned fields need to be used with either the billingAddress or the shippingAddress prefix.

4.2Customer Details

You can provide a parameter customerEmailAddress which contains the email address of the customer. We will send any email message to this email address. Any further detail about the customer should be provided within the shipping or billing address.

The customerId cannot be provided since it is used for processing one-click payments we ignore this request parameter.

4.3Line Items

When you do not provide the line items within the payment link, you have to provide them through the request. A line item requires at least the following properties:

  • amountIncludingTax: The amount of the line items including the tax.

  • name: The name of the line item, which is shown within the documents and e-mails.

  • quantity: The quantity of the line items. The unit price is calculated by dividing the amountIncludingTax by the quantity.

  • type: The type of the line item indicates what the item is. Possible types: PRODUCT, SHIPPING, DISCOUNT or FEE

  • uniqueId: The unique ID identifies the line item within a single transaction.

The line item can have further properties. The line item model definition provides further details about the other properties. Below you find an example of a line item:

<input type="hidden" name="lineItems[0][uniqueId]" value="t-shirt-123" />
<input type="hidden" name="lineItems[0][sku]" value="t-shirt-red-36" />
<input type="hidden" name="lineItems[0][name]" value="T-Shirt" />
<input type="hidden" name="lineItems[0][amountIncludingTax]" value="40.85" />
<input type="hidden" name="lineItems[0][taxes][0][title]" value="MwSt." />
<input type="hidden" name="lineItems[0][taxes][0][rate]" value="19" />
<input type="hidden" name="lineItems[0][shippingRequired]" value="true" />
<input type="hidden" name="lineItems[0][attributes][color][label]" value="Color" />
<input type="hidden" name="lineItems[0][attributes][color][value]" value="Red" />
<input type="hidden" name="lineItems[0][attributes][size][label]" value="Size" />
<input type="hidden" name="lineItems[0][attributes][size][value]" value="36" />

If you want to send more than one line item, you need to repeat the properties and increase the index by one.

It is important to understand that providing the line items through the request will allow the buyer to modify them. We cannot not prevent this. This implies that every transaction has to be checked that the amount has not be altered by the buyer.

4.4Currency

The currency can be provided in the parameter currency. When it is already defined in the payment link, the currency sent in the request will be ignored.

When the payment link defines the line items and they are not in the request, the currency is required to be defined on the payment link.

4.5Failed and Success Page

When the transaction has been authorized or when it has been failed, the user can be redirected to a dedicated page. In case nothing has been specified, the user will be redirected to the default page.

The parameter failedUrl defines the URL to which the user is forwarded to when the payment fails. The parameter successUrl defines the URL to which the user is forwarded to when the payment was authorized successfully.

Note
 You should make sure to use an absolute URL, not a relative URL.

4.6Merchant Reference

To provide a merchant reference you can use the parameter merchantReference. The merchant reference will be displayed in the transaction overview. It can also be used to search for a particular transaction.

It is important to understand that this merchantReference may be changed by the buyer and as such you should consider this fact in your processes you setup.

4.7Additional Information

In case you need to store further data along the transaction, you can do so by using the field metaData. It allows to store further key-value pairs. For example, if you want to store in the key comment a comment about the purchase you can do it by passing in the parameter metaData[comment] a comment. There are some limits applied onto the meta data. Please find more details in the meta data section of the web service API.

4.8Control the Availability by Date and Time

The availability of the payment link can be controlled with the availableFrom and availableUntil parameters. Those parameters are interpreted the same way as the corresponding options on the payment link. However if provided through the payment link the buyer may by pass them. If they need to be enforced in a way that the buyer cannot manipulate them it is required to use the corresponding options on the payment link itself.

The accepted dates for availableFrom and availableUntil have to be in the format ISO 8601. For example:

  • 2018-05-01

  • 2018-08-09T10:10:10

  • 2018-08-09T10:10:10+02:00

In case the date does not contain a time zone the UTC time zone is assumed. It is important that you may need to encode the date in the URL format.

5How do I handle the validation?

We validate the form data. However, we have to indicate the failure on a dedicated page, which is not optimal for the user experience. We recommend using the address validation to validate the address in the browser before submitting the form to the payment link URL. The address validation provides also the facilities to retrieve the countries and country states.

We will validate the input again on the server side. This way we ensure that no corrupted data is processed.

6Can I add general terms and conditions to the payment page?

We recommend to add a check for general terms and conditions to your website form. However, if you want to force the user to accept certain terms and conditions, you may want to use the payment page add-on for the general terms and conditions which forces the user to accept your terms.

7Why can I not use one-click payments with payment links?

One-click payments allow the buyer to store the payment details. For later purchases the buyer does not have to enter the payment details again.

Since we do not authenticate the customer, we cannot allow the customer to pay without entering any payment details. This is why you cannot use the one-click payment feature with payment links. If you activate the one-click payment feature on the payment method, we need to ignore it.