Getnet DocsGetnet Docs

Signature Logic and Security

View as MarkdownView this page as plain textOpen in ChatGPTAsk questions about this pageOpen in ClaudeAsk questions about this pageOpen in PerplexityAsk questions about this page
Connect to CursorUse these docs in CursorConnect to VS CodeUse these docs in VS Code

In the Get Smart API Cloud, security is not handled by a persistent session token or a standard Bearer authentication header. Instead, every message—whether a request sent by you or a response sent by the cloud—is secured using a Digital Signature.

This guide explains the theoretical background of this mechanism, known as a Keyed-Hash, and why it is critical for financial transaction integrity.

The Purpose of the Signature

The signature serves two primary security goals:

  1. Authentication (Who sent it?): Because the signature is generated using a merchant key known only to you and the API Cloud, a valid signature proves the message originated from a trusted source.
  2. Integrity (Did it change?): The signature is a mathematical checksum of the message content. If a single character in the JSON payload is altered (e.g., changing an amount from 10.00 to 1.00), the signature will no longer match, and the request will be rejected.

The Algorithm: SHA256 Concatenation

While similar in purpose to HMAC (Hash-Based Message Authentication Code), the specific implementation in this API uses a concatenation-based SHA256 method.

Logical Flow

Signature = SHA256 (JSON String + Merchant Key)

  1. The Message: The raw JSON string of the info object. This represents the “state” you want to transmit (Merchant ID, Amount, Invoice Number).
  2. The Secret: Your merchant key. This acts as the “salt” that prevents an attacker from generating valid signatures, even if they know the hashing algorithm.
  3. The Hash: The SHA256 function is a one-way cryptographic function. It is easy to generate the hash from the message, but impossible to reverse-engineer the message (or the key) from the hash.

Bidirectional Security

Security in this API is bidirectional.

Outbound (Request Signing)

When you send a request to /pago, you sign it to prove to the API Cloud that you are the authorized merchant. If the signature is invalid, the API returns error code TPC0101 (“Firma Incorrecta”).

Inbound (Response Verification)

When the API Cloud sends you a response (synchronously) or a notification (asynchronously), it signs that message using your merchant key.

Trust No One: You must always calculate the signature of incoming notifications locally and compare it to the signature field received. This protects you from “replay attacks” or malicious actors attempting to inject fake payment confirmations into your system.

Key Management Best Practices

Because the security of the entire system relies on the merchant key, it must be handled with extreme care.

  • Backend Only: Generation must occur on your secure server. Never ship the merchant key in a mobile app or client-side JavaScript bundle.
  • Environment Segregation: Use the specific key assigned for the environment (Test vs. Production). Using a Test key in Production (or vice versa) will result in signature validation failures.

Next Steps