Skip to content
_Nets Easy

    Example for sending a complete Paylink request

    Before you start

    Please make sure you've got a Nets Easy Paylink account, so that you know your Paylink instance name and your API Secret - Integration keys.

    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.

    Scenario

    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[0]=visa) have been replaced by %5B and %5D respectively.

    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&currency=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="amount=8925&vatRate=7.7&currency=CHF&sku=P01122000&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"

    Using the $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: oZip7nkIb0HJsqX/EgIb7hF5aAov9y2bQhTnzs+0iF0=

    This is how the string looks urlencoded: oZip7nkIb0HJsqX%2FEgIb7hF5aAov9y2bQhTnzs%2B0iF0%3D

    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.

    POST "https://api.nets-pay.link/v1.0/Invoice/?instance=INSTANCE_NAME"

    Here is a commandline example for the complete request (calculation of the API Signature included):

    Complete Paylink request - command line example

    apiSignature=`echo -n "amount=8925&vatRate=7.7&currency=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" | openssl dgst -sha256 -hmac "INSTANCE_API_SECRET" -binary | openssl enc -base64`

curl --request POST "https://api.nets-pay.link/v1.0/Invoice/?instance=INSTANCE_NAME" \
  --data-urlencode "amount=8925" \
  --data-urlencode "vatRate=7.7" \
  --data-urlencode "currency=CHF" \
  --data-urlencode "sku=P01122000" \
  --data-urlencode "pm[0]=visa" \
  --data-urlencode "preAuthorization=0" \
  --data-urlencode "reservation=0" \
  --data-urlencode "referenceId=975382" \
  --data-urlencode "title=Test" \
  --data-urlencode "description=Testdescription" \
  --data-urlencode "purpose=This is a test" \
  --data-urlencode "fields[forename][mandatory]=1" \
  --data-urlencode "fields[forename][defaultValue]=Max" \
  --data-urlencode "fields[surname][mandatory]=0" \
  --data-urlencode "fields[surname][defaultValue]=Muster" \
  --data-urlencode "ApiSignature=$apiSignature"

    5. Response

    The response to that request should be {status:success}.

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

    On this page