Example for sending a complete Paylink request
Before you start
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 Nets Easy Paylink account is sufficient.
For our example, let's assume the following scenario: A paylink needs to be created for the following 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"
- as API Signature we define 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& preAuthorization=0& reservation=0& referenceId=975382& title=Test& description=Testdescription& purpose=This+is+a+test& fields%5Bforename%5D%5Bmandatory%5D=1& fields%5Bforename%5D%5BdefaultValue%5D=Max& fields%5Bsurname%5D%5Bmandatory%5D=0& fields%5Bsurname%5D%5BdefaultValue%5D=Muster
2. Calculate API Signature
We now need to calculate the binary hmac hash (API Signature) using the query string and the Nets Easy 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 Nets Easy Paylink account. The same is true for the
instance parameter: in our example we simply used the fictitious value