Create a payment from a URL for a QR code (http GET)
Using the ‘createUrl’ command a payment can be created for a specific entity using the supplied values from the URL. Only when this URL is clicked on by the customer, the payment is created and not earlier. The customer gets redirected to the payment directly after it has been created with the supplied values. The <command> value in the API connection URL must be replaced by: createUrl/<entity key>
Attention
If you want to create a payment in the system, do not use this method, but use the ‘create’ method as described in Create API payment. Only use the method as described on this page if you want to send out a QR code.
| URL PARAMETER | DESCRIPTION |
|---|---|
| entity key | Every PayByLink entity within the system has its own unique key. When connecting to the PayByLink system, this key must be supplied as well so PayByLink knows within which entity the payment must be created. |
In this way, you can send out a lot of links to customers and a payment is only created in the PayByLink system when the customer clicks on that link. For instance; if you want to send out 200.000 invoices to customers but you are not sure if the person wants to pay the invoice using PayByLink, you can create 200.000 payment URLs by yourself and only when the customer clicks on this link, a new payment is created in the PayByLink system and the user is redirected to the payment so he can pay instantly. Big advantage; you get invoiced by PayByLink for the payments that were created successfully. So when only 15.000 customers click on the link, your company will only be invoiced for the 15.000 created payments.
Posted values
| PARAMETER NAME | DESCRIPTION |
|---|---|
| mt | With this parameter you can let the API know what mapping template must be used. If left empty: the default payment mapping for that API user or entity is used. |
| u | Valid API user name (mandatory). |
| exu | The URL where the customer is redirected to when the payment is expired. |
| eru | The URL where the customer is redirected to when an error occurs if he clicks on the link (for instance a technical error. Optional if set at API User level). |
| * | You can post any value. Only those values that are used in the mapping template will be used but they are all part of the HASH calculation. |
| h | A SHA256 hash is calculated with all the parameters that are supplied with the password of the API User at the end. The hash is then added as the last parameter. It is the safest to add the complete hash value but it is allowed to only add the first 10 characters of the hash-value because it is unlikely that a change in the parameter results in the same first 10 characters. |
The link to create a payment request always has the same layout
https://testapi.paybylink.com/payment/createUrl/<entity key>?mt=<valid mapping>&u=<valid API username>&exu=<url to ‘payment expired’ page>&eru=<url to ‘error’ page>&…=…&…=…&h=<valid hash>
Example
An example of a valid create-payment-link with URL-encoded parameters could be:
For this example entity an API user exists with the name ‘Secretapiuser’ and the password ‘T3st2016!’.
In this example URL, the following parameters are used:
| PARAMETERS | DESCRIPTION | EXAMPLE VALUE |
|---|---|---|
| Entity key | Part of the URL | 2b2b9bff-0c96-4f33-a20d-c831ac87e571 |
| u | API User name | Secretapiuser |
| mt | Mapping template (optional) | CreatePaymentLinkMapping |
| exu | Expired URL (optional) | www.paybylink.com |
| eru | Error URL (optional) | www.paybylink.com/en/about-us/contact/ |
| CUSTOM PARAMETERS | VALUE |
|---|---|
| L | nl-NL |
| C | EUR |
| A | 28,50 |
| Ex | 2016-02-29 |
| Or | 201601171959 |
| Pn | Belastingaanslag |
| G | M |
| N | Jan Bakker |
| M | jan@paybylink.com |
| P | 06-12345678 |
The hash will then be calculated using a SHA256 calculation over all these fields without the URL-encoding, in the order that they supplied and with the API password ‘T3st2016!’ at the end. This password is NOT supplied via the URL but only known and used on both sides to calculate the SHA256 hash using the supplied values:
This results in the hash value:
73B58BA21342A257B21A96394818B5C5E61071EE6205FF076AD4450631C2EB62
Return values
If the payment could be created successfully, or if a payment already exists, the customer is directly redirected to the payment page unless the payment is expired. Then the customer is redirected to the ‘exu’ URL. If the payment could not be created, the customer is redirected to the ‘eru’ link. All the calls and parameters to and from the API are logged within the PayByLink system.
Shortened-alias
If you want to create a short URL, on production you can also supply all the parameters to the shorter https://spbl.eu URL using the cpu command (which stands for: create payment by url).
Also the values for ‘mt’, ‘exu’ and ‘eru’ can be set at API User level so these can be skipped as well (if set). You could create a short API user name (‘S’ instead of ‘SecretApiUser’ to save space). Furthermore you could skip parameters like ‘language’ and ‘currency’ because these can be set in the mapping. Parameters like ‘product name’, ‘mail address’, ‘phone number’, etc. could be skipped too to only focus on the important values (amount, order id and expiration date).
https://spbl.eu/cpu/2b2b9bff0c964f33a20dc831ac87e571u=S&a=28.50&or=201601171959&ex=20160229&h=CD 92E1875D
