> ## Documentation Index
> Fetch the complete documentation index at: https://docs.localpayment.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Preautorización y captura

La preautorización es un proceso de dos pasos que permite a los comercios verificar el método de pago del cliente antes de completar la transacción. Este proceso retiene temporalmente el importe de la transacción en la cuenta del cliente sin realizar el cargo.

En **el primer paso**, se realiza la solicitud de preautorización, reservando el importe especificado. Esto garantiza que el cliente dispone de fondos suficientes y que el método de pago es válido. Sin embargo, los fondos no se transfieren al comercio en esta etapa.

En **el segundo paso**, se ejecuta la solicitud de captura para finalizar el pago. El importe preautorizado se debita de la cuenta del cliente y se abona al comercio.

***

## Antes de comenzar

Asegúrate de tener:

> [card] [Credenciales de API](https://docs.localpayment.com/es/docs/api-keys-and-environments.md)
>
> Credenciales API válidas y token de acceso para la autenticación.

> [card] [Configuración de la cuenta](https://docs.localpayment.com/es/docs/make-your-first-test-payment.md)
>
> Configuración adecuada de la cuenta para el país de destino y verificación de la empresa.

> [card] [Lista blanca de IP](https://docs.localpayment.com/es/docs/dashboard-whitelist-your-ips.md)
>
> Incluye en la lista blanca las direcciones IP de tus servidores para el acceso a la API.

> [card] [Endpoint del webhook](https://docs.localpayment.com/es/docs/webhooks.md)
>
> Configura una URL de webhook para recibir notificaciones de pago.

***

## Paso 1: Solicitar una preautorización

Para iniciar una preautorización, deberás enviar una solicitud `POST` al endpoint [Crear Payin](https://docs.localpayment.com/reference/payins.md) y establecer el encabezado `x-capture` en `true`.

### Parámetros clave de la solicitud

La solicitud requiere varios objetos clave:

| Parámetro | Descripción | Requerido |
| - | - | - |
| `beneficiary` | Datos del destinatario, incluyendo información bancaria | ✅ |
| `sender` | Información del remitente para el cumplimiento | ✅ |
| `merchant` | Datos del comerciante/negocio | ✅ |
| `paymentMethod` | Configuración del método de pago | ✅ |
| `amount` | Importe de la transacción | ✅ |
| `currency` | Código de moneda de la transacción | ✅ |
| `country` | Código del país de destino | ✅ |

El valor de `paymentMethod.code` depende del país, de la marca de la tarjeta y del producto (crédito o débito). En Perú también depende de la moneda. Consulta los [códigos de métodos de pago con tarjeta](https://docs.localpayment.com/es/docs/card-payment-methods.md) para ver la lista completa.

### Ejemplo de solicitud

A continuación se muestra un ejemplo que utiliza `curl`:

```bash curl theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
curl --request POST \
  --url https://api.stage.localpayment.com/api/payin/ \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer <your_access_token>' \
  --header 'Content-Type: application/json' \
  --header 'x-capture: true' \
  --data '{
    "paymentMethod": {
        "type": "CreditCard",
        "code": "1000",
        "flow": "DIRECT"
    },
    "externalId": "40bac59a-0381-4cc0-a6a5-33418d84c2e4",
    "country": "ARG",
    "currency": "ARS",
    "amount": 1000,
    "accountNumber": "{{accountNumber}}",
    "conceptCode": "0001",
    "merchant": {
        "type": "COMPANY",
        "name": "Company",
        "document": {
            "type": "CUIT",
            "id": "3000091105"
        },
        "email": "mail@company.com",
        "phone": {
            "countryCode": "54",
            "areaCode": "351",
            "number": "1234567"
        }
    },
    "payer": {
        "type": "INDIVIDUAL",
        "name": "John",
        "lastname": "Doe",
        "document": {
            "type": "DNI",
            "id": "37993123"
        },
        "email": "john.doe@example.com",
        "phone": {
            "countryCode": "1",
            "areaCode": "11",
            "number": "98189123"
        },
        "bank": {
            "name": "BANCO BBVA ARGENTINA S.A.",
            "code": "017",
            "account": {
                "type": "S",
                "number": "19101196551119123456789"
            }
        }
    },
    "commercialData": {
        "items": [
            {
                "id": "12345",
                "quantity": "1",
                "description": "Test product",
                "title": "Test",
                "unitPrice": "1000"
            }
        ]
    },
    "card": {
        "number": "4000000000000002",
        "cvv": "123",
        "expirationMonth": "12",
        "expirationYear": "2029"
    }
}'
```

Consulta todos los [parámetros disponibles](https://docs.localpayment.com/reference/payins.md) en la solicitud.

***

## Paso 2: Gestionar la respuesta

### Respuesta exitosa

Una respuesta exitosa incluye información detallada de la transacción e identificadores de seguimiento.

```json theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
{
  "transactionType": "PayIn",
  "externalId": "40bac59a-0381-4cc0-a6a5-33418d84c2e4",
  "internalId": "22b29c98-92af-44bd-a164-1863ae2f1bb3",
  "paymentMethod": {
    "type": "CreditCard",
    "code": "1000",
    "flow": "DIRECT"
  },
  "country": "ARG",
  "currency": "ARS",
  "amount": 1000,
  "accountNumber": "{{accountNumber}}",
  "confirmed": {
    "currency": "ARS",
    "amount": 1000,
    "fxQuote": 1,
    "exchangeRateToken": null
  },
  "payment": {
    "installment": null,
    "currency": "ARS",
    "fxQuote": 1,
    "financingFee": 0,
    "amount": 1000
  },
  "localTaxes": [],
  "withHoldings": [],
  "fees": {
    "description": "Fee",
    "currency": "ARS",
    "fxSource": 210.8,
    "fxQuote": 1,
    "amount": 13.02,
    "account": "{{accountNumber}}"
  },
  "status": {
    "code": "102",
    "description": "AUTHORIZED",
    "detail": "The payin was authorized"
  },
  "ticket": null,
  "qr": null,
  "beneficiary": null,
  "merchant": {
    "type": "COMPANY",
    "name": "Company"
  },
  "payer": {
    "type": "INDIVIDUAL",
    "name": "John",
    "lastname": "Doe",
    "document": {
      "id": "37895247",
      "type": "DNI"
    },
    "email": "john.doe@example.com",
    "phone": {
      "countryCode": "1",
      "areaCode": "11",
      "number": "98789632"
    },
    "address": null,
    "birthdate": null,
    "nationality": null
  },
  "intermediaries": [],
  "wireInstructions": null,
  "date": {
    "creationDate": "2024-05-19T19:02:44.018+00:00",
    "processedDate": "2024-05-19T19:02:44.799618",
    "expirationDate": "0001-01-01T00:00:00"
  },
  "card": {
    "bin": "402670",
    "brand": "VISA",
    "country": "RS",
    "name": "John Doe",
    "last4": "3263",
    "expirationYear": 2029,
    "expirationMonth": 9
  },
  "errors": []
}
```

### Campos de respuesta clave

| Campo | Descripción | Caso de uso |
| - | - | - |
| `internalId` | Identificador único de transacción de Localpayment | Seguimiento y soporte de transacciones |
| `externalId` | Tu número de referencia | Reconciliación interna |
| `status.code` | Código de estado de transacción actual | Monitoreo de estado |
| `date.creationDate` | Cuando se creó la transacción | Registro de auditoría |
| `date.processedDate` | Cuando comenzó el procesamiento de la transacción | Cálculo del tiempo de procesamiento |

### Respuesta de error

Cuando una solicitud falla, recibirás información detallada sobre el error:

```json theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
{
  "externalId": "46014bdc-c3a7-1b15-8dcf-c7050c1c8199",
  "internalId": "caa4e9aa-f634-497c-ba75-7f88b005ca62",
  "status": {
    "code": "801",
    "description": "REJECTED",
    "detail": "Params error"
  },
  "errors": [
    {
      "code": "300",
      "detail": "Invalid param + [paymentMethod] + doesn´t exists for MEX"
    },
    {
      "code": "300",
      "detail": "Invalid param + [payer.bank.account.[number, type | alias]] + must not be null"
    },
    {
      "code": "300",
      "detail": "Invalid param + [payer.document.type] + is invalid for country MEX"
    },
    {
      "code": "300",
      "detail": "Invalid param + [payer.document] + is invalid for payer type"
    },
    {
      "code": "701",
      "detail": "IncorrectAccountNumber"
    }
  ]
}
```

***

## Paso 3: Capturar los fondos

Tras preautorizar una transacción, debes capturar los fondos para debitar la cuenta del cliente. Asegúrate de que la solicitud de captura sea por el importe total de la preautorización. La retención de fondos por preautorización **caducará a los 7 días**. Si no capturas los fondos dentro de este plazo, se devolverán automáticamente a la tarjeta del cliente.

Para capturar una preautorización, envía una solicitud `PATCH` al endpoint [Capturar Payin autorizado](https://docs.localpayment.com/reference/capture-payin.md).

### Ejemplo de solicitud

```bash curl theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
curl --location --request PATCH 'https://api.stage.localpayment.com/api/payin/capture/{externalId}' \
--header 'Authorization: Bearer <your_access_token>'
```

### Respuesta exitosa

```json theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
{
    "externalId": "40bac59a-0381-4cc0-a6a5-33418d84c2e4",
    "internalId": "40ae5d95-e859-4fc9-b37b-67442392b785",
    "status": {
        "code": "103",
        "description": "APPROVED",
        "detail": "The payin was confirmed but not credited yet"
    }
}
```

***

## Liberar fondos no utilizados

Para garantizar una experiencia positiva para el cliente, se recomienda liberar los fondos preautorizados que no se vayan a utilizar. Al iniciar la liberación mediante una solicitud API, puedes evitar que tus clientes tengan que esperar los 7 días completos para la liberación automática.

Para liberar los fondos no utilizados, envía una solicitud `PATCH` al endpoint [Cancelar autorización de Payin](https://docs.localpayment.com/reference/cancel-authorization.md).

### Ejemplo de solicitud

```bash curl theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
curl --location --request PATCH 'https://api.stage.localpayment.com/api/payin/capture/{externalId}/status/' \
--header 'Authorization: Bearer <your_access_token>' \
--header 'Content-Type: application/json' \
--data-raw '{
    "status": "CANCELLED"
}'
```

### Respuesta exitosa

```json theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
{
    "externalId": "40bac59a-0381-4cc0-a6a5-33418d84c2e4",
    "internalId": "39eb0371-3f21-488f-a779-913799e51406",
    "status": {
        "code": "905",
        "description": "CANCELLED",
        "detail": "The authorization was cancelled"
    }
}
```

***

## Paso 4: Seguimiento del estado de la transacción

Tras iniciar un pago preautorizado, supervisa su progreso mediante estos métodos:

> [card] [Webhooks (recomendado)](https://docs.localpayment.com/es/docs/webhooks.md)
>
> Recibe notificaciones en tiempo real cuando cambie el estado de la transacción. Más eficiente para entornos de producción.

> [card] [Endpoint de la API de estado](https://docs.localpayment.com/es/reference/get-transaction-status.md)
>
> Consulta el estado de las transacciones mediante programación. Útil para sondear o recuperar notificaciones de webhook perdidas.

> [card] [Vista del Business Portal](https://docs.localpayment.com/es/docs/dashboard-overview.md)
>
> Interfaz visual para el seguimiento de transacciones. Ideal para la supervisión manual y el análisis detallado de las transacciones.

### Códigos de estado comunes

La API de Localpayment proporciona varios códigos de estado para indicar el progreso y el resultado del pago en la respuesta.

| Código | Estado | Descripción |
| :- | :- | :- |
| `103` | `APPROVED` | El payin se confirmó, pero aún no se ha abonado. |
| `200` | `Completed` | El payin se ha completado. |
| `701` | `Rejected` | Número de cuenta bancaria no válido. |

> [!NOTE]
>
> **APPROVED no es el estado final.** Significa que el pago con tarjeta se confirmó, pero los fondos aún no se abonaron a tu saldo. Puedes ver el pago, pero no puedes retirar los fondos hasta que el estado cambie a Completed. Esto suele tardar de 1 a 2 días, según el proveedor.

> [!NOTE]
>
> Para consultar la referencia completa de códigos de estado, consulta la documentación sobre el [estado de las transacciones](https://docs.localpayment.com/reference/payin-status-error-codes.md).

## Probando tu integración

### Escenarios de prueba

Verifica que tu integración gestione estos escenarios:

1. **Transacción exitosa**: Flujo de pago estándar
2. **Errores de validación**: Cuenta bancaria no válida, campos faltantes
3. **Retrasos en el procesamiento**: Transacciones que requieren tiempo para procesarse.
4. **Transacciones fallidas**: Fondos insuficientes, beneficiarios bloqueados
5. **Actualizaciones de estado**: Gestión de webhooks y sondeo de estado

***

## Próximos pasos

Una vez procesada la preautorización, es posible que debas realizar acciones adicionales, como las siguientes:

> [card] [Reembolsar la transacción](https://docs.localpayment.com/docs/refunds/)
>
> Si es necesario, puedes reembolsar el pago al cliente. Consulta la documentación sobre reembolsos para obtener más información.

> [card] [Gestionar las devoluciones de cargo](https://docs.localpayment.com/docs/chargebacks.md)
>
> En caso de disputa, es posible que debas gestionar las devoluciones de cargo. Consulta la documentación sobre devoluciones de cargo para obtener información sobre este proceso.

> [card] [Revisar los detalles de la transacción](https://docs.localpayment.com/reference/get-transaction-status.md)
>
> Obtén información sobre las transacciones mediante la API de Localpayment. Consulta la documentación sobre información de transacciones para obtener más detalles.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.