# Cards

Puedes empezar a aceptar pagos con tarjeta en la Web usando la [Página de pago alojada](https://docs.monei.com/es/es/integrations/use-prebuilt-payment-page/.md) o el [Componente Card Input](https://docs.monei.com/es/es/monei-js/reference/.md#cardinput-component). No se necesita ninguna configuración adicional para la Página de pago alojada. Ya admite todos los métodos de pago disponibles y no requiere programación.

Nuestro [Componente Card Input](https://docs.monei.com/es/es/monei-js/reference/.md#cardinput-component) renderiza un campo de entrada de tarjeta en tu página de pago personalizada. El Componente Card Input te permite recopilar de forma segura los datos de la tarjeta en un único componente. Incluye un icono de marca de tarjeta que se actualiza dinámicamente, así como campos para el número, la fecha de caducidad y el CVC. Es responsivo, está optimizado para dispositivos móviles, es completamente personalizable y está localizado a 14 idiomas.

[](https://payments-demo.monei.com)

[Demo en vivo](https://payments-demo.monei.com)

[Código fuente](https://github.com/MONEI/monei-payments-demo)

## Antes de empezar[​](#antes-de-empezar "Enlace directo al Antes de empezar")

Esta página explica cómo añadir el Componente Card Input a tu página de pago personalizada. Si no necesitas una experiencia de checkout personalizada, te recomendamos usar nuestra [Página de pago alojada](https://docs.monei.com/es/es/integrations/use-prebuilt-payment-page/.md).

Para aceptar pagos con tarjeta necesitas tener al menos un procesador de tarjetas configurado. Para configurar los procesadores de tarjetas ve a [MONEI Dashboard → Ajustes → Métodos de pago → Pagos con tarjeta](https://dashboard.monei.com/settings/payment-methods/card).

Para probar tu integración:

* Usa tu Account ID y clave de API del [modo de prueba](https://docs.monei.com/es/es/testing/.md).
* Usa los [números de tarjeta](https://docs.monei.com/es/es/testing/.md#test-card-numbers) de prueba.
* Puedes comprobar el estado de un pago de prueba en tu [MONEI Dashboard → Pagos](https://dashboard.monei.com/payments) (en modo de prueba).

## Integración[​](#integración "Enlace directo al Integración")

### 1. Crear un pago `Servidor`[​](#1-crear-un-pago-servidor "Enlace directo al 1-crear-un-pago-servidor")

Crea un [Pago](https://docs.monei.com/es/es/apis/rest/schemas/payment/.md) en tu servidor con un importe y una moneda. Decide siempre cuánto cobrar en el lado del servidor, un entorno de confianza, y no en el cliente. Esto evita que clientes malintencionados puedan elegir sus propios precios.

<!-- -->

* cURL
* Node.js
* PHP
* Python

POST https\://api.monei.com/v1/payments

```
curl --request POST 'https://api.monei.com/v1/payments' \

--header 'Authorization: YOUR_API_KEY' \

--header 'Content-Type: application/json' \

--data-raw '{

  "amount": 110,

  "currency": "EUR",

  "orderId": "14379133960355",

  "description": "Test Shop - #14379133960355",

  "customer": {

    "email": "email@example.com"

   },

  "callbackUrl": "https://example.com/checkout/callback"

}'
```

(Sustituye `YOUR_API_KEY` por tu clave de API de MONEI real)

server.js

```
import {Monei} from '@monei-js/node-sdk';



// Replace YOUR_API_KEY with your actual MONEI API key

const monei = new Monei('YOUR_API_KEY');



const payment = await monei.payments.create({

  amount: 110,

  currency: 'EUR',

  orderId: '14379133960355',

  description: 'Test Shop - #14379133960355',

  customer: {

    email: 'email@example.com'

  },

  callbackUrl: 'https://example.com/checkout/callback'

});



// Pass payment.id to your client-side

const paymentId = payment.id;
```

server.php

```
<?php

require_once 'vendor/autoload.php';



use Monei\Model\CreatePaymentRequest;

use Monei\Model\PaymentCustomer;

use Monei\MoneiClient;



// Replace YOUR_API_KEY with your actual MONEI API key

$monei = new MoneiClient('YOUR_API_KEY');



$payment = $monei->payments->create(

  new CreatePaymentRequest([

    'amount' => 110,

    'currency' => 'EUR',

    'order_id' => '14379133960355',

    'description' => 'Test Shop - #14379133960355',

    'customer' => new PaymentCustomer([

      'email' => 'email@example.com'

    ]),

    'callback_url' => 'https://example.com/checkout/callback'

  ])

);



// Pass payment ID to your client-side

$paymentId = $payment->getId();

?>
```

server.py

```
import Monei

from Monei import CreatePaymentRequest, PaymentCustomer



# Replace YOUR_API_KEY with your actual MONEI API key

monei = Monei.MoneiClient(api_key="YOUR_API_KEY")



payment = monei.payments.create(

    CreatePaymentRequest(

        amount=110,

        currency="EUR",

        order_id="14379133960355",

        description="Test Shop - #14379133960355",

        customer=PaymentCustomer(

          email="email@example.com"

        ),

        callback_url="https://example.com/checkout/callback"

    )

)



# Pass payment ID to your client-side

payment_id = payment.id
```

Los siguientes parámetros son obligatorios:

* **amount** entero positivo - Importe que se pretende cobrar con este pago. Un entero positivo que representa cuánto cobrar en la unidad de moneda más pequeña (p. ej., 100 céntimos para cobrar 1,00 USD)
* **currency** cadena - Código de moneda [ISO](https://en.wikipedia.org/wiki/ISO_4217) de tres letras, en mayúsculas. Debe ser una moneda compatible.
* **orderId** cadena - Un ID de pedido de tu sistema. Un identificador único que puede usarse para conciliar el pago con tu sistema interno.
* **callbackUrl** cadena - La URL a la que se enviará de forma asíncrona el resultado del pago.

Consulta todos los [parámetros de solicitud](https://docs.monei.com/es/es/apis/rest/payments-create/.md) disponibles.

El objeto Pago devuelto incluye un `id` de pago, que se usa en el lado del cliente para completar de forma segura el proceso de pago en lugar de pasar el objeto Pago completo.

### 2. Recopilar los datos de la tarjeta `Cliente`[​](#2-recopilar-los-datos-de-la-tarjeta-cliente "Enlace directo al 2-recopilar-los-datos-de-la-tarjeta-cliente")

Incluye `monei.js` en tu página de checkout añadiendo la etiqueta script al `head` de tu archivo HTML.

checkout.html

```
<head>

  <title>Checkout</title>

  <script src="https://js.monei.com/v3/monei.js"></script>

</head>
```

Añade el [Componente Card Input](https://docs.monei.com/es/es/monei-js/reference/.md#cardinput-component) de MONEI a tu página de pago. Crea nodos DOM vacíos (contenedores) con IDs únicos en tu formulario de pago.

checkout.html

```
<form id="payment-form">

  <div class="card-field">

    <div id="card-input">

      <!-- A MONEI Card Input Component will be inserted here. -->

    </div>

    <!-- Used to display card errors. -->

    <div id="card-error"></div>

  </div>

  <button type="submit" id="payment-button">Submit payment</button>

</form>
```

Inicializar el Componente Card Input

client.js

```
const container = document.getElementById('card-input');

const errorText = document.getElementById('card-error');



// Create an instance of the Card Input using payment_id.

const cardInput = monei.CardInput({

  paymentId: '{{payment_id}}',

  onChange: function (event) {

    // Handle real-time validation errors.

    if (event.isTouched && event.error) {

      container.classList.add('is-invalid');

      errorText.innerText = event.error;

    } else {

      container.classList.remove('is-invalid');

      errorText.innerText = '';

    }

  }

});



// Render an instance of the Card Input into the `card_input` <div>.

cardInput.render(container);
```

El Componente Card Input simplifica el formulario y minimiza el número de campos requeridos insertando un único campo de entrada flexible que recopila de forma segura todos los datos de la tarjeta necesarios.

nota

El Componente Card Input también está disponible como componente de [React](https://docs.monei.com/es/es/monei-js/react/.md), [Vue](https://docs.monei.com/es/es/monei-js/vue/.md), [Angular](https://docs.monei.com/es/es/monei-js/angular/.md) y [Svelte](https://docs.monei.com/es/es/monei-js/svelte/.md).

Consulta la [Referencia de MONEI JS](https://docs.monei.com/es/es/monei-js/reference/.md#cardinput-component) para ver más opciones.

### 3. Confirmar el pago `Cliente`[​](#3-confirmar-el-pago-cliente "Enlace directo al 3-confirmar-el-pago-cliente")

Para completar el pago necesitas confirmarlo usando la función [confirmPayment](https://docs.monei.com/es/es/monei-js/reference/.md#confirmpayment-function) de monei.js.

Debes proporcionar un `paymentId` (obtenido en el [paso 1](#1-create-a-payment-server-side)) y el `paymentToken` generado con el Componente Card Input. También puedes proporcionar parámetros adicionales como `customer.email`. Consulta todos los [parámetros](https://docs.monei.com/es/es/apis/rest/payments-confirm/.md) disponibles.

client.js

```
// Handle form submission.

const paymentForm = document.getElementById('payment-form');

const paymentButton = document.getElementById('payment-button');

paymentForm.addEventListener('submit', async function (event) {

  event.preventDefault();

  paymentButton.disabled = true;

  try {

    // Generate a payment token from the card input

    const {token, error} = await cardInput.submit();



    if (error) {

      // Inform the user if there was an error.

      container.classList.add('is-invalid');

      errorText.innerText = error;

      return;

    }



    container.classList.remove('is-invalid');

    errorText.innerText = '';



    // Confirm the payment with the generated token

    const result = await monei.confirmPayment({

      paymentId: '{{payment_id}}',

      paymentToken: token,

      paymentMethod: {card: {cardholderName: 'JOHN DOE'}}

    });



    // At this moment you can show a customer the payment result

    // But you should always rely on the result passed to the callback endpoint on your server

    // to update the order status

    console.log(result);

  } catch (error) {

    console.error(error);

  } finally {

    paymentButton.disabled = false;

  }

});
```

Tras enviar el formulario, MONEI mostrará automáticamente una ventana emergente con la pantalla de confirmación 3D Secure (si es necesario).

nota

Como proceso alternativo, puedes enviar el `paymentToken` generado a tu servidor y luego [confirmar el pago](https://docs.monei.com/es/es/apis/rest/payments-confirm/.md) en el lado del servidor.

### 4. Procesar la notificación webhook `Servidor`[​](#4-procesar-la-notificación-webhook-servidor "Enlace directo al 4-procesar-la-notificación-webhook-servidor")

Tras la interacción en el lado del cliente y cualquier procesamiento en segundo plano necesario (como 3D Secure o la autorización bancaria), MONEI envía el estado de pago final y autoritativo mediante una solicitud HTTP POST asíncrona a la `callbackUrl` que proporcionaste en el Paso 1.

El cuerpo de la solicitud contiene el objeto [Pago](https://docs.monei.com/es/es/apis/rest/schemas/payment/.md) completo en formato JSON.

Este webhook es la **única forma fiable** de confirmar el resultado definitivo del pago.

**Es imprescindible que:**

1. **Verifiques el encabezado `MONEI-Signature`** incluido en la solicitud. Esto confirma que el webhook proviene genuinamente de MONEI. Consulta la [guía de verificación de firmas](https://docs.monei.com/es/es/guides/verify-signature/.md) para los detalles de implementación.
2. **Devuelvas un código de estado HTTP `200 OK`** inmediatamente al recibir el webhook para confirmar la recepción. Cualquier otro código de estado indica a MONEI que la notificación ha fallado.

Si MONEI no recibe un `200 OK`, reintentará el envío del webhook.

Una vez verificada la firma, inspecciona el campo `status` del objeto Pago (`SUCCEEDED`, `FAILED`, `CANCELED`, etc.) para determinar si debes completar el pedido o gestionar el error.

## Antes de pasar a producción[​](#antes-de-pasar-a-producción "Enlace directo al Antes de pasar a producción")

* Asegúrate de que estás usando el Account ID y la clave de API del [modo de producción (live)](https://docs.monei.com/es/es/testing/.md).
* Asegúrate de que tienes al menos un [procesador de tarjetas habilitado](https://dashboard.monei.com/settings/payment-methods/card).

## Información adicional[​](#información-adicional "Enlace directo al Información adicional")

### Límites de importe[​](#límites-de-importe "Enlace directo al Límites de importe")

El importe máximo predeterminado por transacción con tarjeta es de 4.000 EUR. Este límite puede aumentarse: contacta con nuestro [equipo de soporte](https://support.monei.com/hc/requests/new) para ajustarlo en tu cuenta.

### Reembolsos[​](#reembolsos "Enlace directo al Reembolsos")

Los comercios pueden emitir reembolsos directamente desde el [MONEI Dashboard](https://dashboard.monei.com) en un plazo de 180 días a partir de la fecha de la transacción. Para reembolsos de transacciones más antiguas, ponte en contacto con nuestro [equipo de soporte](https://support.monei.com/hc/requests/new).