> ## 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.

# Pagos únicos

​Localpayment permite a los comercios procesar pagos únicos mediante tarjetas de crédito y débito, en múltiples países y divisas.

Esta guía describe el proceso para iniciar un pago único con tarjeta a través de la API de Localpayment, detallando los parámetros necesarios, el manejo de las respuestas y la interpretación de los códigos de estado.

## Antes de comenzar

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 un pago con tarjeta

Para iniciar un pago único con tarjeta, deberás enviar una solicitud `POST` al endpoint [Crear Payin](https://docs.localpayment.com/es/reference/payins.md).

### Parámetros clave de la solicitud

La solicitud requiere varios objetos clave:

| Parámetro | Descripción | Requerido |
| - | - | - |
| `payer` | Información del pagador 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 `paymentMethod.code` depende del país, la marca de la tarjeta y el 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' \
  --data '{
    "paymentMethod": {
        "type": "CreditCard",
        "code": "1600",
        "flow": "DIRECT"
    },
    "externalId": "dffbd2a6-6e65-469b-8bbe-dac269882220",
    "country": "MEX",
    "currency": "MXN",
    "amount": 1000,
    "accountNumber": "{{accountNumber}}",
    "conceptCode": "0001",
    "merchant": {
        "type": "COMPANY",
        "name": "Company",
        "document": {
            "type": "RFC",
            "id": "XXX840510XX1"
        },
        "email": "mail@company.com"
    },
    "payer": {
        "type": "INDIVIDUAL",
        "name": "John",
        "lastname": "Doe",
        "document": {
            "type": "RFC",
            "id": "YYY180222YY6"
        },
        "email": "john.doe@example.com"
    },
    "card": {
        "number": "4000000000000002",
        "cvv": "123",
        "expirationMonth": "12",
        "expirationYear": "2029"
    }
}'
```

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

### Pago con tarjeta tokenizada

Si ya has tokenizado la tarjeta de un cliente, puedes usar el token en lugar de enviar los datos completos de la tarjeta para procesar un pago único. Esto mejora la seguridad y simplifica el proceso de pago al eliminar la necesidad de solicitar la información de la tarjeta nuevamente.

Para obtener información detallada sobre la tokenización de tarjetas, consulta la documentación sobre [tokenización](https://docs.localpayment.com/es/docs/tokenization.md).

### Pago con 3D Secure

Si el titular de la tarjeta requiere autenticación adicional, el proceso se realizará mediante 3D Secure. En este caso, Localpayment devuelve la URL de desafío del emisor en la respuesta de la API, y es responsabilidad del comercio redirigir al cliente o mostrar el desafío durante el proceso de pago. Esto permite al titular de la tarjeta completar la verificación requerida. La experiencia exacta con 3D Secure puede variar según el emisor y el país del cliente.

Para obtener información detallada sobre los pagos 3D Secure, consulta la documentación de [3D Secure](https://docs.localpayment.com/es/docs/3d-secure.md).

***

## 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": "dffbd2a6-6e65-469b-8bbe-dac269882220",
  "internalId": "22b29c98-92af-44bd-a164-1863ae2f1bb3",
  "paymentMethod": {
    "type": "CreditCard",
    "code": "1000",
    "flow": "DIRECT"
  },
  "country": "MEX",
  "currency": "MXN",
  "amount": 1000,
  "accountNumber": "{{accountNumber}}",
  "confirmed": {
    "currency": "MXN",
    "amount": 1000,
    "fxQuote": 1,
    "exchangeRateToken": null
  },
  "payment": {
    "installment": null,
    "currency": "MXN",
    "fxQuote": 1,
    "financingFee": 0,
    "amount": 1000
  },
  "localTaxes": [],
  "withHoldings": [],
  "fees": {
    "description": "Fee",
    "currency": "MXN",
    "fxSource": 210.8,
    "fxQuote": 1,
    "amount": 13.02,
    "account": "{{accountNumber}}"
  },
  "status": {
    "code": "103",
    "description": "APPROVED",
    "detail": "The payin was confirmed but not credited yet"
  },
  "ticket": null,
  "qr": null,
  "beneficiary": null,
  "merchant": {
    "type": "COMPANY",
    "name": "Company"
  },
  "payer": {
    "type": "INDIVIDUAL",
    "name": "John",
    "lastname": "Doe",
    "document": {
      "id": "YYY180222YY6",
      "type": "RFC"
    },
    "email": "john.doe@example.com",
    "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": "400000",
    "brand": "VISA",
    "country": "RS",
    "name": "John Doe",
    "last4": "0002",
    "expirationYear": 2029,
    "expirationMonth": 12
  },
  "errors": []
}
```

### Campos de respuesta clave

| Parámetro | 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 la transacción actual. | Monitoreo del 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: Seguimiento del estado de la transacción

Tras iniciar un pago único, 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. |
| `300` | `Rejected` | Parámetro no válido + \[nombre del parámetro] + \[motivo]. |

> [!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]
>
> **Referencia completa**
>
> Consulta todos los códigos de estado en nuestra [documentación sobre el estado de las transacciones](https://docs.localpayment.com/es/reference/transaction-status-error-codes).

***

## 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 procesado un pago único, es posible que debas realizar acciones adicionales, tales como:

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

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

> [card] [Revisar los detalles de la transacción](https://docs.localpayment.com/es/reference/get-transaction-status.md)
>
> Puedes recuperar información sobre las transacciones utilizando la API de Localpayment para obtener información detallada.


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