You are here:

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 PARAMETERDESCRIPTION
entity keyEvery 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 NAMEDESCRIPTION
mtWith 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.
uValid API user name (mandatory).
exuThe URL where the customer is redirected to when the mandate is expired.
eruThe 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.
hA 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:

https://testapi.paybylink.com/mandate/createUrl/2b2b9bff-0c96-4f33-a20dc831ac87e571?mt=CreateMandateLinkMapping&u=secretapiuser&exu=https%3a%2f%2fwww.paybylink.com& eru=https%3A%2F%2Fwww.paybylink.com%2Fen%2Fabout-us%2Fcontact%2F&l=nl-NL&c=EUR&a=28%2c50&ex=2016-02-29&mnr=201601171959&pn=Belastingaanslag&g=M&fn=Jan&ln=Bakker&m=jan%40paybylink.com&p=06-12345678&s=Test%20street&nr=28&z=1234AB&cit=Nijmegen&cou=The%20Netherlands& h=19F09D36855B580A24B45D061AFB1189BB380B96AA9B38D6BF00915455C0FBDF


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:

PARAMETERSDESCRIPTIONEXAMPLE VALUE
Entity keyPart of the URL2b2b9bff-0c96-4f33-a20d-c831ac87e571
uAPI User nameSecretapiuser
mtMapping template (optional)CreatePaymentLinkMapping
exuExpired URL (optional)www.paybylink.com
eruError URL (optional)www.paybylink.com/en/about-us/contact/
CUSTOM PARAMETERSVALUE
lnl-NL
cEUR
a28,50
ex2016-02-29
mnr201601171959
pnBelastingaanslag
gM
nJan Bakker
mjan@paybylink.com
p06-12345678
sTest street
nr28
z1234AB
citNijmegen
couThe 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:

2b2b9bff-0c96-4f33-a20d-c831ac87e571CreateMandateLinkMappingSecretapiuserhttps://www.paybylink.comhttps://www.paybylink.com/en/about-us/contactnl-NLEUR28,502016-02-29201601171959BelastingaanslagMJan Bakkerjan@paybylink.com06-12345678Teststreet281234ABNijmegenThe NetherlandsT3st2016!


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). 

This would result in something like this:
https://spbl.eu/cmu/2b2b9bff0c964f33a20dc831ac87e571?u=S&a=28.50&or=201601171959&ex=20160229&h=CD92E1875D
Date updated: 2019-11-20
Trust Guard