Crear método de pago
POST /api/payment-method-types
Autenticación: Bearer del usuario del tenant (Authorization: Bearer <api_token>).
Registra un método de pago. El servidor asigna el código.
Quién puede usarlo: solo usuarios de tipo administrador (type = admin). Con el token de un vendedor responde 403.
Formato de respuesta: estándar {success, data, message?} (registro único). Responde 201 con el método creado (incluye su id).
Cuerpo (JSON):
| Campo | Tipo | Obligatorio | Descripción / valores permitidos |
|---|---|---|---|
description |
string (máx. 255) | Sí al crear | Nombre que ve el cajero (p. ej. Yape, Transferencia BBVA). |
is_credit |
boolean | No | true = condición de crédito (plazo de cobro, p. ej. A 45 días), no una forma de cobro. Por defecto false. |
number_days |
integer (0 a 3650) | No | Días de plazo de una condición de crédito. Por defecto 0. |
goes_to_cash_drawer |
boolean | No | true = el dinero entra y sale del cajón (efectivo) y se cuadra en el arqueo de la caja. Por defecto false. |
use_for_income |
boolean | No | Se ofrece para cobrar (ventas, cobranzas, ingresos). Por defecto true. |
use_for_expense |
boolean | No | Se ofrece para pagar (compras, gastos). Por defecto false. |
destination_rule |
string | No | any · type:bank · type:wallet · type:gateway · type:card · account:<id>. Por defecto any. Ver la tabla de reglas. |
is_active |
boolean | No | Activo (se ofrece en los formularios). Por defecto true. |
has_card |
boolean | No | Pide marca de tarjeta al registrar el pago. |
charge |
numeric (0 a 100) | No | Recargo porcentual informativo del método. |
Regla de destino (destination_rule) — un solo valor decide a dónde va (o de dónde sale) el dinero:
| Valor | Significado | Cómo queda el método |
|---|---|---|
any |
Se elige la cuenta al registrar cada cobro o pago. | default_destination_id = null, allowed_destination_type = null |
type:bank |
Solo cuentas bancarias. | allowed_destination_type = "bank" |
type:wallet |
Solo billeteras digitales (Yape, Plin...). | allowed_destination_type = "wallet" |
type:gateway |
Solo pasarelas de pago (Niubiz, Izipay...). Una pasarela recibe cobros pero no paga. | allowed_destination_type = "gateway" |
type:card |
Solo tarjetas de la empresa. Una tarjeta de la empresa paga pero no recibe cobros. | allowed_destination_type = "card" |
account:<id> |
Siempre esa cuenta (id de Cuentas bancarias, bank-accounts). Al registrar un pago con este método hay que enviar esa misma cuenta como payment_destination_id; otra se rechaza. |
default_destination_id = <id> |
Un método que va al cajón (goes_to_cash_drawer: true, el efectivo) no tiene cuenta: su regla siempre queda en any y sus cobros van a la caja abierta (payment_destination_id = "cash").
Reglas:
- El código (
id) lo asigna el servidor al crear: el primer libre desde11(los códigos01a10están reservados). No se envía ni cambia al editar; si se envía, se ignora. - Un método nuevo se coloca al final del orden (
sort_order). is_credit: true→ no es medio de pago (is_payment_medium: false): se fuerzagoes_to_cash_drawer,use_for_incomeyuse_for_expenseafalsey no aparece al registrar pagos.- Un medio de pago sin uso (ni cobrar ni pagar) queda inactivo aunque envíes
is_active: true(has_no_use: true). Márcale un uso para activarlo. goes_to_cash_drawer: true→ la regla de destino queda enany(el efectivo no tiene cuenta).- La cuenta (o el tipo) tiene que servir para todo lo marcado: si
use_for_incomey la cuenta no recibe cobros, ouse_for_expensey la cuenta no permite pagos, responde409y no guarda nada.
Errores:
403si el usuario no es administrador.422{success: false, message: {campo: [errores]}}si falla la validación de campos. (faltadescription,destination_rulecon formato inválido oaccount:<id>de una cuenta que no existe).409si la cuenta o el tipo elegido no sirve para lo marcado, o si ya no quedan códigos libres.401sin token o con un token inválido.
Cuerpo
Content-Type: application/json
{
"description": "Plin",
"goes_to_cash_drawer": false,
"use_for_income": true,
"use_for_expense": true,
"destination_rule": "account:5"
}
Respuestas
201 — Creado
{
"success": true,
"data": {
"id": "21",
"description": "Plin",
"sort_order": 140,
"is_active": true,
"is_credit": false,
"number_days": 0,
"has_card": false,
"charge": 0.0,
"is_payment_medium": true,
"goes_to_cash_drawer": false,
"use_for_income": true,
"use_for_expense": true,
"destination_rule": "account:5",
"default_destination_id": 5,
"allowed_destination_type": null,
"destination_label": "PLIN TIENDA CENTRO",
"uses_label": "Cobros y pagos",
"has_no_use": false,
"can_delete": true,
"logo_url": null,
"initials": "PL",
"monogram_color": "#155e75"
},
"message": "Método de pago registrado con éxito"
}
409 — La cuenta no sirve para lo marcado
{
"success": false,
"message": "\"NIUBIZ TIENDA\" no permite pagos. Desmarca \"Para pagar\" o elige otra cuenta."
}
422 — Regla de destino inválida
{
"success": false,
"message": {
"destination_rule": [
"destination_rule debe ser \"any\", \"type:bank\", \"type:wallet\", \"type:gateway\", \"type:card\" o \"account:<id de la cuenta>\"."
]
}
}
403 — Usuario no administrador
{
"success": false,
"message": "Solo un administrador puede gestionar este recurso."
}
Pruébalo
Prueba este endpoint con tu empresa y tu token: elige la URL en Servers, pega el token en Authorize y haz clic en Try it out.