---
updatedAt: 2025-10-29T09:16:27.000Z
agentTools:
  projectIndex: https://shop-and-pay.readme.io/llms.txt
---

# Getting started

<br />

## Request

The payload data has to be RFC 3986 (<http://www.ietf.org/rfc/rfc3986.txt>) url encoded and spaces will be percent encoded "%20".

The basic URL to our API is: <https://api.shop-and-pay.com/v1.0/:object/:id?instance=:instance>

<Table align={["left","left"]}>
  <thead>
    <tr>
      <th>
        Parameter
      </th>

      <th>
        Value
      </th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>
        object
      </td>

      <td>
        AuthToken | Invoice | Page | Subscription
      </td>
    </tr>

    <tr>
      <td>
        id
      </td>

      <td>
        Only used for request types GET, PUT and DELETE where only one entity gets modified.
      </td>
    </tr>

    <tr>
      <td>
        instance
      </td>

      <td>
        The Shop & Name instance name.  
        If you access your Shop & Pay payment page with example.shop-and-pay.com, the name would be **example**
      </td>
    </tr>
  </tbody>
</Table>

For POST requests all query parameters except the instance have to be in the body.

## Authentication - API signature

> 📘 Is this important for you?
>
> This part of the documentation is only important if you are not using an SDK.

The API signature is a HMAC ([RFC 2104](https://www.ietf.org/rfc/rfc2104.txt)).

For security reasons we want you to pass an API signature calculated with the API Secret of your instance.\
The parameter name of this API signature should be **ApiSignature**. You can calculate the signature using all params except the param **instance**.

* Build query string (e.g. model=Page\&id=17)
* Calculate binary hmac hash using your instance's API Secret as key
* Encode it with base64

```php
base64_encode(hash_hmac('sha256', http_build_query($params, null, '&'), $apiSecret, true));
```
```shell
echo -n "HTTP-QUERY-STRING" | openssl dgst -sha256 -hmac "API-SECRET" -binary | openssl enc -base64
```
```python
import urllib.request
import hmac
import hashlib
import base64

post_data = {}

httpQueryString = urllib.parse.urlencode(post_data).encode('UTF-8')

apiSignature = hmac.new(b'API-SECRET', msg=httpQueryString, digestmod=hashlib.sha256).digest()
```
```java
// imports
import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;
import java.io.UnsupportedEncodingException;
import java.net.URLEncoder;
import java.util.Base64;
import java.util.HashMap;
import java.util.concurrent.atomic.AtomicReference;

public static void main(String[] args) {
  // method content
  String key = "API-SECRET";

  // set up api data
  HashMap<String, String> data = new HashMap<>();
  data.put("title", "Test");
  data.put("description", "Test");
  data.put("referenceId", "12345678");
  data.put("purpose", "Test");
  data.put("amount", "200");
  data.put("currency", "EUR");

  String payload = getPayload(data);
  String hash = getApiSignature(payload, key);

  // append calculated ApiSignature to form data
  try {
    payload += "&ApiSignature=" + URLEncoder.encode(hash, "UTF-8");
  } catch (Exception e) {}

  payload = payload.replace("+", "%20");

  System.out.println("ApiSignature: " + hash);
  System.out.println("Payload: " + payload);
}

private static String getApiSignature(String encodedData, String apiKey) {
  try {
    Mac sha256_HMAC = Mac.getInstance("HmacSHA256");
    SecretKeySpec secret_key = new SecretKeySpec(apiKey.getBytes("UTF-8"), "HmacSHA256");
    sha256_HMAC.init(secret_key);
    return Base64.getEncoder().encodeToString(sha256_HMAC.doFinal(encodedData.getBytes("UTF-8")));
  } catch (Exception e) {}
  return "";
}

private static String getPayload(HashMap<String, String> postData) {
  AtomicReference<String> urlEncoded = new AtomicReference<>("");
  postData.forEach((s, s2) -> {
    try {
      String concat = urlEncoded.get().isEmpty() ? "" : "&";
      urlEncoded.set(urlEncoded.get() + concat + s + "=" + URLEncoder.encode(s2, "UTF-8"));
    } catch (UnsupportedEncodingException e) {
    }
  });

  return urlEncoded.get();
}
```
```csharp
# head
using System.Text;
using System.Security.Cryptography;

# function
string key = "API-SECRET";
string message = "";

byte[] keyByte = new UTF8Encoding().GetBytes(key);
byte[] messageBytes = new UTF8Encoding().GetBytes(message);
byte[] hashmessage = new HMACSHA256(keyByte).ComputeHash(messageBytes);

var signature = Convert.ToBase64String(hashmessage);
```
```typescript NodeJS
function buildSignature (query = '') {
  return Base64.stringify(hmacSHA256(query, secret))
}

let queryParams = Object.assign({}, params)
const queryStr = qs.stringify(queryParams)
queryParams.ApiSignature = buildSignature(queryStr)
```

> 🚧 Encoding of HTTP-Query String
>
> The query string has to be [RFC 1738](https://www.ietf.org/rfc/rfc1738.txt) encoded, that means you have to replace spaces by "+".\
> You can probably use: <http://linux.die.net/man/1/urlencode>