Authentication

The Monnet API uses a Keyed-hash message authentication codes (HMAC) as authentication mechanism to authenticate every single HTTP requests. HMAC is a mechanism for message authentication using cryptographic hash functions.

Every Merchant ID is provided with a pairs of keys. These keys are access credentials composed of alphanumeric characters that authorize the use of specific functionalities of our API.

It is required to use UTF-8 encoding to avoid calculation errors.

Below, we describe the components required to authenticate requests:

Required Variables

  1. Merchant ID: A unique identifier assigned to the merchant using our API. You should provide your assigned Merchant ID when making every single API request.

  2. API Key: An API key that identifies the associated API secret. You must include this key in the header of your requests using the "monnet-api-key" field.

  3. API Secret: An API key Secret associated with the API Key. You must use this value as an input for the HMAC algorithm.

  4. Timestamp: A timestamp generated by the merchant for each request. This timestamp must be included in the API endpoint URL as a query string parameter.

  5. HTTP Method: The HTTP method of the request.

  6. Hashed Body: The body of the request hashed using the alghoritm SHA-256.

  7. Signature: The HMAC result. The signature must be included in the API endpoint URL as a query string parameter.

How to generate the signature

The signature generation is an important step to ensure the authenticity and integrity of requests in our API. There are two important parts of the signature generation:

  • How to construct the signature content

    1. Extract the HTTP Method of your request.

      {HTTPmethod} = GET or POST

    2. Extract the resource path of the endpoint that you are sending the request.

      {resourcePath} = /api/v1/{MerchantID}/payouts

    3. Generate a Timestamp, include it in the request as a query parameter. The timestamp is a value that needs to be generated for each request. It should be in a format that includes the date and time information.

      {timestamp} = '?timestamp=' + 00000000000000

    4. Extract the body of your request and execute the SHA-256 on it.

      {hashedBody} = SHA256({body})

    5. Concatenate all the parameters adding ':' as separator.

      {HTTPmethod} + ':' + {resourcePath} + {timestamp} + ':' + {hashedBody}

  • How to sign/hash

    1. Calculate the Signature using HMAC-SHA256. The HMAC-SHA256 receives two parameters:

      • Message: Use the calculated content in the last step.

      • Secret Passphrase: Use the API Secret.

    2. Include the calculated signature as a query parameter of your request.

      {requestURL}&signature={calculatedSignature}

  • Add API Key to Header

    1. Add the API Key as part of the header with the name "monnet-api-key".

      monnet-api-key: {API Key}

Examples

In this section we are going to provide an example of how to calculate the signature:

Variables

API Key

SoSSp+5M4GrYfngfSE78lC2BzvUYQ0k8+i/iHg+bp54=

API Secret

P5yjICOFoE0kmJVMALeBRmoxuWXz0BJKuoSaIXEHTgE=

Merchant ID

22

  1. Example Create Payout:

Request Information

{HTTPmethod}:     POST
{resourcePath}:   /api/v1/22/payouts
{timestamp}:      ?timestamp=1687347016568
{body}:           '{"country": "MEX","amount": 10,"currency": "MXN","orderId": "CDO_90305","beneficiary": {"name": "testName","lastName": "testLastName","document": {"type": 3,"number": "PEGM9007151H0"},"customerId": "test","userName": "646180110400000007"},"destination": {"bankAccount": {"bankCode": "002","accountType": 1,"clabe": "002123451234534510"}}}'

Hash the body using alghoritm SHA-256

{hashedBody}: 7c7b333e31a0f1f9fab0222a97e0366e8327749732132d17934f51d6738e4c2e

Content to Sign

POST:/api/v1/22/payouts?timestamp=1687543238010:7c7b333e31a0f1f9fab0222a97e0366e8327749732132d17934f51d6738e4c2e

Signed Content

d6895bccdff72b95cb1d134037edadfa87cff1f0a543209efa356c889db97cb9

Request with Signature and Header

POST https://cert.api.payout.monnet.io/api/v1/22/payouts?timestamp=1687543238010&signature=d6895bccdff72b95cb1d134037edadfa87cff1f0a543209efa356c889db97cb9

--header 'monnet-api-key: SoSSp+5M4GrYfngfSE78lC2BzvUYQ0k8+i/iHg+bp54='

--data-raw '{"country": "MEX","amount": 10,"currency": "MXN","orderId": "CDO_90305","beneficiary": {"name": "testName","lastName": "testLastName","document": {"type": 3,"number": "PEGM9007151H0"},"customerId": "test","userName": "646180110400000007"},"destination": {"bankAccount": {"bankCode": "002","accountType": 1,"clabe": "002123451234534510"}}}'

  1. Example of a Get Payout:

Request Information

{HTTPmethod}:     GET
{resourcePath}:   /api/v1/22/payouts/65
{timestamp}:      ?timestamp=1687347519398
{body}:           ''

Hash the body using alghoritm SHA-256

{hashedBody}: e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855

Content to Sign

GET:/api/v1/22/payouts/73?timestamp=1687543425203:e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855

Signed Content

14cbc221c52bf588f439f86894ab1ebed9aa4867c2d79a1b159bd94a1df2c0d7

Request with Signature and Header

GET https://cert.api.payout.monnet.io/api/v1/22/payouts/73?timestamp=1687543425203&signature=14cbc221c52bf588f439f86894ab1ebed9aa4867c2d79a1b159bd94a1df2c0d7

--header 'monnet-api-key: SoSSp+5M4GrYfngfSE78lC2BzvUYQ0k8+i/iHg+bp54='

--data-raw ''

Make sure to follow these security considerations

  • Keep your keys and Merchant IDs secure. Do not share these values with unauthorized individuals.

  • Use HTTPS for all API requests to ensure communication security.

  • Generate a new timestamp for each request to avoid reusing previous requests.

Last updated