API Reference

International Payin Authorization

To ensure secure communication between your application and the PagSeguro International Payin API, all requests must include an Authorization header using Basic Authentication over HTTPS.

How Authorization Works

Each request to the International Payin API must be authenticated using Basic Authentication. This involves sending your API credentials, the merchant_id and secret_key, encoded in base64 format.

Authorization: Basic base64(merchant_id:secret_key)

The credentials are encoded as a single string using base64, and the result is prefixed by the word Basic and a space.

๐Ÿ“˜

HTTPS Required

Basic Authentication is only accepted over HTTPS. Requests made over insecure channels will be rejected.

Example

If your credentials are:

  • merchant_id: 1234
  • secret_key: 37b36e17-edb2-4d60-9afd-91062bebf5e4

You first concatenate them as:

1234:37b36e17-edb2-4d60-9afd-91062bebf5e4

Then encode the string in base64:

MTIzNDozN2IzNmUxNy1lZGIyLTRkNjAtOWFmZC05MTA2MmJlYmY1ZTQ=

Your final Authorization header becomes:

Authorization: Basic MTIzNDozN2IzNmUxNy1lZGIyLTRkNjAtOWFmZC05MTA2MmJlYmY1ZTQ=

Code Examples

You can use the following examples to generate the Authorization header in various languages:

$key = '1234';
$secret = '37b36e17-edb2-4d60-9afd-91062bebf5e4';
$encoded = base64_encode("$key:$secret");
$header = "Authorization: Basic $encoded";

echo $header;
// Output: Authorization: Basic MTIzNDozN2IzNmUxNy1lZGIyLTRkNjAtOWFmZC05MTA2MmJlYmY1ZTQ=

String key = "1234";
String secret = "37b36e17-edb2-4d60-9afd-91062bebf5e4";

String encoded = Base64.getEncoder().encodeToString((key + ":" + secret).getBytes());
String header = "Authorization: Basic " + encoded;

System.out.println(header);
// Output: Authorization: Basic MTIzNDozN2IzNmUxNy1lZGIyLTRkNjAtOWFmZC05MTA2MmJlYmY1ZTQ=

import base64

key = "1234"
secret = "37b36e17-edb2-4d60-9afd-91062bebf5e4"
credentials = f"{key}:{secret}"

encoded = base64.b64encode(credentials.encode("utf-8")).decode("utf-8")
header = f"Authorization: Basic {encoded}"

print(header)
# Output: Authorization: Basic MTIzNDozN2IzNmUxNy1lZGIyLTRkNjAtOWFmZC05MTA2MmJlYmY1ZTQ=

require "base64"

key = '1234'
secret = '37b36e17-edb2-4d60-9afd-91062bebf5e4'

encoded = Base64.encode64("#{key}:#{secret}").strip
header = "Authorization: Basic #{encoded}"

puts header
# Output: Authorization: Basic MTIzNDozN2IzNmUxNy1lZGIyLTRkNjAtOWFmZC05MTA2MmJlYmY1ZTQ=

Receiving Your Credentials

After the onboarding process is complete, PagSeguro will provide your unique credentials:

  • merchant_id
  • secret_key

These are required for all authenticated requests to the International Payin API.

โš ๏ธ

Keep Your Credentials Secure

Your credentials allow the creation of transactions on your behalf. Never expose them in frontend code, public repositories, or logs.

๐Ÿ“˜

Recommended best practices:

  • Store credentials in secure server environments.
  • Use environment variables or secret managers (e.g., AWS Secrets Manager, HashiCorp Vault).