Acepta pesos colombianos (Bre-B, Nequi, Daviplata)

Recibe pagos de compradores en Colombia en el checkout alojado o desde tus propias pantallas, prueba cada canal y reembolsa dentro de 96 horas.

Qué vas a hacer

Los pesos llegan a un saldo COP aparte, netos de tu comisión COP (estándar 4,5% + COP 1.500 por pago; ver la página de Precios). El mínimo por pago es COP 20.000. En el checkout alojado pones el precio en USD y VEXPay le muestra al comprador el monto en pesos.

COP habilitado en tu cuenta por VEXPay.
Un endpoint de webhook suscrito a payment.completed, payment.failed, payment.canceled y payment.reversed.

Pasos: checkout alojado

Crea una sesión
POST /v1/checkout/sessions con amountUsd y methods que incluya cop (o sin methods).
El comprador elige COP
El checkout muestra el total en pesos y luego Bre-B, Nequi y Daviplata.
El comprador completa el canal
Bre-B: escanea el QR o copia la llave en cualquier app bancaria colombiana (unos 15 minutos). Nequi: aprueba la notificación en la app (unos 5 minutos). Daviplata: escribe el código de 6 dígitos que llega por SMS.
Entrega desde el webhook
payment.completed con method: "COP", amountCop, feeCop, amountUsd y la referencia de tu checkoutSession.

Pasos: tus propias pantallas (API)

Crea el pago
POST /v1/cop/payments con un encabezado Idempotency-Key, amountCop (pesos enteros, mínimo 20.000), channel (breb, nequi o daviplata) y buyer (obligatorio para Nequi y Daviplata: email, teléfono de 10 dígitos que empieza por 3, tipo y número de documento).
Muestra el siguiente paso
El campo next de la respuesta te dice qué mostrar: show_qr (imagen QR y llave — se devuelven una sola vez), approve_in_app o submit_otp.
Solo Daviplata: envía el código
POST /v1/cop/payments/:id/otp con { "otp": "…" }. Un código errado se puede reintentar mientras el pago esté pendiente.
Espera el resultado
Reacciona a payment.completed o payment.failed, o lee GET /v1/cop/payments/:id. Cancela un pago pendiente con POST /v1/cop/payments/:id/cancel.

curlbash

curl --request POST "${API_URL}/v1/cop/payments" \
  --header "content-type: application/json" \
  --header "x-api-key: ${VEXPAY_API_KEY}" \
  --header "Idempotency-Key: order-5120" \
  --data '{
    "amountCop": 50000,
    "channel": "nequi",
    "reference": "order-5120",
    "buyer": { "email": "juan@example.com", "phone": "3001234567", "documentType": "CC", "documentNumber": "1234567890" }
  }'

Comprueba que funcionó

Nequi en Test: cualquier dato válido se completa cerca de un minuto después. Daviplata en Test: código 123456. Nunca envíes pesos reales en Test.
GET /v1/cop/payments/:id muestra completed con feeCop.
GET /v1/cop/balance muestra el neto en heldCop (Live) y luego en availableCop.

Reembolsa un pago en pesos

POST /v1/cop/payments/:id/refund reembolsa el monto completo dentro de 96 horas desde que se completó. Tu saldo COP debe cubrir el neto que se acreditó; la comisión COP se devuelve. Luego recibes payment.reversed con status: "refunded". Mira Reembolsos y contracargos.

Si algo sale mal

Síntoma	Causa probable	Qué hacer
403 `method_not_allowed`	COP no habilitado en tu cuenta	Pide a VEXPay que lo habilite.
400 `amount_below_minimum`	Menos de COP 20.000	Sube el monto u ofrece otra moneda.
400 `invalid_data` sobre `buyer`	Falta el comprador para Nequi/Daviplata, teléfono inválido, o un documento Daviplata distinto de CC, CE o TI	Corrige el campo que indica el error.
400 `invalid_otp`	Código Daviplata errado	Pide de nuevo el código al comprador mientras el pago esté pendiente.
503 `method_unavailable`	El canal o la tasa no están disponibles ahora	Ofrece otra moneda y reintenta más tarde.
`failed` con `expired` o `rejected`	El comprador no aprobó a tiempo, o lo rechazó	Inicia un pago nuevo.
COP no aparece en el checkout	Total bajo el mínimo, sin tasa reciente, una sesión dividida, o está apagado	Mira Activar o desactivar métodos.

Comisiones: Precios. Relacionado: Colombia (COP) · Receta: pesos colombianos · Convertir a USDT