Create a mandate request from a URL for a QR code (http GET)
Using the ‘createUrl’ command a mandate request can be created for a specific entity using the supplied values from the URL. When this URL is clicked on, the customer gets redirected to the mandate request 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 mandate request in the system, do not use this method, but use the ‘create’ method as described in 'Create API mandate request'. Only use the method as described in this chapter if you want to send out a QR code to customers and/or if you are not sure that the mandate request will be clicked on by the customer.
| 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 mandate request 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 a mandate, you can create 200.000 mandate request URLs by yourself and only when the customer clicks on this link, a new mandate request is created in the PayByLink system and the user is redirected to the request so he can start the e-mandate. Big advantage; you get invoiced by PayByLink for the mandate requests 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 mandate requests.
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 mandate 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 mandate 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 mandate request always has the same layout:
https://testapi.paybylink.com/mandate/createUrl/<entity key>?mt=<valid mapping>&u=<valid API username>&exu=<url to ‘mandate request expired’ page>&eru=<url to ‘error’ page>&…=…&…=…&h=<valid hash>
Example
An example of a valid create-mandate-request-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 |
| mnr | 201601171959 |
| pn | Belastingaanslag |
| g | M |
| n | Jan Bakker |
| m | jan@paybylink.com |
| p | 06-12345678 |
| s | Test street |
| nr | 28 |
| z | 1234AB |
| cit | Nijmegen |
| cou | The Netherlands |
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:
19F09D36855B580A24B45D061AFB1189BB380B96AA9B38D6BF00915455C0FBDF
Return values
If the mandate request could be created successfully, or if a request with this mandate number already exists, the customer is directly redirected to the mandate request page unless it is expired. If the request is expired, the customer is redirected to the 'exu' URL. If the mandate request 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 cmu command (which stands for: create mandate 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/cmu/2b2b9bff0c964f33a20dc831ac87e571?u=S&a=28.50&or=201601171959&ex=20160229&h=CD92E1875D
