Welcome to the Maypay APIs documentation.

Here you can find all the details on how to get access, input parameters and expected results for each individual API exposed by the Maypay service.

Before proceeding to the details of each API, we strongly recommend you read the Authorization section in order to implement the correct API access algorithm

Access to the APIs service is protected by an authorisation mechanism based on an API Key. Every merchant wishing to integrate their e-commerce with Maypay must first obtain their own API Key, that consists of a private part that must remain secret and a public part.

To be authorised, the request must contain the following headers:

• Authorization: MAYPAY <public_key>:<digest>; (mind the semicolon)
• x-maypay-req-id: random UUID as request identifier.
• Date: Date string based on rfc7231 date format, to ensure request freshness.

  How to build Authorization header

  As can be seen above, the header consists of 3 distinct fields:
  • MAYPAY: fixed string
  • public_key: the public part of the API Key
  • digest: digitally signed payload of the request using the private part of the API Key

The payload of the request must be a string having the following structure:

<http_method> <url>
<date>
<x-maypay-req-id>
<content-type> (optional)
<json_serialized_body> (optional)       

Here are 2 examples of payloads of a post and a get requests:

POST https://europe-west1-maypay-app.cloudfunctions.net/cancelMerchantPaymentRequest
Mon, 20 Mar 2023 08:34:32 GMT
72f9a80a-5a2c-4200-b719-24399d6f3965
application/json
{"merchantPaymentRequestId":"jA6EqoCld0lYMc55o1gw"}

GET https://europe-west1-maypay-app.cloudfunctions.net/getMerchantPaymentRequest?merchantPaymentRequestId=jA6EqoCld0lYMc55o1gw
Mon, 20 Mar 2023 08:33:51 GMT
dac7b351-c861-49b9-8a55-770608b075e9

After building the string representing the request payload, the digest is obtained by creating a Base64-encoded hash of the payload using the HMAC SHA1 algorithm with the private part of the API Key as secrete key.

Below is an implementation example in NodeJs of how to build headers to access APIs.

const crypto = require("crypto");
const maypayAPIRequest = async (
  method,
  url,
  contentType,
  data,
  publicKey,
  privateKey
) => {
  try {
    let payload, body;

    const headers = {
      "X-MAYPAY-Req-ID": crypto.randomUUID(),
      Date: new Date().toUTCString(),
    };

    payload = `${method} ${url}\n${headers["Date"]}\n${headers["X-MAYPAY-Req-ID"]}`;

    if (contentType === "application/json") {
      headers["Content-Type"] = contentType;
      payload += `\n${headers["Content-Type"]}`;
      if (data) {
        body = JSON.stringify(data)
        payload += `\n${body}`;
      }
    }

    const hm = crypto.createHmac("sha1", privateKey);
    hm.update(payload);
    headers["Authorization"] = `MAYPAY ${publicKey}:${hm.digest().toString("base64")};`;

    const apiResponse = await fetch(url, {
      method,
      headers,
      body,
    });

    const json = await apiResponse.json();
    return json;
  } catch (error) {
    console.log("fetch error", error);
  }
};

How to handle Webhook responses

When creating the payment request, you must provide a callback URL that will act as an endpoint for the communication of the outcome of the transaction.

To ensure security for this communication as well, the request from our servers uses the same authentication mechanism described above.

When the webhook is triggered, you can authenticate the packet by comparing the signature contained in the x-maypay-digest header and the signature created from the packet. The HMAC signature is created using the same API key with which the payment request was created.

Below is an example of how to verify that the signature was created from the same private key written in NodeJS. The req object has the same properties as the Express request object.

const authenticateWebhookResult = (req, privateKey) => {
  try {
    const authorization = req.header("x-maypay-digest");
    const date = req.header("date");
    const contentType = req.header("content-type");
    const xMaypayReqId = req.header("x-maypay-req-id");

    const reg =
      /^MAYPAY\s(maypay_pk_(?:[A-Za-z0-9+\/]{4})*(?:[A-Za-z0-9+\/]{2}==|[A-Za-z0-9+\/]{3}=|[A-Za-z0-9+\/]{4})):((?:[A-Za-z0-9+\/]{4})*(?:[A-Za-z0-9+\/]{2}==|[A-Za-z0-9+\/]{3}=|[A-Za-z0-9+\/]{4}));$/;

    let auth = authorization || "";
    auth = auth.trim();
    const check = auth.match(reg);

    if (!check || check.length <= 2) {
      throw { message: "Invalid Authorization header", code: 401 };
    }

    const pk = check[1];
    const digest = check[2];

    if (!pk || !digest) {
      throw { message: "Missing public key or digest", code: 401 };
    }

    const requestDate = new Date(date).getTime();
    const actualDate = Date.now();

    // Request Freshness
    if (actualDate - requestDate > 5 * 60 * 1000 /* max 5 minutes old*/) {
      throw { message: "Timeout", code: 410 /* GONE */ };
    }

    const hm = crypto.createHmac("sha1", privateKey);
    
    const fullUrl = `${req.headers["x-forwarded-proto"]}://${req.headers.host}${req.url}`;

    let payload = `${req.method} ${fullUrl}\n${date}\n${xMaypayReqId}`;
    payload += "\n" + contentType + "\n" + JSON.stringify(req.body);

    hm.update(payload);

    const compareDigest = hm.digest().toString("base64");
    if (compareDigest !== digest) {
      throw {
        message: "Invalid digest. Received payload: " + payload,
        code: 401,
      };
    }

    console.log("Authorized");
    return true;
  } catch (error) {
    console.error(error);
    return false;
  }
};

A payment request represents the willingness of an e-commerce to initiate a payment procedure over the Maypay service.

APIs offer the possibility of:

• Create a new payment request
• Cancel an existing and pending one
• Get the data of a request

Flows

When creating a request you can use one of the following flows:

A Store represents a point of sale of a merchant. The API makes it possible to get information on one or more of a merchant's stores.

getStoreList API does not require any additional input parameters, as the API Key uniquely identifies a merchant or his specific store. Depending on the type of API Key used, the results vary as follows:

• API Key associated with a merchant: list of stores belonging to the merchant with that specific merchantId and meeting the search parameters.
• API Key associated with a store: list containing the data of the individual store