Getnet DocsGetnet Docs

API Cloud Architecture

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

The Get Smart API Cloud is designed to bridge the gap between your cloud-based management software and physical payment terminals (TPV-PC). Unlike purely e-commerce APIs where transactions happen instantly in the browser, physical payments require human interaction (inserting a card, entering a PIN).

To accommodate this, the API uses a two-phase asynchronous architecture. Understanding this flow is essential to avoid common integration errors, such as assuming a transaction is complete when you receive the initial HTTP response.

High-Level Data Flow

The lifecycle of a transaction involves three parties: Your Application, the API Cloud, and the Physical Terminal.

  1. Initiation (Synchronous): Your application sends a request to the Cloud.
  2. Processing (Physical): The Cloud instructs the Terminal to activate. The customer interacts with the device.
  3. Completion (Asynchronous): The Cloud notifies your application of the final result.

Phase 1: The Synchronous Request

When you send a request (e.g., to /pago), the API Cloud performs an immediate validation check.

  • What happens: The system verifies your credentials, the message signature, and the JSON format.
  • The Response: You receive an immediate HTTP 200 OK response with a result code.
  • Crucial Concept: A result code of "0" does not mean the payment is approved. It means “Request Received and Validated.”
// Example Synchronous Response
{
    "resultado": {
        "codigo": "0" // The command was successfully queued for the terminal.
    }
}

Do not treat this response as a receipt. At this stage, no money has moved. The terminal might not have even lit up yet. You should update your local order state to “Pending” or “In Progress.”

Phase 2: The Asynchronous Notification

Once the synchronous phase is complete, the API Cloud pushes the command to the specific terminal ID defined in your request.

  1. Interaction: The terminal prompts the user. The user inserts their card and enters their PIN.
  2. Result Generation: The terminal communicates the outcome (Approved, Denied, Cancelled) back to the Cloud.
  3. Notification: The API Cloud sends a POST request to the urlNotificacion you defined in your initial request.

This notification contains the final result of the transaction, including authorization codes, ticket data, and card details.

Notification Fallback

The system is designed to ensure you receive the result even if your server is unreachable.

  • Primary Channel: urlNotificacion (HTTP POST).
  • Secondary Channel: If the call to your URL fails (e.g., your server is down or returns an error), the system attempts to send an email to the address defined in correoNotificacion.

System Requirements

To participate in this architecture, your integration must meet specific constraints defined in the standard.

Network and Security

  • Protocol: All connections must be secured via TLS 1.2 or higher.
  • Access: Connectivity is established over public internet lines; no VPN or dedicated leased lines are required for the REST interface.
  • Encoding: All data must be UTF-8 encoded.

JSON Constraints

The API is strict regarding data types to ensure stability across different terminal softwares.

  • No null values: Fields must never be explicitly set to null. If a field is optional and has no value, it must be omitted from the JSON object entirely.
  • Minimization: While not strictly enforced for parsing, it is recommended to avoid excessive whitespace, tabs, or newlines in production payloads to prevent signature verification issues.

Next Steps