curl -X POST https://consola.mouvlatam.com/api/deposits/pse \
-H "Authorization: Bearer mvk_..." \
-H "Content-Type: application/json" \
-d '{
"amountCents": 100000,
"payerDocumentTypeId": 1,
"payerDocumentNumber": "1018485810",
"payerFirstName": "Juan",
"payerLastName": "Pérez",
"payerEmail": "juan@example.com",
"payerPhone": "3115551234",
"internalRef": "factura-001"
}'
const deposit = await fetch('https://consola.mouvlatam.com/api/deposits/pse', {
method: 'POST',
headers: {
'Authorization': `Bearer ${process.env.MOUV_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
amountCents: 100000,
payerDocumentTypeId: 1,
payerDocumentNumber: '1018485810',
payerFirstName: 'Juan',
payerLastName: 'Pérez',
payerEmail: 'juan@example.com',
internalRef: 'factura-001',
}),
}).then(r => r.json());
// Enviá el link al pagador (por email/SMS/dashboard tu sistema)
console.log(`Link de pago: ${deposit.paygatewayUrl}`);
{
"id": "dep_8e39f393-...",
"status": "PENDING_CONFIRM",
"amountCents": 100000,
"currency": "COP",
"paygatewayUrl": "https://pse.proveedor.com/pse?id=abc123",
"expiresAt": "2026-05-26T20:00:00.000Z",
"internalRef": "factura-001",
"createdAt": "2026-05-25T20:00:00.000Z"
}
{
"error": "FEE_EXCEEDS_AMOUNT",
"message": "El monto del depósito es menor que la comisión configurada.",
"details": {
"grossCents": 100000,
"totalFee": 1100,
"ivaAmount": 209,
"totalCharged": 101309
}
}
Recaudos PSE
POST /deposits/pse
Generar link PSE para recaudar a tu wallet
POST
/
api
/
deposits
/
pse
curl -X POST https://consola.mouvlatam.com/api/deposits/pse \
-H "Authorization: Bearer mvk_..." \
-H "Content-Type: application/json" \
-d '{
"amountCents": 100000,
"payerDocumentTypeId": 1,
"payerDocumentNumber": "1018485810",
"payerFirstName": "Juan",
"payerLastName": "Pérez",
"payerEmail": "juan@example.com",
"payerPhone": "3115551234",
"internalRef": "factura-001"
}'
const deposit = await fetch('https://consola.mouvlatam.com/api/deposits/pse', {
method: 'POST',
headers: {
'Authorization': `Bearer ${process.env.MOUV_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
amountCents: 100000,
payerDocumentTypeId: 1,
payerDocumentNumber: '1018485810',
payerFirstName: 'Juan',
payerLastName: 'Pérez',
payerEmail: 'juan@example.com',
internalRef: 'factura-001',
}),
}).then(r => r.json());
// Enviá el link al pagador (por email/SMS/dashboard tu sistema)
console.log(`Link de pago: ${deposit.paygatewayUrl}`);
{
"id": "dep_8e39f393-...",
"status": "PENDING_CONFIRM",
"amountCents": 100000,
"currency": "COP",
"paygatewayUrl": "https://pse.proveedor.com/pse?id=abc123",
"expiresAt": "2026-05-26T20:00:00.000Z",
"internalRef": "factura-001",
"createdAt": "2026-05-25T20:00:00.000Z"
}
{
"error": "FEE_EXCEEDS_AMOUNT",
"message": "El monto del depósito es menor que la comisión configurada.",
"details": {
"grossCents": 100000,
"totalFee": 1100,
"ivaAmount": 209,
"totalCharged": 101309
}
}
Genera un link PSE (pagosseguros.com.co) que un tercero usa para pagarte. Cuando el pagador completa el flujo, Mouv:
- Confirma con el proveedor PSE
- Acredita el monto neto (gross - fee - IVA) a tu wallet ACH
- El status del deposit pasa a
PAID
WRITE
Body
number
required
Monto que el pagador debe pagar (centavos). Mínimo 100.
number
required
1 = CC, 4 = CE, 5 = Pasaporte, 8 = NIT.string
required
5-15 dígitos.
string
required
Nombres del pagador.
string
required
Apellidos del pagador.
string
required
Email válido — se usa para enviar el link si llamás
/share-email.string
Opcional. Celular Colombia 10 dígitos.
string
Opcional. Tu identificador interno (ej.
factura-001). Aparece en el listado y receipt.Response 201
string
UUID del deposit (
dep_...)string
PENDING_CONFIRM al inicionumber
Lo que cotizaste
string
"COP"string
Compartilo con el pagador. El link expira en 24h.
string
ISO 8601 — cuándo expira el link si no se paga
string
Tu reference (si lo proveíste)
string
ISO 8601
Ejemplos
curl -X POST https://consola.mouvlatam.com/api/deposits/pse \
-H "Authorization: Bearer mvk_..." \
-H "Content-Type: application/json" \
-d '{
"amountCents": 100000,
"payerDocumentTypeId": 1,
"payerDocumentNumber": "1018485810",
"payerFirstName": "Juan",
"payerLastName": "Pérez",
"payerEmail": "juan@example.com",
"payerPhone": "3115551234",
"internalRef": "factura-001"
}'
const deposit = await fetch('https://consola.mouvlatam.com/api/deposits/pse', {
method: 'POST',
headers: {
'Authorization': `Bearer ${process.env.MOUV_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
amountCents: 100000,
payerDocumentTypeId: 1,
payerDocumentNumber: '1018485810',
payerFirstName: 'Juan',
payerLastName: 'Pérez',
payerEmail: 'juan@example.com',
internalRef: 'factura-001',
}),
}).then(r => r.json());
// Enviá el link al pagador (por email/SMS/dashboard tu sistema)
console.log(`Link de pago: ${deposit.paygatewayUrl}`);
{
"id": "dep_8e39f393-...",
"status": "PENDING_CONFIRM",
"amountCents": 100000,
"currency": "COP",
"paygatewayUrl": "https://pse.proveedor.com/pse?id=abc123",
"expiresAt": "2026-05-26T20:00:00.000Z",
"internalRef": "factura-001",
"createdAt": "2026-05-25T20:00:00.000Z"
}
{
"error": "FEE_EXCEEDS_AMOUNT",
"message": "El monto del depósito es menor que la comisión configurada.",
"details": {
"grossCents": 100000,
"totalFee": 1100,
"ivaAmount": 209,
"totalCharged": 101309
}
}
Lifecycle del deposit
| Status | Significado |
|---|---|
PENDING_CONFIRM | Link generado, esperando pago del pagador |
PAID | Pagador completó PSE, monto neto acreditado a tu wallet ACH |
FAILED | Pagador intentó pero falló (ej. fondos insuficientes en su banco) |
EXPIRED | 24h sin pagar — el link ya no es válido |
Webhooks (próximamente)
Cuando habilitemos webhooks salientes, recibirás un POST a tu URL configurada con eventodeposit.paid cuando el pago confirme — sin tener que pollear.
Tip — flujo recomendado
- Cliente cobra a un cliente final (factura emitida en tu sistema)
- Tu sistema llama
POST /deposits/psecon los datos del pagador + tuinternalRef - Mostrás el
paygatewayUrlal pagador (o llamás/share-emailpara enviarlo) - Pagador completa PSE en su banco
- Tu sistema pollea
GET /deposits?status=PAIDcada N min (o espera webhook) y matchea porinternalRef - Marca factura como pagada en tu sistema