# Signature Logic and Security

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

* [**Authenticate Requests**](/en/get-smart/get-smart-api-cloud/first-steps/authtenticate-requests)**:** See the practical code implementation of this logic.  
* [**Debug Signature and Connectivity Issues**](/en/get-smart/get-smart-api-cloud/integration-guides/debug-signature-and-connectivity-issues)**:** Learn how to troubleshoot common `TPC0101` errors.