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.
Botón de Transferencia Bancolombia: Permite a tus clientes usar sus cuentas de ahorros o corrientes Bancolombia para realizar el pago.
Nequi: Ofrece a tus clientes la posibilidad de usar su cuenta Nequi desde su celular, para completar el pago.
PSE: Permite a tus clientes realizar el pago usando su cuenta bancaria, de ahorros o corriente de cualquier banco colombiano.
Pago en efectivo en Corresponsales Bancarios Bancolombia: Permite a tus clientes realizar el pago en efectivo en cualquiera de los más de 15.000 Corresponsales Bancarios Bancolombia.
PCOL: Permite a tus clientes realizar el pago redimiendo Puntos Colombia.

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

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, MasterCard y American Express, 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:

Debes haber tokenizado una tarjeta previamente (instrucciones a continuación)
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

Para obtener el estado de una transacción en Wompi, utiliza el siguiente endpoint:

GET /v1/transactions/<ID_TRANSACCION>

Asegúrate de reemplazar <ID_TRANSACCION> con el ID real de la transacción que deseas consultar. Este endpoint te proporcionará detalles sobre el estado y la información de pago de la transacción.

A continuación se muestra un ejemplo de los campos necesarios para realizar una nueva transacción con tarjeta de crédito o débito:

{
    "data": {
        "id": "0101010-0101010101-10101",
        "created_at": "2023-01-17T18:16:06.287Z",
        "amount_in_cents": 1000000,
        "reference": "Prime_102305887219213_108224918",
        "currency": "COP",
        "payment_method_type": "CARD",
        "payment_method": {
            "type": "CARD",
            "extra": {
                "name": "MASTERCARD-0110",
                "brand": "MASTERCARD",
                "last_four": "0110",
                "processor_response_code": "51" // Código de respuesta del procesador y/o emisor de la tarjeta
            },
            "installments": 2
        },
        "redirect_url": null,
        "status": "DECLINED",
        "status_message": "Fondos Insuficientes",
        "merchant": {
            "name": "HULU PRIME",
            "legal_name": " HULU S.A.S.",
            "contact_name": "John Doe",
            "phone_number": "+573001111111",
            "logo_url": null,
            "legal_id_type": "NIT",
            "email": "payins+01codiprime@hulu.com",
            "legal_id": "100111111-01"
        },
        "taxes": []
    },
    "meta": {}
}

En la respuesta, se proporciona el processor_response_code, status y status_message de la transacción.

NOTA: Le recomendamos utilizar el campo processor_response_code para obtener la respuesta del procesador. Además, tenga presente que en la respuesta del endpoint puede recibir campos adicionales en el objeto extra.

Es importante verificar periódicamente el estado de una transacción en Wompi desde tu sistema utilizando el ID de transacción y nuestro API con el endpoint GET /v1/transactions/<ID_TRANSACCION>.

Botón de Transferencia Bancolombia

En Wompi, tus clientes pueden completar el pago de una transacción usando su cuenta de ahorros o corriente Bancolombia. El nombre del método de pago que debes usar al crear la transacción es BANCOLOMBIA_TRANSFER.

Al usar el tipo de método de pago BANCOLOMBIA_TRANSFER debes tener en cuenta lo siguiente:

Tu cliente debe escoger qué tipo de persona es en el campo user_type. Por el momento únicamente está disponible Persona Natural, como PERSON
Debes especificar un nombre de lo que se está pagando en el campo payment_description. Máximo 64 caracteres. No puedes incluir comillas simples en este dato (').
Si tu transacción es en el ambiente Sandbox, debes enviar el campo sandbox_status que especificará qué status final quieres simular. Puede ser uno de los siguientes valores: APPROVED, DECLINED o ERROR.

Así, los campos de método de pago una nueva transacción con BANCOLOMBIA_TRANSFER deben ser similares a los siguientes:

{
  "payment_method": {
    "type": "BANCOLOMBIA_TRANSFER",
    "user_type": "PERSON", // Tipo de persona
    "payment_description": "Pago a Tienda Wompi", // Nombre de lo que se está pagando. Máximo 64 caracteres
    // El siguiente dato SOLO aplica si estás haciendo transacciones current Sandbox:
    "sandbox_status": "APPROVED", // Status final deseado current el Sandbox. Uno de los siguientes: APPROVED, DECLINED o ERROR
    "ecommerce_url": "https://comercio.co/thankyou_page" // Permite al cliente omitir la pantalla resumen de la transacción de wompi, y redireccionar a un resumen personalizado current el comercio
  }
  // Otros campos de la transacción a crear...
}

Al crear la transacción, debes consultarla continuamente (long polling) hasta que ésta contenga un campo llamado async_payment_url dentro de un objeto extra, que estará dentro de la propiedad payment_method. Una vez la obtengas, debes redireccionar a tu cliente a esta URL para que complete el pago en la respectiva institución financiera (banco). El campo que debes esperar de la transacción se vería como el siguiente:

{
  "payment_method": {
    "type": "BANCOLOMBIA_TRANSFER",
    // Otros campos del payment_method
    "extra": {
      "async_payment_url": "https://..." // URL para redireccionar al cliente
    }
  }
  // Otros campos de la transacción...
}

Al finalizarse el proceso de pago a través de Bancolombia, éste redireccionará a la redirect_url que hayas especificado originalmente en la transacción, para que puedas verificar el resultado de la transacción, nuevamente con un long polling hasta obtener un status final.

Bancolombia QR

Permite a tus clientes usar sus cuentas a la mano de Bancolombia, cuentas de ahorros o corrientes Bancolombia y cuentas de Nequi, a través de la generación de un QR que deberá ser leído por la respectiva app del banco. El nombre del método de pago que debes usar al crear la transacción es BANCOLOMBIA_QR. Debes tener en cuenta que los pagos a través de este medio solo aplican para personas naturales.

Los campos de método de pago para una nueva transacción con BANCOLOMBIA_QR deben ser similares a los siguientes:

{
  "payment_method": {
    "type": "BANCOLOMBIA_QR",
    "payment_description": "Pago a Tienda Wompi", // Nombre de lo que se está pagando. Máximo 64 caracteres
    // El siguiente dato SOLO aplica si estás haciendo transacciones en Sandbox:
    "sandbox_status": "APPROVED" // Status final deseado en el Sandbox. Uno de los siguientes: APPROVED, DECLINED o ERROR
  }
  // Otros campos de la transacción a crear...
}

Al crear la transacción, debes consultarla continuamente (long polling) hasta que ésta contenga un campo llamado qr_image y qr_id, que estará dentro de la propiedad payment_method, el cual tendrá la imagen del QR en base64 dentro de un objeto extra.

Una vez la obtengas, puedes renderizar el QR en un tag img de la siguiente manera:

<img src="data:image/svg+xml;base64 + ${qr_image}"/>

El campo que debes esperar de la transacción se vería como el siguiente:

{
  "payment_method": {
    "type": "BANCOLOMBIA_QR",
    // Otros campos del payment_method
    "extra": {
      "qr_id": "a3827b90-501b-11ed-ae9b-3156df51ed75", // ID del código QR
      "qr_image": "PD94bWwgdmVyc2lvbj0iK.....", // Imágen del código QR codificada en Base64
      "external_identifier": "d00000000000" //Id de conciliación una vez hecho el pago
    }
  }
  // Otros campos de la transacción...
}

Al finalizarse el proceso de pago a través de BANCOLOMBIA_QR, éste redireccionará a la redirect_url que hayas especificado originalmente en la transacción, para que puedas verificar el resultado de la transacción, nuevamente con un long polling hasta obtener un status final.

Nequi

En Wompi, tus clientes pueden completar el pago de una transacción usando su cuenta Nequi en su celular. El nombre del método de pago que debes usar al crear la transacción es NEQUI.

Al usar el tipo de método de pago NEQUI solamente debes solicitarle a tu cliente un número celular colombiano, de 10 dígitos, que esté registrado con Nequi, para enviarlo dentro de la información necesaria para nuestro API. Recuérdale a tu cliente que debe contar con la app de Nequi instalada en su celular para poder completar el pago usando este método.

Teniendo el número celular, los campos de método de pago una nueva transacción con Nequi deben ser similares a los siguientes:

{
  "payment_method": {
    "type": "NEQUI"
    "phone_number": "3107654321" // Número celular de la cuenta Nequi
  }
  // Otros campos de la transacción a crear...
}

Al crear la transacción, debes indicarle a tus clientes que recibirán una notificación push de parte de Nequi en su celular, en la cual deberán aceptar o rechazar dicha transacción. Este resultado se verá reflejado en Wompi en cuestión de segundos, luego de que el usuario haya tomado acción.

Por último, recuerda siempre verificar periódicamente el estado de una transacción en Wompi desde tu sistema usando el ID de transacción y nuestro API.

PSE

En Wompi, tus clientes pueden completar el pago de una transacción usando su cuenta de ahorros o corriente de cualquier banco colombiano, a través de PSE. El nombre del método de pago que debes usar al crear la transacción es PSE.

Al usar el tipo de método de pago PSE debes tener en cuenta lo siguiente:

Debes obtener primero una lista de instituciones financieras usando nuestro API, en el endpoint GET /v1/pse/financial_institutions
Tu cliente debe escoger en qué institución (banco) quiere realizar el pago
Tu cliente debe especificar el tipo de persona que es: natural (0) o jurídica (1).
Tu cliente debe especificar su tipo y número de documento
Tu cliente debe especificar su nombre completo
Tu cliente debe especificar una cuenta de correo electrónico
Tu cliente debe especificar un número de teléfono
Finalmente debes especificar la descripción de lo que tu cliente está pagando, máximo 64 caracteres

Luego de que tu cliente haya escogido una institución financiera, usa su código (code) como el identificador que vas a enviar al crear la transacción. Así, los campos de método de pago de una nueva transacción tipo PSE deben ser similares a los siguientes:

{
  "customer_email": "cliente@example.com",
  "payment_method": {
    "type": "PSE",
    "user_type": 0, // Tipo de persona, natural (0) o jurídica (1)
    "user_legal_id_type": "CC", // Tipo de documento, CC o NIT
    "user_legal_id": "1099888777", // Número de documento
    "financial_institution_code": "1", // Código (`code`) de la institución financiera
    "payment_description": "Pago a Tienda Wompi, ref: JD38USJW2XPLQA", // Descripción de lo que está pagando. Máximo 64 caracteres
  },
  "customer_data": {
    "phone_number": "573145678901",
    "full_name": "Nombre(s) Apellido(s)"
  }
  // Otros campos de la transacción a crear...
}

{
  "payment_method": {
    // Otros campos del payment_method
    "extra": {
      "async_payment_url": "https://..." // URL para redireccionar al cliente
    }
  },
  // Otros campos de la transacción...
}

Al finalizarse el proceso de pago a través de PSE, éste redireccionará a la redirect_url que hayas especificado originalmente en la transacción, para que puedas verificar el resultado de la transacción, nuevamente con un long polling hasta obtener un status final.

Pago en efectivo en Corresponsales Bancarios Bancolombia

Este medio de pago le permite al tus clientes acercarce a cualquier Corresponsal Bancario Bancolombia y realizar el pago en efectivo. Para generar una intención de pago en efectivo debes seguir los siguientes pasos:

Paso 1: Crea la transacción

Debes crear una transacción insertando BANCOLOMBIA_COLLECT en el campo type de payment_method:

{
  "payment_method": {
    "type": "BANCOLOMBIA_COLLECT" // medio de pago current corresponsal bancario
  }
  // Otros campos de la transacción a crear...
}

Como respuesta obtendrás una transacción con el campo status en PENDING.

Paso 2: Consulta la transacción creada

Después de crear la transacción debes hacer long polling a la misma usando el endpoint el endpoint GET /v1/transactions/<ID_DE_TRANSACCION> hasta obtner la información de convenio que te será presentada de la siguiente manera en el campo payment_method en el objeto extra de la transacción:

{
  "payment_method": {
    "type": "BANCOLOMBIA_COLLECT",
    "extra": {
        "business_agreement_code": "12345", // Esto current un valor de ejemplo
        "payment_intention_identifier": "65770204276" // Esto current un valor de ejemplo
    }
  // El resto de la información de transacción...
}

Paso 3: Comparte la información de pago

Una vez tengas la información de pago como se muestra en el paso anterior, puedes compartir con tus clientes el número de convenio business_agreement_code y el número de intención de pago payment_intention_identifier, para que estos efectúen el pago en cualquier Corresponsal Bancario Bancolombia.

Puntos Colombia (PCOL)

En Wompi, tus clientes pueden completar el pago de una transacción usando pago total con Puntos Colombia o Puntos + un segundo metodo de pago: Tarjetas de Crédito o Débito, Botón de Transferencia Bancolombia, Nequi, PSE. Para crear una transacción con pago con Puntos Colombia, el nombre del método de pago que debes usar es PCOL.

Paso 1: Crea la transacción con Método de pago PCOL

Para crear una transacción de Pago con Puntos (PCOL), los campos del método de pago deben ser similares a los siguientes:

{
  "customer_email": "myemail@mail.com",
    "customer_data": {
      "phone_number": "+573121111111",
      "full_name": "Nombre Apellido"
  },
  "payment_method": {
    "type": "PCOL"    
  }
  // Otros campos de la transacción a crear...
}

Al crear la transacción, debes consultarla continuamente (long polling) hasta que ésta contenga un campo llamado async_payment_url dentro de un objeto extra, que estará dentro de la propiedad payment_method. Una vez la obtengas, debes redireccionar a tu cliente a esta URL para que realice la redención de Puntos. El campo que debes esperar de la transacción se ve como el siguiente:

{
  "payment_method": {
    // Otros campos del payment_method
    "extra": {
      "async_payment_url": "https://..." // URL para redireccionar al cliente
    }
  }
  // Otros campos de la transacción...
}

Paso 2: Validar resultado de la redención en Puntos Colombia

Al finalizarse el proceso de redención a través de PCOL, éste redireccionará a la redirect_url que hayas especificado originalmente en la transacción, para que puedas verificar el resultado de la redención, e identificar si el pago con Puntos fue completo o parcial.

Para esto, al recibir la redirección se debe hacer nuevamente un long polling de la transacción hasta obtener en el campo status diferente de PENDING y los campos point_redeemed, redeemed_amount_in_cents_pcol y remaining_amount_in_cents dentro de un objeto extra, que estará dentro de la propiedad payment_method:

{
  "payment_method": {
    "type": "PCOL",
    "extra": {
      "async_payment_url": "https://...", // URL para redireccionar al cliente
      "points_redeemed": 1000, // Puntos Colombia redimidos
      "remaining_amount_in_cents": 0, // Saldo pendiente por pagar con segundo medio de pago 
      "redeemed_amount_in_cents_pcol": 700000, // Dinero redimido      
    }
  },
  "status": "APPROVED",
  // Otros campos de la transacción...
}

Debes validar el valor recibido en el campo remaining_amount_in_cents: (i) Si este es igual a 0, y el estado de la transacción es APPROVED esto indicará que el cliente realizó el pago total con Puntos y en este caso finaliza la transacción y se puede mostrar el resumen del pago. (ii) Si el valor es igual a 0, y el estado de la transacción es ERROR o DECLINED esto indicará que no se realizó redención de Puntos; en este caso puedes habilitar al cliente la opción de pagar el total de la transacción con un segundo medio de pago. (Paso 3) (iii) Si el valor es mayor a 0, debes habilitar la opción de pagar con segundo medio de pago el valor pendiente por pagar. (Paso 3)

Paso 3: Pago con segundo medio de pago

Si en el paso anterior se cumple la condición (ii) Pago total con segundo medio de pago o (iii) Pago de saldo restante con segundo medio de pago se deberá habilitar la selección del segundo medio de pago (Tarjetas de Crédito o Débito, Botón de Transferencia Bancolombia, Nequi o PSE) para pagar el valor restante (remaining_amount_in_cents). Una vez seleccionado el segundo medio de pago, se deberá crear una segunda transacción asociada a la creada en el Paso 1. Para esto debes seguir las indicaciones del medio de pago respectivo agregando en la petición el campo parent_transaction_id como se muestra a continuación:

Segundo medio de Pago con Tarjeta

{
  "payment_method": {
    "type": "CARD",
    "installments": 2, // Número de cuotas
    "token": "tok_prod_1_BBb749EAB32e97a2D058Dd538a608301" // Token de la tarjeta de crédito
  },
  "parent_transaction_id": "1929-1666902167-47609" // Transacción PCOL
  // Otros campos de la transacción a crear...
}

Segundo medio de Pago con Botón de Transferencia Bancolombia

{
  "payment_method": {
    "type": "BANCOLOMBIA_TRANSFER",
    "user_type": "PERSON", // Tipo de persona
    "payment_description": "Pago a Tienda Wompi", // Nombre de lo que se está pagando. Máximo 64 caracteres
    "ecommerce_url": "https://comercio.co/thankyou_page" // Permite al cliente omitir la pantalla resumen de la transacción de wompi, y redireccionar a un resumen personalizado current el comercio
  },
  "parent_transaction_id": "1929-1666902167-47609" // Transacción PCOL
  // Otros campos de la transacción a crear...
}

Segundo medio de Pago con Nequi

{
  "payment_method": {
    "type": "NEQUI"
    "phone_number": "3107654321" // Número celular de la cuenta Nequi
  },
  "parent_transaction_id": "1929-1666902167-47609" // Transacción PCOL
  // Otros campos de la transacción a crear...
}

Segundo medio de Pago con PSE

{
  "payment_method": {
    "type": "PSE",
    "user_type": 0, // Tipo de persona, natural (0) o jurídica (1)
    "user_legal_id_type": "CC", // Tipo de documento, CC o NIT
    "user_legal_id": "1099888777", // Número de documento
    "financial_institution_code": "1", // Código (`code`) de la institución financiera
    "payment_description": "Pago a Tienda Wompi, ref: JD38USJW2XPLQA", // Nombre de lo que se está pagando. Máximo 30 caracteres
    "ecommerce_url": "https://comercio.co/thankyou_page" // Permite al cliente omitir la pantalla resumen de la transacción de wompi, y redireccionar a un resumen personalizado current el comercio
  },
  "parent_transaction_id": "1929-1666902167-47609" // Transacción PCOL
  // Otros campos de la transacción a crear...
}

Por último, recuerda siempre verificar periódicamente el estado de una transacción en Wompi desde tu sistema usando el ID de transacción y nuestro API, con el endpoint GET /v1/transactions/<ID_DE_TRANSACCION>. Al consultar una transacción PCOL que tenga asociado un segundo medio de pago, encontrarás un campo llamado child_transaction_id dentro de un objeto extra, que estará dentro de la propiedad payment_method; este campo corresponde al identificador de la transacción del segundo medio de pago:

{
  "payment_method": {
    "type": "PCOL",
    "extra": {
      "points_redeemed": 0,
      "async_payment_url": "https://....",
      "external_identifier": "external-id-123",
      "remaining_amount_in_cents": 300000,
      "redeemed_amount_in_cents_pcol": 0,
      "child_transaction_id": "11463-1666651097-12919" // Transacción segundo medio de pago
    }
  }
}

De igual forma, al consultar la transacción asociada (child_transaction_id), encontrarás el identificador de la transacción PCOL:

{
  "payment_method": {
    "type": "NEQUI", // Segundo medio de pago
    "phone_number": "3222222222",
    "extra": {
      "parent_transaction_id": "11463-1666649502-97081" // Transacción PCOL
    }
}

Estados finales de una transacción​

Tarjetas de Crédito o Débito​

Tokeniza una tarjeta​

Realiza la transacción​

Botón de Transferencia Bancolombia​

Bancolombia QR​

Nequi​

PSE​

Pago en efectivo en Corresponsales Bancarios Bancolombia​

Paso 1: Crea la transacción​

Paso 2: Consulta la transacción creada​

Paso 3: Comparte la información de pago​

Puntos Colombia (PCOL)​

Paso 1: Crea la transacción con Método de pago PCOL​

Paso 2: Validar resultado de la redención en Puntos Colombia​

Paso 3: Pago con segundo medio de pago​