PaymentMethod

Configura una pasarela de pago (gateway) para una Company o, opcionalmente, para una Branch concreta. name es el nombre del gateway (stripe, paypal, …) y config guarda las claves para inicializar su SDK. Normalmente hace falta el SDK del proveedor para implementar el cobro.

Nivel y recaudación

Sin branch_id: el método es de la company y recauda la plataforma.
Con branch_id: es un método propio del comercio y recauda el comercio directamente (habitual en marketplaces, donde cada comercio define los suyos).
El modo efectivo (solo company, solo branch o ambos) lo decide el ajuste PAYMENTS_MODE de la sucursal.

Configuración (`config`)

Objeto con las claves específicas del gateway (solo se conservan las que el gateway declara como editables) más whitelist / blacklist de clientes. Vistas derivadas:

visible_config — solo las claves públicas del gateway.
internal_config — config sin whitelist ni blacklist.
whitelist / blacklist — listas de clientes tomadas de config.

Recargo (`tax_percent` + `tax_flat_e2` + `currency_iso`)

Recargo adicional que se cobra al cliente por usar el método: tax_percent es un porcentaje y tax_flat_e2 un monto fijo en céntimos (× 100). currency_iso es solo la moneda en la que se muestra ese impuesto; el cobro real se convierte a la moneda de la orden. El endpoint get-tax calcula el recargo para un monto dado.

Notas y gotchas

name se guarda internamente con prefijo <branch_id>: para el índice único, pero el accesor lo devuelve sin prefijo.
company_id está en $hidden.

Estructura de Datos

Atributo	Tipo	Descripción
`id`	`int`
`name`	`string`	Nombre del gateway a usar (`stripe`, `paypal`, …)
`config`	`array`	Claves de inicialización del SDK del gateway + whitelist/blacklist (ver "Configuración")
`enabled`	`bool`	Si el método está activo para cobrar
`tax_percent`	`float`	Recargo porcentual por usar el método
`tax_flat_e2`	`int`	Recargo fijo por usar el método, en céntimos (× 100)
`created_at`	`datetime\\|null`
`updated_at`	`datetime\\|null`
`company_id`	`int`	{@link Company} dueña del método (oculto)
`currency_iso`	`string`	Moneda en la que se muestra el recargo del método
`branch_id`	`int\\|null`	{@link Branch} propietaria del método; si es nulo, es de la company y recauda la plataforma
`allLogs`	`ApiLog>`
`blacklist`	`array`	Clientes bloqueados para este método (de `config`)
`currency`	`Currency\\|null`	{@link \App\Currency} correspondiente a `currency_iso`
`currency_tax`	`CurrencyTax`	Impuesto del método resuelto sobre su moneda
`tax`	`Tax`	Datos del recargo del método (`iso`, `tax_percent`, `tax_flat_e2`)
`internal_config`	`array`	`config` sin `whitelist` ni `blacklist`
`logs`	`ApiLog>`
`visible_config`	`array`	Subconjunto de `config` con solo las claves públicas del gateway
`whitelist`	`array`	Clientes permitidos para este método (de `config`)

{
    "id": 19,
    "name": "stripe",
    "config": {
        "public_key": "pk_test_FdMRjWhvmpDlQATdzn1IgwTl",
        "secret_key": "sk_test_qOc9zLm2kowVdEpQEpQtrZk3",
        "whitelist": [],
        "blacklist": []
    },
    "enabled": true,
    "tax_percent": 0.03,
    "tax_flat_e2": 30,
    "created_at": "2020-05-05 01:48:43",
    "updated_at": "2025-01-16 19:50:42",
    "currency_iso": "USD",
    "branch_id": null
}

Endpoints

Insertar PaymentMethod

Configurar método de pago

Crea un PaymentMethod a nivel de la Company —recauda la plataforma— a partir de una pasarela del catálogo. config lleva las claves del SDK del gateway; si no se envía currency_iso se usa la moneda internacional de la company.

{warning} Responde 404 si la pasarela (name) no está en el catálogo, y 503 si el servicio de pagos no está disponible.

Método	URI	Cabeceras
POST	`/companies/{company}/payment-methods`	Authorization

{
    "name": "required|string|in:paypal,instapago,zelle,payco,stripe,balance,pos,banco_de_venezuela,binance,bancamiga_ci,sypago_ci,post-payment",
    "enabled": "required|boolean",
    "config": "required",
    "tax_percent": "numeric|between:0.0000,1.0000",
    "tax_flat_e2": "integer|min:0",
    "currency_iso": "required_with:tax_flat_e2|string|min:3|max:8"
}

Listar PaymentMethod

Listar métodos de pago de la compañía

Devuelve los PaymentMethod configurados a nivel de la Company — los que recauda la plataforma. Aplica cuando la company es marketplace (setting_is_marketplace = true).

{info} Responde 503 si el servicio de pagos no está disponible.

Método	URI	Cabeceras
GET	`/companies/{company}/payment-methods`	N/A

Actualizar PaymentMethod

Actualizar método de pago

Modifica los campos enviados del PaymentMethod: enabled, config, tax_percent, tax_flat_e2 y currency_iso.

Método	URI	Cabeceras
PATCH	`/companies/{company}/payment-methods/{payment_method}`	Authorization

{
    "name": "string|max:32|in:paypal,instapago,zelle,payco,stripe,balance,pos,banco_de_venezuela,binance,bancamiga_ci,sypago_ci,post-payment",
    "enabled": "boolean",
    "config": "required",
    "tax_percent": "numeric|between:0.0000,1.0000",
    "tax_flat_e2": "integer|min:0",
    "currency_iso": "required_with:tax_flat_e2|string|min:3|max:8"
}

