Tarjeta

Crear un pago con tarjeta en Perú consiste en capturar los datos necesarios del cliente para el pago y hacer una solicitud a través de nuestra API con un bearer token y una firma secreta. De esta forma, las transacciones se autentican y se realizan de forma segura.

Los pagos con tarjeta cuentan con la herramienta automatizada Decision Manager (DM) del motor de gestión de riesgos y prevención de fraude de Cybersource (A Visa Solution), junto con el sistema 3DS, el cual activa los desafíos (challenges) correspondientes para validar o rechazar transacciones.

¿Cómo funciona?

El proceso de pago con tarjeta en Perú consta de cinco etapas principales:

1. Selección de método. El cliente elige pagar con tarjeta en tu sitio web o aplicación.
2. Ingreso de datos. El cliente llena los datos requeridos en el formulario de pago con tarjeta, como: número de tarjeta, fecha de vencimiento, CVV, nombre y correo electrónico. Si tienes activadas las opciones, el cliente verá también la opción de pagar en cuotas y la de recordar tarjeta.
3. Validación de datos. Se verifican los datos con el emisor de la tarjeta.
4. Autorización y Captura. Se verifica que existan los fondos suficientes, y se mueven desde el banco del cliente hacia la cuenta de tu comercio.
5. Confirmación. El cliente ve en pantalla el resultado de la transacción. A su vez, tu comercio recibe la confirmación a través de los webhooks que hayas configurado.

Especificaciones

El pago con tarjeta en Perú cuenta con características extras. Algunas de ellas las puedes activar o desactivar en la Consola, según lo requieras. A continuación se detallan.

Pago en cuotas

El switch de pago con cuotas puede encenderse o apagarse desde la Consola. Al estar encendido, la opción de cuotas se mostrará en automático en el formulario. El número de cuotas son definidas por el emisor de la tarjeta, así como por el banco del usuario.

Recordar tarjeta

Esta función también puede ser controlada desde la Consola. Si se habilita, al cliente le aparecerá un campo extra en su formulario de pago con la opción de recordar su tarjeta para futuras compras. Podrá asignarle un alias a cada tarjeta que decida guardar:

📘

Monedas

Si el cliente guarda una tarjeta después de un pago en soles, esa tarjeta guardada solo se podrá utilizar para pagos futuros en soles. Si desea usarla en dólares, deberá guardarla nuevamente en dólares.

Pago con tarjetas foráneas

Nuestro sistema cuenta con soporte de pagos con tarjetas foráneas. Se detectará en automático cuando se trata de una tarjeta de este tipo, con lo cual, el cliente verá dos campos extras en su formulario de pagos (ciudad y país de la tarjeta):

Crea un nuevo pago

Tu front-end será el encargado de recopilar los datos necesarios de tu cliente para procesar el pago, mientras que tu back-end estará integrado con nuestra API, procesando el pago.

De este modo, para crear una solicitud de nuevo pago deberás usar este endpoint y colocar pe_card_payment como método de pago en el body de la solicitud.

La solicitud se envía con tu bearer token, así como con tu firma secreta. Además, debes incluir los datos necesarios del cliente para hacer el pago, como: nombre, correo electrónico, teléfono, país, moneda, monto, entre otros.

🚧

Firma de la transacción

Puedes ver el detalle de cómo firmar los parámetros de la transacción con tu secretKey en este artículo.

También deberás incluir la URL de retorno en caso de que la transacción sea exitosa, así como una URL en caso de que el pago sea rechazado.

📘

Notificación del estado de la transacción

Para configurar el webhook que irá en el campo confirmationURL y recibir notificaciones con el estado de tu transacción, revisa este artículo.

A continuación puedes ver un ejemplo de request:

