Complete example for sending a Checkout Paylink request
The examples above are meant for a Linux command-line. Some adaptation might be necessary for other operating systems.
Before you start
Please make sure that have completed the prerequisite steps outlined from here before you can proceed with this.
This and the following steps are only relevant for you, if you want to automate your Paylink or One-Page-Shop payment processes by using the API. For most cases, the functionality provided through your Checkout Paylink account is sufficient.
For the following example, we will assume this scenario:
A paylink needs to be created with these values:
- Amount is 89,25 CHF, VAT rate is 7.7%
- Visa is offered as the only payment method
- Your product stock keep unit value (SKU) is P01122000
- The page title shown on the payment page is going to be "Test", the description will say "Testdescription" and the purpose will be "The purpose of the payment."
- The contact name is "Max Mustermann"
- The API Signature will consist of the made up value "a12345678"
1. Build Query String
First, we build the query string.
Encoding of HTTP-Query String
The query string has to be (RFC1738)[https://www.ietf.org/rfc/rfc1738.txt] encoded. That means, you have to replace spaces by "+" as in
purpose=This+is+a+test. Also, the left and right square brackets (as in
pm=visa) have been replaced by
For our example, the encoded query string would look like this:
Example for an encoded query string - line breaks added for readability
amount=8925& vatRate=7.7¤cy=CHF& sku=P01122000& pm%5B0%5D=visa&
It is a common error, that the query string is not encoded according to RFC1738 encoding rules.
2. Calculate API Signature
We now need to calculate the binary hmac hash (API Signature) using the query string and the Checkout Paylink account's API Secret as a key.
2a) Set the queryString variable (command line example)
$queryString variable from the example above, we now calculate the API Signature. In our example, we use the fictional
a12345678 value as the API Secret:
2b) Calculate API Signature - command line example
digest=`echo -n $queryString| openssl dgst -sha256 -hmac "a12345678" -binary`
In a final step, the API Signature gets encrypted:
2c) openssl encrypt API Signature - command line example
apiSignature=`echo -n $digest| openssl enc -base64`
The result of our example would be:
This is how the string looks urlencoded:
3. Build the Request's Body (Payload)
Now that we have the calculated API Signature, we build the requests payload. The payload consists of name - value pairs, similiar to the ones that we used as query parameter-values for the calculation of the API Signature.
The payload data has to be (url encoded) [http://www.ietf.org/rfc/rfc3986.txt)] and spaces will be percent encoded: "%20".
4. Send the Complete Request
In order to send the complete Paylink request, your
instance Name has to be added to the query's header.
Here is a commandline example for the complete request (calculation of the API Signature included):
The response to that request should be
In our example we have used the made up
a12345678 value as the API key. You need to replace that key with your actual API key from your Checkout Paylink account. The same is true for the
instance parameter: in our example we simply used the fictitious value