API Reference

Brazil Payin Authorization

PagSeguro Brazil Payin API uses a custom HMAC-based authentication scheme to securely validate requests. Each API call must include an Authorization header that combines your merchant ID, secret key, and request-specific parameters.

This page explains how to generate the correct authorization header for both POST and GET requests.

Authentication Overview

To authenticate, you must include the following HTTP header in every request:

Authorization: merchant-id:hmac-sha256-signature

The signature is generated using the HMAC-SHA256 algorithm and varies depending on the HTTP method (POST or GET).

You’ll receive your merchant-id and secret-key from PagSeguro during the onboarding process.

⚠️

Keep Your Credentials Safe

Do not expose your merchant ID or secret key in client-side code. Always store them securely in server-side environments using secrets managers or environment variables.

POST Requests Authorization

For POST requests (e.g. creating a transaction), the authorization header is based on:

  • The URL path (/transactions)
  • The MD5 hash of the request body
  • Your secret key

The signature should have the following structure:

Authorization: merchant-id:hmac-sha256(URL Path + Content-MD5, secret-key)

You must:

  1. Compute the MD5 hash of the request body.
  2. Concatenate the URL path with the MD5 hash.
  3. Generate an HMAC-SHA256 using the secret key.
  4. Prefix the result with your merchant ID and colon.

The following code block shows examples of how to generate the signature in different programming languages:

final String data = "/transactions" + contentMD5;
Mac mac = Mac.getInstance("HmacSHA256");
mac.init(new SecretKeySpec(secretKey.getBytes("UTF8"), "HmacSHA256"));
String signature = Hex.encodeHexString(mac.doFinal(data.getBytes("UTF-8")));
String authorization = merchantId + ":" + signature;

$contentMD5 = md5($body);
$hashHmac = hash_hmac('sha256', '/transactions' . $contentMD5, $secretKey);
$authorizationHeader = $merchantId . ':' . $hashHmac;

import hashlib, hmac

message = b'/transactions' + b'123'  # Replace '123' with your contentMD5
secret = b'bc123'

signature = hmac.new(secret, message, hashlib.sha256).hexdigest()
authorization = f"{merchant_id}:{signature}"

require 'openssl'

data = '/transactions' + content_md5
signature = OpenSSL::HMAC.hexdigest('sha256', secret_key, data)
authorization = "#{merchant_id}:#{signature}"

GET Requests Authorization

For GET requests (e.g. searching transactions), the authorization is based on:

  • The URL path
  • The query string
  • Your secret key

The signature should have the following structure:

Authorization: merchant-id:hmac-sha256(URL Path + Query String, secret-key)

You must:

  1. Concatenate the URL path and query string.
  2. Generate an HMAC-SHA256 signature using the secret key.
  3. Prefix the result with your merchant ID and colon.

The following code block shows examples of how to generate the signature in different programming languages

final String data = "/transactions?initial_date=2024-01-01";
Mac mac = Mac.getInstance("HmacSHA256");
mac.init(new SecretKeySpec(secretKey.getBytes("UTF8"), "HmacSHA256"));
String signature = Hex.encodeHexString(mac.doFinal(data.getBytes("UTF-8")));
String authorization = merchantId + ":" + signature;

$query = '/transactions?initial_date=2024-01-01';
$hashHmac = hash_hmac('sha256', $query, $secretKey);
$authorizationHeader = $merchantId . ':' . $hashHmac;

import hashlib, hmac

message = b'/transactions?initial_date=2024-01-01'
secret = b'bc123'

signature = hmac.new(secret, message, hashlib.sha256).hexdigest()
authorization = f"{merchant_id}:{signature}"

require 'openssl'

data = '/transactions?initial_date=2024-01-01'
signature = OpenSSL::HMAC.hexdigest('sha256', secret_key, data)
authorization = "#{merchant_id}:#{signature}"