{ 
  "currency": "PEN", 
  "country": "PE", 
  "amount": "10",
  "clientName" : "John Doe", 
  "clientEmail" : "[email protected]", 
  "clientPhone" : "999999999", 
  "clientDocument" : "12345678912", 
  "paymentMethod" : "pe_card_payment", 
  "urlConfirmation" : "Webhook", 
  "urlFinal" : "example.com/successful", 
  "urlRejected" : "example.com/declined", 
  "order" : "1234", 
  "theme": "[{\"bgColor\": \"transparent\", \"mode\": \"dark\"}]",
  "sign" : "Signature of the parameters" 
}

Puedes ajustar la apariencia de tu formulario con el parámetro opcional theme cambiando el color de fondo o creando versiones modo claro y modo oscuro.

Respuesta

Como respuesta a una solicitud de pago exitosa, recibirás un enlace para procesar el pago, así como un identificador de pago del sistema.

Ejemplo de respuesta para pago exitoso:

{ 
   "urlPay" : "Link to redirect or Iframe to insert",
   "uid" : "ID in our services",
   "reference": "Reference in our services" 
}

Ejemplo de respuesta de pago rechazado:

{ 
   "uid": "ID in our services",
   "status": "rejected",
   "reference": "Reason for rejection" 
}

Confirmación de un pago

Una vez que el usuario haya completado el proceso de pago en el formulario, ProntoPaga le mostrará una ventana con el resultado final de su transacción. Al mismo tiempo, devolverá los datos de la transacción a la URL que especificaste en urlConfirmation.

Para confirmar si una transacción fue exitosa, debes verificar que en tu webhook el valor del campo status sea success.

Conoce todos los estados posibles de un pago en el siguiente enlace: Estados de los pay ins.

Ejemplo de webhook para un pago exitoso:

{ 
  "uid":"01HZ7HFEJZ0GN2TYNDDXC456F", 
  "status":"success", 
  "amount":10, 
  "method":"PE Tarjeta", 
  "reference":"1687348107370523",
  "clientEmail" : "[email protected]",
  "clientDocument" : "999999999",         
  "order":"30023", 
  "currency":"PEN", 
  "country":"PE", 
  "method_type":"TDD", 
  "method_detail":"6623 VD", 
  "hash":"25aGF34G33HG34H41111",
  "note":null, 
  "sign":"e6f27650e5e7703949b0f2be41dde1aeab84145595c4183271e0a42f1500aa"
} 

Detalles de un pago

Si así lo deseas, puedes consultar este endpoint para conocer los detalles del pago. De ser exitosa la consulta, obtendrás una respuesta similar a la siguiente:

{ 
  "uid": [string] // Transaction Identifier 
  "status": [string] // Transaction status 
  "amount": [integer] // Transaction amount 
  "method": [string] // Payment method used 
  "reference": [string] // Reference of the transaction 
  "clientEmail": [string] // Client's email address 
  "clientDocument": [string] // Customer's ID number 
  "order": [string] // Payment identifier to be associated with 
  "currency": [string] // ISO currency code 
  "country": [string] // International Country Format 
  "method_type": [string] // Method type 
  "method_detail": [string] // Method details 
  "hash": [string] // Security hash parameter 
  "sign": [string] // Signature of the parameters
}

Motivos de rechazo

A continuación se muestran varios posibles casos de rechazo junto con su código y descripción. Además, incluimos posibles datos de prueba para utilizar en cada caso:

Prueba tu integración

Contamos con un catálogo de datos de prueba que puedes usar para comprobar que tu integración está lista, así como para ver el flujo de pago que seguirá tu cliente. Además, también puedes hacer pruebas con nuestros demos.

Antes de finalizar tu integración

Estos son algunos puntos importantes a tomar en cuenta, antes de finalizar tu integración con nosotros:

• No almacenar datos sensibles del cliente en tu base de datos.
• Enviar todos los datos requeridos en el body request del endpoint de creación de pago.
• Agregar los logotipos de los diferentes métodos de pago de ProntoPaga a tu front-end. Puedes descargarlos aquí.