Saltar al contenido principal

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

Por defecto recomendamos tokenizar cifrando la información de la tarjeta. Si tu caso de uso no soporta el cifrado, selecciona la pestaña de tokenización simple.

Los pasos para tokenizar cifrando la información de la tarjeta son los siguientes:

  1. Obtén la llave pública (GET /v1/tokens/keys/tokenization).
  2. Genera el JWE con algoritmo RSA-OAEP-256 y CEK AES-GCM-256.
  3. Envía el payload (el JWE como string) a POST /v1/tokens/cards.

Para tokenizar cifrando la información (método recomendado), primero se debe generar un JWE (JSON Web Encryption) con la información de la tarjeta y enviarlo en el campo payload.

La llave pública necesaria para generar el JWE —la cual utiliza el algoritmo RSA-OAEP— puede obtenerse desde el siguiente endpoint:

GET /v1/tokens/keys/tokenization

Para realizar la tokenización de una tarjeta, se debe enviar la información de la tarjeta cifrada al siguiente endpoint.

POST /v1/tokens/cards
Header de autenticación

Usa la llave pública de tu comercio en el header de autorización.
"Authorization": "Bearer [llave pública del comercio]"

El JWE debe ser enviado dentro del campo payload como un string (base64) y para el CEK (Content Encryption Key) del JWE es necesario utilizar AES GCM 256. Suponiendo una función cifrar_jwe, la cual genera el JWE a partir de la información de la tarjeta, la llave pública y el algoritmo a utilizar en el CEK, al endpoint se debe enviar la siguiente información:

{
"payload": cifrar_jwe(
{
"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
},
LLAVE_PUBLICA_CIFRADO,
"RSA-OAEP-256"
)
}

La respuesta exitosa de v1/tokens/cards se verá de la siguiente manera:

{
"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"
}
}

Ejemplos en distintos lenguajes:

BASE_URL

Para Panamá usa https://api.wompi.pa/v1 como BASE_URL en los ejemplos.

encrypt.js
import { pathToFileURL } from 'url'
import { importSPKI, EncryptJWT } from 'jose'

const BASE_URL = '<BASE_URL>'
const WOMPI_PUBLIC_KEY = '...'

const cardInfo = {
number: '4242424242424242',
exp_month: '04',
exp_year: '30',
cvc: '123',
card_holder: 'test test',
}

let cachedPublicKey

async function getPublicKey() {
if (cachedPublicKey) return cachedPublicKey

const response = await fetch(`${BASE_URL}/tokens/keys/tokenization`, {
headers: {
Authorization: `Bearer ${WOMPI_PUBLIC_KEY}`,
'Content-Type': 'application/json',
},
})

if (!response.ok) {
const body = await response.text()
throw new Error(`Unable to fetch public key. Status ${response.status}: ${body}`)
}

const body = await response.json()
const publicKeyPem = body?.data?.publicKey
if (!publicKeyPem) throw new Error('Public key missing in response')

cachedPublicKey = publicKeyPem
return cachedPublicKey
}

async function tokenizeCard(payload) {
const response = await fetch(`${BASE_URL}/tokens/cards`, {
method: 'POST',
headers: {
Authorization: `Bearer ${WOMPI_PUBLIC_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify(payload),
})

const body = await response.json()
if (!response.ok) {
throw new Error(
`Tokenization failed - Status ${response.status}: ${JSON.stringify(body)}`
)
}

return body
}

export async function encryptCardInfo(cardInfo, pubKey) {
const secret = await importSPKI(pubKey, 'RSA-OAEP-256')
const encryptedData = await new EncryptJWT(cardInfo)
.setProtectedHeader({ alg: 'RSA-OAEP-256', enc: 'A256GCM' })
.encrypt(secret)

return encryptedData
}

const main = async () => {
try {
const publicKey = await getPublicKey()
const encrypted = await encryptCardInfo(cardInfo, publicKey)
console.log("encypted:", encrypted)
const tokenizationResponnse = await tokenizeCard({ payload: encrypted })
console.log(tokenizationResponnse)
return tokenizationResponnse
} catch (error) {
console.error('Tokenization failed:', error)
process.exitCode = 1
}
}

if (import.meta.url === pathToFileURL(process.argv[1]).href) {
main()
}
¡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": {}
}

Pago simple clave