API de Vueltos (Pago Móvil C2P)
Emite pagos móviles inmediatos y entrega vueltos a tus clientes directamente desde tus cuentas bancarias empresariales.
Exclusivo para Cuentas Bancarias Jurídicas
Este endpoint funciona únicamente con cuentas bancarias jurídicas / empresariales (personas jurídicas con RIF J o G, como Banco de Venezuela Empresas, Mercantil Jurídico, Banco Plaza Jurídico, etc.) que tengan contratado y habilitado el servicio C2P (Comercio a Personas / Vuelto) en su institución bancaria.
No disponible para personas naturales: La normativa bancaria en Venezuela restringe la emisión de cobros/vueltos C2P exclusivamente a comercios y empresas. Las cuentas de personas naturales (RIF V o E) no pueden emitir pagos por esta vía.
💡 Puedes verificar si tu cuenta tiene C2P activo revisando tus cuentas en el panel o verificando que el arreglo verifications_types_available incluya { id: "C2P" } al consultar GET /me/usersbank.
El dinero sale de tu cuenta jurídica y llega al teléfono del cliente en tiempo real vía red Pago Móvil.
Permite enviar cambio a clientes de cualquier banco nacional (0102, 0108, 0134, 0105, etc.).
Soporta números de factura propios o correlativos seguros autogenerados por Pabilo.
Enviar Vuelto / Pago Móvil
Procesa una orden de vuelto debitando el monto de tu cuenta bancaria y acreditándolo instantáneamente al pagador.
https://api.pabilo.app/v1/transactionchange/userbank/{userBankId}Autenticación Requerida
Authorization: Bearer TU_API_KEY.Parámetros de la URL
| Parámetro | Tipo | Requerido | Descripción |
|---|---|---|---|
| userBankId | string | Sí | ID de la cuenta bancaria jurídica en Pabilo (ej. 68bf4460342eb73ad4ccfe72). Debe ser una cuenta de empresa con soporte C2P. |
Cuerpo de la Petición (JSON)
| Campo | Tipo | Requerido | Descripción |
|---|---|---|---|
| dni | object | Sí | Objeto que contiene el documento de identidad del destinatario/cliente. |
| dni.code | string | Sí | Tipo de documento del cliente: "V" (Venezolano), "E" (Extranjero), "J" (Jurídico), "G" (Gubernamental) o "P" (Pasaporte). |
| dni.number | string | Sí | Número de documento o cédula sin puntos ni letras (ej. "29660549"). |
| phone_pagador | string | Sí | Número de teléfono del cliente afiliado a Pago Móvil (ej. "04248343530" o "04141234567"). Debe incluir el código de operadora local. |
| amount | number | Sí | Monto a transferir en Bolívares (VES / Bs). Debe ser un número mayor a 0 (ej. 1 o 150.50). |
| invoice_number | string | Sí | Número de factura o correlativo de control asignado a la transacción (ej. "1036"). Requerido por el banco para conciliación. Puedes usar tu propio correlativo o solicitar uno atómico con el endpoint de factura precalculada. |
| destination_bank_code | string | Sí | Código bancario oficial de 4 dígitos del banco donde el cliente tiene su pago móvil (ej. "0102" Banco de Venezuela, "0105" Mercantil, "0108" Provincial, "0134" Banesco). |
Ejemplos de Integración
cURL
curl -X POST https://api.pabilo.app/v1/transactionchange/userbank/68bf4460342eb73ad4ccfe72 \
-H "Authorization: Bearer TU_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"dni": {
"code": "V",
"number": "29660549"
},
"phone_pagador": "04248343530",
"amount": 1,
"invoice_number": "1036",
"destination_bank_code": "0102"
}'JavaScript (Fetch)
const darVuelto = async () => {
const userBankId = "68bf4460342eb73ad4ccfe72"; // ID de tu cuenta jurídica
const response = await fetch(`https://api.pabilo.app/v1/transactionchange/userbank/${userBankId}`, {
method: "POST",
headers: {
"Authorization": "Bearer TU_API_KEY",
"Content-Type": "application/json"
},
body: JSON.stringify({
dni: {
code: "V",
number: "29660549"
},
phone_pagador: "04248343530",
amount: 1,
invoice_number: "1036",
destination_bank_code: "0102"
})
});
const result = await response.json();
if (!response.ok) {
console.error("Error al dar vuelto:", result.message);
return;
}
console.log("Vuelto exitoso:", result);
};Respuestas de la API
Respuesta Exitosa (200 OK)
El banco emisor procesa el pago y retorna el número de referencia y el código de autorización oficial.
{
"message": "Transaction change created successfully",
"data": {
"transaction_changes": {
"reference": "123456789012",
"authorization_code": "AUTH987",
"status": "APPROVED"
}
}
}Respuesta de Error
Si la cuenta no es jurídica, no tiene C2P contratado o hay saldo insuficiente:
{
"message": "La cuenta bancaria no soporta C2P o no es una cuenta jurídica habilitada"
}Gestión de Facturas y Consultas
Endpoints auxiliares para coordinar el correlativo de facturación y auditar transacciones pasadas.
Obtener Siguiente Número de Factura Atómico
Si tu sistema o punto de venta no gestiona un correlativo propio, puedes solicitar a Pabilo el siguiente número correlativo seguro para la cuenta:
https://api.pabilo.app/userbankpayment/{userBankId}/get-next-invoice-numbercurl -X GET https://api.pabilo.app/userbankpayment/68bf4460342eb73ad4ccfe72/get-next-invoice-number \
-H "Authorization: Bearer TU_API_KEY"Respuesta:
{
"data": {
"invoice_number": "1036"
}
}Consultar Estado de un Vuelto por ID
Obtén la información completa y comprobante de un vuelto registrado previamente en el sistema:
https://api.pabilo.app/v1/transactionchange/{transactionChangeId}curl -X GET https://api.pabilo.app/v1/transactionchange/68bf4460342eb73ad4ccfe99 \
-H "Authorization: Bearer TU_API_KEY"