Eliminar PaymentMethod

Eliminar método de pago

Borra la configuración del PaymentMethod indicado.

Método	URI	Cabeceras
DELETE	`/companies/{company}/payment-methods/{payment_method}`	Authorization

Acciones de PaymentMethod

Listar métodos de pago del comercio

Devuelve los PaymentMethod que aplican a la Branch: sus métodos propios —que recauda el comercio directamente— y, según el modo de pagos de la sucursal (PAYMENTS_MODE), también los de la company. Aplica cuando la company no es marketplace (setting_is_marketplace = false).

{info} Responde 503 si el servicio de pagos no está disponible.

Método	URI	Cabeceras
GET	`/companies/{company}/branches/{branchId}/payment-methods`	Authorization

Calcular recargo del método de pago

Para el PaymentMethod identificado por name (opcionalmente el de una sucursal, vía branch_id), calcula el recargo por usar el método y el total a cobrar para un monto dado (order_e2, tax_e2, currency_to_use).

Método	URI	Cabeceras
GET	`/companies/{company}/payment-methods/{name}/get-tax`	Authorization

{
    "order_e2": "required|integer|min:0",
    "tip_e2": "required|integer|min:0",
    "currency_to_use": "string|min:3|max:8",
    "branch_id": "nullable|integer"
}

Obtener el user id del cliente en la pasarela

Registra y vincula el identificador del cliente en la pasarela del PaymentMethod (por ejemplo, el Customer de Stripe) y lo devuelve. A partir de ahí se puede acceder al wallet de tarjetas del cliente en esa pasarela. Un admin debe indicar client_id; un cliente opera sobre sí mismo.

Método	URI	Cabeceras
GET	`/companies/{company}/payment-methods/{payment_method}/get-user`	Authorization

Listar tarjetas del cliente

Devuelve las tarjetas guardadas del cliente en el wallet de la pasarela del PaymentMethod, junto con su identificador de cliente en la pasarela. Un admin debe indicar client_id; un cliente opera sobre sí mismo.

Método	URI	Cabeceras
GET	`/companies/{company}/payment-methods/{payment_method}/cards`	Authorization

Guardar tarjeta del cliente

Registra una tarjeta (source) en el wallet del cliente en la pasarela del PaymentMethod. La operación está limitada por frecuencia (rate limit) por cuenta.

Método	URI	Cabeceras
POST	`/companies/{company}/payment-methods/{payment_method}/cards`	Authorization

{
    "source": "required|string"
}

Eliminar tarjeta del cliente

Quita la tarjeta card_id del wallet del cliente en la pasarela del PaymentMethod.

Método	URI	Cabeceras
DELETE	`/companies/{company}/payment-methods/{payment_method}/cards`	Authorization

{
    "card_id": "required|string"
}

Seleccionar tarjeta del cliente

Marca la tarjeta card_id como predeterminada del cliente para ese PaymentMethod y devuelve el listado actualizado.

Método	URI	Cabeceras
POST	`/companies/{company}/payment-methods/{payment_method}/select-card`	Authorization

{
    "card_id": "required|string"
}

Catálogo de pasarelas configurables

Devuelve las pasarelas de pago que la Company puede configurar, con su estado actual (configurada / habilitada). Es la lista que alimenta la pantalla de configuración de métodos de pago.

{info} Responde 503 si el servicio de pagos no está disponible.

Método	URI	Cabeceras
GET	`/companies/{company}/payment-methods/set-up`	Authorization

Catálogo de pasarelas configurables del comercio

Igual que el catálogo de la company, acotado a la Branch indicada.

{info} Responde 503 si el servicio de pagos no está disponible.

Método	URI	Cabeceras
GET	`/companies/{company}/branches/{branchId}/payment-methods/set-up`	Authorization

Configurar método de pago del comercio

Igual que configurar un método de pago, pero asociado a la Branch (branch_id): el comercio recauda directamente. Requiere acceso a la sucursal.

{warning} Responde 404 si la pasarela (name) no está en el catálogo, y 503 si el servicio de pagos no está disponible.

Método	URI	Cabeceras
POST	`/companies/{company}/branches/{branchId}/payment-methods`	Authorization

{
    "name": "required|string|in:paypal,instapago,zelle,payco,stripe,balance,pos,banco_de_venezuela,binance,bancamiga_ci,sypago_ci,post-payment",
    "enabled": "required|boolean",
    "config": "required",
    "tax_percent": "numeric|between:0.0000,1.0000",
    "tax_flat_e2": "integer|min:0",
    "currency_iso": "required_with:tax_flat_e2|string|min:3|max:8"
}

Relaciones

allLogs HasMany ApiLog
currency HasOne Currency
logs HasMany ApiLog

Administración

Métodos de Pago

Calificaciones

PaymentMethod

Nivel y recaudación

Configuración (config)

Recargo (tax_percent + tax_flat_e2 + currency_iso)

Notas y gotchas

Estructura de Datos

Endpoints

Insertar PaymentMethod

Listar PaymentMethod

Actualizar PaymentMethod

Eliminar PaymentMethod

Acciones de PaymentMethod

Listar métodos de pago del comercio

Calcular recargo del método de pago

Obtener el user id del cliente en la pasarela

Listar tarjetas del cliente

Guardar tarjeta del cliente

Eliminar tarjeta del cliente

Seleccionar tarjeta del cliente

Catálogo de pasarelas configurables

Catálogo de pasarelas configurables del comercio

Configurar método de pago del comercio

Relaciones

Configuración (`config`)

Recargo (`tax_percent` + `tax_flat_e2` + `currency_iso`)