Authentication & Request Signing

Step 1: Obtain an Auth Token

Before accessing protected endpoints, you need to exchange your API key for a JWT token.

Endpoint:
POST /api/v1/auth/token

Request Example:

Success Response:

{
  "success": true,
  "data": {
    "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9....",
    "exp": 1748422939
  },
  "trace_id": "b12d9cfe-6dc2-4d91-8d63-xxxx"
}

Use this token as a Bearer token for all protected API requests.

The token is valid for 24 hours (unless configured otherwise).

Step 2: Prepare and Sign Your Request

Every request to a protected endpoint must be signed using HMAC-SHA256 and your API key, to ensure authenticity and prevent tampering.

How to Sign Your Request

To calculate the signature:

Build the Canonical String

<HTTP_METHOD>\n
<FULL_URL_WITHOUT_QUERY_PARAMS>\n
<CANONICAL_JSON_BODY>

HTTP_METHOD — e.g., POST or GET, UPPERCASE

FULL_URL_WITHOUT_QUERY_PARAMS — the full request URL without query parameters
e.g. https://pay.deficopay.com/api/v1/deposits/fiat/initiate

CANONICAL_JSON_BODY — the JSON body of your request, with all keys sorted alphabetically (recursively), no spaces or line breaks.
For GET or requests with no body, use an empty string ("").

Example:

POST
https://pay.deficopay.com/api/v1/deposits/fiat/initiate
{
"amount":20,
"currency":"ARS",
"customer":{
"country":"AR",
"email":"test@gmail.com",
"firstName":"John",
"lastName":"Doe",
"personalId":"12343113"
},
"merchant_notification_url":"https://webhook.site/23e6bd27-0ec6-4158-ae7e-bceb25e68325",
"merchant_transaction_id":"4adb427f-b062-4705-8d95-00c57916cd3a",
"order":{
    "description":"Test 30 May 1257",
    "id":"339f8edb-cd94-4ea7-a6b6-d7621f57cf92"
},
"payment_method_code":"mercadopago_qr_ar",
"returnUrls":{
    "default":"https://webhook.site/23e6bd27-0ec6-4158-ae7e-bceb25e68325"
}
}

Calculate the Signature

Use your API key as the secret.

Calculate HMAC-SHA256 of the canonical string.

Encode the result as a lowercase hex string.

Pseudo-code:

signature = HMAC_SHA256(api_key, canonical_string)

Send Signature in Header

Add the signature to the header:

X-API-Signature: <signature>

Always include your JWT auth token in the Authorization: Bearer <token> header.

Example: Initiate a Fiat Deposit (Step-by-Step)

1. Get an Auth Token

Save the token from the response.

2. Prepare the Body and Canonical String

Suppose your request body is:

{
  "amount": 20,
  "currency": "ARS",
  "payment_method_code": "mercadopago_qr_ar",
  "merchant_transaction_id": "4adb427f-b062-4705-8d95-00c57916cd3a",
  "order": {
    "id": "339f8edb-cd94-4ea7-a6b6-d7621f57cf92",
    "description": "Test 130 May 1257"
  },
  "merchant_notification_url": "https://webhook.site/23e6bd27-0ec6-4158-ae7e-bceb25e68325",
  "customer": {
    "firstName": "John",
    "lastName": "Doe",
    "personalId": "12343113",
    "email": "test@gmail.com",
    "country": "AR"
  },
  "returnUrls": {
    "default": "https://webhook.site/23e6bd27-0ec6-4158-ae7e-bceb25e68325"
  }
}

Recursively sort keys alphabetically (example above is already sorted).

Convert to compact JSON, no whitespace or line breaks.

3. Build Canonical String

POST
https://pay.deficopay.com/api/v1/deposits/fiat/initiate
<compact_sorted_json_body>

4. Compute Signature

Python Example:

5. Make the API Request

Summary Table

Header	Value	Example
Authorization	Bearer `<token>`	`Bearer eyJ0eXAiOiJKV1QiLCJ...`
X-API-Signature	`<signature>`	`bf8e1a7a395a1ac99e8...`
Content-Type	application/json

Notes

Always use your API key as HMAC secret, not your token.

The JWT token is for authentication, the signature is for integrity.

Always sort JSON keys alphabetically and compact (no extra whitespace).

For GET or bodyless requests, the canonical string body part is empty.

Ready-to-use Postman Pre-request Script Example

Troubleshooting

401 Unauthorized: Check your token and signature, and ensure headers are correct.

Signature mismatch: Confirm body is sorted and compacted properly, canonical string matches exactly.

Quick Checklist

Obtain JWT token

Prepare request body, recursively sort keys

Build canonical string

Sign canonical string using HMAC-SHA256 and your API key

Send request with JWT token + signature

Step 1: Obtain an Auth Token#

Step 2: Prepare and Sign Your Request#

How to Sign Your Request#

Example: Initiate a Fiat Deposit (Step-by-Step)#

1. Get an Auth Token#

2. Prepare the Body and Canonical String#

3. Build Canonical String#

4. Compute Signature#

5. Make the API Request#

Summary Table#

Notes#

Ready-to-use Postman Pre-request Script Example#

Troubleshooting#

Quick Checklist#