Authentication Learn how Payyo uses message signing for authentication

Authentication

Payyo uses public keys and message signing to authenticate clients. A Payyo representative will give (or has already given) you your own public and secret key.

Clients must send an Authorization header in the following format:

Authorization: "Basic " + BASE64($PUBLICKEY + ":" + HMAC_SHA256(BASE64URL($REQUEST), $SECRETKEY))

Below you see an explanation for each parameter ($...) and method (...()) used in the aforementioned Authorization header. If you read on you'll find a complete example.

Parameters

Parameter Description Example
$PUBLICKEY The client's public key. api_e702422d73e2efff455021180ba0
$SECRETKEY The client's secret key. sec_fff455021180ba0e702422d73e2e
$REQUEST The JSON-encoded request data {"jsonrpc": "2.0", "method": "transaction.capture", "params": { ... }, "id": "1"}

Methods

Method Description
BASE64() Encodes a string in base64.
BASE64URL() Encodes a string in base64url.
HMAC_SHA256() Computes a MAC of the input data using the SHA-256 hashing algorithm and a secret key. See HMAC for more details.

Example

This is a complete example on how to compute a valid Authorization header for a request and a given key pair. It consists of first encoding the request data, then computing the signature and in a final step assembling the complete Authorization header.

Public Key
"api_e702422d73e2efff455021180ba0"
Secret Key
"sec_fff455021180ba0e702422d73e2e"
JSON Body
{
  "jsonrpc": "2.0",
  "method": "transaction.capture",
  "params": {
    "merchant_id": 100001,
    "transaction_id": "tra_8e7832a8c1594f8fcdd5a301c127"
  },
  "id": 1
}

Step 1: base64url-encode request data

In a first step we compute the base64url representation of the request data. Important: Make sure that the request data is exactly the same as it will be sent; this includes whitespace characters.

BASE64URL('{
  "jsonrpc": "2.0",
  "method": "transaction.capture",
  "params": {
    "merchant_id": 100001,
    "transaction_id": "tra_8e7832a8c1594f8fcdd5a301c127"
  },
  "id": 1
}')
= "ewogICJqc29ucnBjIjogIjIuMCI...NWEzMDFjMTI3IgogIH0sCiAgImlkIjogMQp9"

Step 2: Compute signature

Using the result from the previous step and the secret key we can now compute the signature for the request.

HMAC_256(
  "ewogICJqc29ucnBjIjogIjIuMCI...NWEzMDFjMTI3IgogIH0sCiAgImlkIjogMQp9",
  "sec_fff455021180ba0e702422d73e2e"
)
= "14a7817aab8521d51d85584f1652dfc9e73322de597a8250bb2ab638b1284c57"

Step 3: Assemble authorization header

The final step consists of using the public API key ("username") and the computed signature from the previous step ("password") as the parameters in an HTTP basic authentication header.

Authorization: Basic BASE64('api_e702422d73e2efff455021180ba0:14a7817aab8 \
                     521d51d85584f1652dfc9e73322de597a8250bb2ab638b1284c57')
Authorization: Basic YXBpX2U3MDI0MjJkNzNlMmVmZmY0NTUwMjExODBiYTA6MTRhNzgx \
                     N2FhYjg1MjFkNTFkODU1ODRmMTY1MmRmYzllNzMzMjJkZTU5N2E4 \
                     MjUwYmIyYWI2MzhiMTI4NGM1Nw==

When Payyo receives the request it will look up the secret key associated with the public key to compute a signature which is compared with the one from the request. If the signatures match it proves that the client had access to the key pair's secret key and also that the message was not tempered with.