Process Single-Step Payments

This guide details how to implement the standard payment flow (Sale). In this flow, you send a single request to the API, and the terminal handles the interaction with the cardholder.

Because physical terminal interactions take time, this process is asynchronous. You will initiate the payment via a direct API call and receive the final result via a webhook notification.

The Transaction Lifecycle

Request: Your server sends a POST request to the /pago endpoint.
Acknowledgment: The API returns a synchronous 200 OK indicating the terminal has received the command.
Interaction: The terminal prompts the customer to insert their card and enter their PIN.
Notification: Once the transaction concludes (Approved, Denied, or Cancelled), the API sends a JSON payload to your urlNotificacion.

Step 1: Send the Payment Request

To start a sale, send a POST request to the /pago endpoint.

Test Endpoint: https://tpvpc-i.redsys.es:27443/TPV_PC/services/rest/tpvpcwss/v1/pago
Production Endpoint: https://tpvpc.redsys.es/TPV_PC/services/rest/tpvpcwss/v1/pago

Request Payload

The payload must include the amount, your internal invoice reference, and the notification URL where you want to receive the final result.

{
  "info": {
    "comercio": "777888991",
    "terminal": 1,
    "timestamp": "20250428 111217",
    "notificacion": {
      "urlNotificacion": "https://your-server.com/api/webhooks/payment-results",
      "correoNotificacion": "[email protected]"
    },
    "datosOperacion": {
      "importe": "25.50",
      "factura": "ORD-2025-001"
    }
  },
  "signature": "YOUR_CALCULATED_SIGNATURE"
}

Ensure importe is formatted as XXXXXXXXX.XX (e.g., 25.50 or 0.01). Do not use commas.

Step 2: Handle the Synchronous Response

Immediately after sending the request, the API will return a response.

Expected Response:

{
  "info": {
    "resultado": {
      "codigo": "0"
    }
  },
  "signature": "SERVER_SIGNATURE"
}

codigo: "0": Success. The terminal is now processing the payment.
Any other code: The request failed (e.g., validation error, terminal offline). See the Error and Denial Code Catalog reference.

Do NOT release goods yet. A code of 0 here only means “Request Accepted.” It does not mean the payment was paid or authorized.

Step 3: Receive the Asynchronous Notification

When the customer finishes (or cancels) the transaction, the API Cloud sends a POST request to your urlNotificacion.

Example Success Notification

{
  "info": {
    "comercio": "777888991",
    "terminal": 1,
    "timestamp": "20250428 111500",
    "datosRespuesta": {
      "tipoPago": "PAGO",
      "importe": "25.50",
      "moneda": "978",
      "factura": "ORD-2025-001",
      "resultado": "Autorizada",
      "codigoRespuesta": "998877",
      "estado": "F",
      "tarjetaClienteRecibo": "************1234",
      "marcaTarjeta": "1"
    }
  },
  "signature": "SERVER_SIGNATURE"
}

Key Fields to Validate

You must inspect specific fields in datosRespuesta to confirm the payment status:

Field	Value for Success	Description
`resultado`	`Autorizada`	Explicitly states the transaction was approved.
`estado`	`F`	Indicates the operation is “Finalized” (Finalizada).
`codigoRespuesta`	(Auth Code)	The authorization code from the bank. If the transaction was denied, this will contain a denial code (e.g., `101`, `117`).
`importe`	(Your Amount)	Verify that the amount authorized matches the amount you requested.

Handling Denials and Errors

If the payment fails, the notification will reflect the failure:

resultado: Denegada
codigoRespuesta: A denial code (e.g., 117 for Incorrect PIN).
estado: Might be G (Denied), A (Cancelled), or T (Technical Failure).

Next Steps

Set up Webhooks and Notifications: Detailed guide on parsing and validating the notification payload.
Receipt Printing Specifications: Use the data from the notification (tarjetaClienteRecibo, marcaTarjeta) to print the mandatory compliant receipt.