Métodos de pago

Cambio importante en el API

Para la creación de transacciones y fuentes de pago, pensando en la privacidad y el correcto manejo de los datos personales de nuestros usuarios, es ahora obligatorio el uso de Tokens de Aceptación a la hora de crear cualquiera de estos dos recursos a través de nuestro API.

Cada vez que creas una transacción usando nuestro API, tienes la opción de procesar el pago usando distintos métodos de pago. Actualmente se encuentran disponibles los siguientes métodos de pago:

• Tarjetas de Crédito o Débito: Permite a tus clientes usar tarjetas de crédito o débito para realizar el pago.
• Clave: Ofrece a tus clientes la posibilidad de usar su tarjeta Clave, para completar el pago.

Para usar un método de pago al hacer POST en el endpoint de /transactions debes:

1. Especificar el campo payment_method con un objeto JSON que contiene detalles específicos de cada método, descritos más abajo.

Al finalizar el proceso de pago de cualquiera de los métodos disponibles, te recomendamos siempre verificar periódicamente (long polling) el estado de una transacción, esperando un status final (aprobada, rechazada o error), usando el ID de transacción y nuestro API, ya que ninguno de los métodos de pago otorga un resultado síncrono (inmediato). Una transacción recién creada siempre tiene un status: PENDING.

Estados finales de una transacción

El status final posible de una transacción puede ser: APPROVED (aprobada), DECLINED (rechazada), VOIDED (anulada, sólo aplica para transacciones con Tarjeta) o ERROR (si sucedió algún error externo a Wompi autorizando la transacción).

Tarjetas de Crédito o Débito

En Wompi, tus clientes pueden procesar pagos usando tarjetas crédito y débito de las franquicias Visa y MasterCard, siempre y cuando cuenten con un CVC (Código de Verificación de Tarjeta), usualmente impreso en el reverso de la tarjeta, lo que significa que está habilitada para comprar en internet.

El nombre del método de pago que debes usar al crear la transacción es CARD. Al usar el tipo de método de pago CARD debes tener en cuenta que:

1. Debes haber tokenizado una tarjeta previamente (instrucciones a continuación)
2. Debes haber preguntado a tu usuario en cuántas cuotas desea hacer el pago.

¡No guardes nunca la información de una tarjeta!

Desaconsejamos completamente que guardes información sensible de tarjetas. No sólo pones en riesgo la información de tus usuarios sino que puedes enfrentar sanciones económicas y problemas legales. Wompi cuenta con una certificación PCI DSS para al manejo, transmisión y procesamiento seguro de datos de tarjeta, de manera que ningún comercio deba guardar estos datos, usando únicamente los tokens seguros generados.

Tokeniza una tarjeta

Para tokenizar de manera segura una tarjeta debes usar nuestro endpoint (autenticado con tu llave pública):

POST /v1/tokens/cards

A este endpoint, debes enviar la siguiente información de la tarjeta:

{
  "number": "4242424242424242", // Número de la tarjeta
  "cvc": "123", // Código de seguridad de la tarjeta (3 o 4 dígitos según corresponda)
  "exp_month": "08", // Mes de expiración (string de 2 dígitos)
  "exp_year": "28", // Año expresado current 2 dígitos
  "card_holder": "José Pérez" // Nombre del tarjetahabiente
}

A lo que el endpoint responderá:

{
  "status": "CREATED",
  "data": {
    "id": "tok_prod_1_BBb749EAB32e97a2D058Dd538a608301", // TOKEN que debe ser usado para crear la transacción
    "created_at": "2020-01-02T18:52:35.850+00:00",
    "brand": "VISA",
    "name": "VISA-4242",
    "last_four": "4242",
    "bin": "424242",
    "exp_year": "28",
    "exp_month": "08",
    "card_holder": "José Pérez",
    "expires_at": "2020-06-30T18:52:35.000Z"
  }
}

De esta respuesta, el valor del campo "id" es el token que debes usar dentro del método de pago (en este caso "tok_prod_1_BBb749EAB32e97a2D058Dd538a608301"), para posteriormente crear una transacción.

¡No uses un token más de dos veces!

Si necesitas hacer múltiples cobros a una misma tarjeta, utiliza Fuentes de Pago.

Realiza la transacción

Teniendo estos detalles, y habiéndole preguntado al usuario final el número de cuotas ("installments") en los que desea pagar, los campos de método de pago de una nueva transacción con tarjeta de crédito o débito deben ser similares a los siguientes:

{
  "payment_method": {
    "type": "CARD",
    "installments": 1, // Número de cuotas
    "token": "tok_prod_1_BBb749EAB32e97a2D058Dd538a608301" // Token de la tarjeta de crédito
  }
  // Otros campos de la transacción a crear...
}

Por último, recuerda siempre verificar periódicamente el status de la transacción en Wompi desde tu sistema usando el ID de transacción y nuestro API con el endpoint GET /v1/transactions/<ID_TRANSACCION>.

Clave

Te guiáremos en el proceso de utilizar el medio de pago Clave en nuestra API. Clave es un sistema de tarjetas perteneciente a la compañía Telered en Panamá que ofrece a tus clientes una forma segura de procesar pagos en tu plataforma.

Crear la transacción

Debes crear una nueva transacción utilizando el endpoint POST /v1/transactions. Asegúrate de incluir los siguientes campos específicos para el método de pago Clave:

{
  "payment_method": {
    "type": "CLAVE"
  },
  // Otros campos de la transacción a crear...
  "amount_in_cents": 2000,
  "currency": "USD",
  "customer_email": "{{EMAIL}}",
  "reference": "{{REFERENCE}}",
  "acceptance_token": "{{ACCEPTANCE_TOKEN}}"
}

Consultar la transacción

Después de crear la transacción, es esencial verificar periódicamente los cambios en la transacción a través del API de Wompi utilizando el ID de transacción. Puedes hacer esto utilizando el endpoint GET /v1/transactions/<ID_TRANSACCION>.

Una vez obtenida la respuesta, debes validar el campo data->payment_method->extra->clave_auth->url. Esta URL deberá ser cargada en un elemento <iframe> dentro de tu página de pago. Aquí, tus clientes interactuarán con el sistema Clave para continuar el proceso de la transacción. Al finalizar exitosamente el proceso, el campo data->status cambiará a APPROVED, DECLINED o ERROR según corresponda.

Aquí tienes un ejemplo de la estructura de la respuesta:

{
  "data": {
    "id": "1156-1689191638-98479",
    "created_at": "2023-07-12T19:53:58.190Z",
    "amount_in_cents": 1000,
    "reference": "refence_test1",
    "currency": "USD",
    "payment_method_type": "CLAVE",
    "payment_method": {
      "type": "CLAVE",
      "extra": {
        "clave_auth": {
          "url": "URL_TEST",
          "session_id": "12345",
          "client_session_id": "12345"
        }
      }
    },
    "redirect_url": null,
    "status": "PENDING",
    "status_message": null,
    "merchant": {
      "name": "Comercio De Prueba",
      "legal_name": "Comercio De Prueba",
      "contact_name": "Pepito Perez",
      "phone_number": "+507123456789",
      "logo_url": null,
      "legal_id_type": "RUC",
      "email": "test@wompi.com",
      "legal_id": "123456789-1"
    },
    "taxes": []
  },
  "meta": {}
}