Payment

Un pago (o intento de pago) sobre una Order. Puede ser electrónico (pasarela), declarado manualmente por el cliente (reporte), contra entrega o con saldo.

Tipo (type)

  • gateway — pago electrónico procesado por una pasarela (Stripe, PayPal, etc.).
  • form — pago manual: el cliente reporta una transferencia/depósito y un admin lo valida.
  • post-payment — se cobra al momento de la entrega (POS, efectivo).
  • balance — se debita del saldo del cliente.

Estado (options)

options es un bitmask; el nibble bajo (status_code) es el estado y el resto (agent_code) identifica la pasarela. status (string) es la etiqueta derivada. Valores de status_code: 1 pendiente, 2 esperando efecto, 3 preparado, 4 listo para cobrar, 5 requiere confirmación, 10 cancelado por el cliente, 11 rechazado por vencimiento, 12 rechazado y reembolsado, 13 rechazado inválido, 14 rechazado duplicado, 15 confirmado (aceptado). Cada is_status_* corresponde a uno de esos valores.

Agentes / pasarelas (is_agent_*): custom (reporte manual), paypal, stripe, instapago, zelle, post_payment, coupon, balance, bdv, payco, binance, bancamiga_ci, sypago_ci.

Transiciones manuales (endpoints PATCH payments/{id}/...): prepare, verify, accept, cancel, set-invalid, set-duplicated, set-refunded.

Montos

Todos con sufijo _e2 (entero = monto × 100). En la moneda de la Company: total_e2 = order_e2 + tax_e2 + tip_e2. order_e2 es la parte que va a la orden, tax_e2 los impuestos, tip_e2 la propina. payment_tax_e2 es la comisión adicional que cobra la pasarela (no reduce lo que recibe la orden). total_effective_e2 / total_paid_e2 son lo efectivamente cobrado. related_amount_e2 / related_money expresan el monto en la moneda del pago (la que eligió el cliente), no en la de la Company.

Datos de la pasarela

payload y metadata (oculto) son los datos crudos; data, gateway, gateway_payload y transaction son vistas derivadas para la respuesta.

Estructura de Datos

Atributo Tipo Descripción
id int
options int Bitmask de estado y agente (ver "Estado")
payload array\|null Datos crudos del pago / la transacción de la pasarela
total_e2 int Monto total del pago: order_e2 + tax_e2 + tip_e2 (× 100)
order_e2 int Parte del pago que se aplica a la orden (× 100)
tax_e2 int Impuestos incluidos en el pago (× 100)
tip_e2 int Propina incluida en el pago (× 100)
created_at datetime\|null
updated_at datetime\|null
order_id int {@link Order} pagada
provider_id int\|null Proveedor asociado (pagos a flota / repartidor)
client_id int\|null Cliente que paga
admin_id int\|null Administrador que registró o validó el pago
company_id int Company de la orden
metadata array Metadatos internos del pago (oculto)
branch_id int\|null Comercio de la orden
uid string\|null Identificador legible del pago
payment_tax_e2 int Comisión adicional que cobra la pasarela por este pago (× 100)
is_visible bool Si el pago se muestra en los listados del cliente
is_branch_gateway bool El pago usa la pasarela configurada a nivel de comercio
type string\|null gateway | form | post-payment | balance
action_performed_at string\|null Momento en que se ejecutó una acción manual sobre el pago
status_code int BitMask ({@link self::options} & 0xf)
agent_code int BitMask (({@link self::options} & 0xfff0) >> 4)
is_status_pending bool BitMask (({@link self::options} & 0xf) === 1)
is_status_waiting_for_taking_effect bool BitMask (({@link self::options} & 0xf) === 2)
is_status_prepared bool BitMask (({@link self::options} & 0xf) === 3)
is_status_ready_to_charge bool BitMask (({@link self::options} & 0xf) === 4)
is_status_requires_confirmation bool BitMask (({@link self::options} & 0xf) === 5)
is_status_canceled_by_client bool BitMask (({@link self::options} & 0xf) === 10)
is_status_refused_expired bool BitMask (({@link self::options} & 0xf) === 11)
is_status_refused_refunded bool BitMask (({@link self::options} & 0xf) === 12)
is_status_refused_invalid bool BitMask (({@link self::options} & 0xf) === 13)
is_status_refused_duplicated bool BitMask (({@link self::options} & 0xf) === 14)
is_status_confirmed bool BitMask (({@link self::options} & 0xf) === 15)
is_agent_custom bool BitMask (({@link self::options} & 0x10) !== 0)
is_agent_paypal bool BitMask (({@link self::options} & 0x20) !== 0)
is_agent_stripe bool BitMask (({@link self::options} & 0x40) !== 0)
is_agent_instapago bool BitMask (({@link self::options} & 0x80) !== 0)
is_agent_zelle bool BitMask (({@link self::options} & 0x100) !== 0)
is_agent_post_payment bool BitMask (({@link self::options} & 0x200) !== 0)
is_agent_coupon bool BitMask (({@link self::options} & 0x400) !== 0)
is_agent_balance bool BitMask (({@link self::options} & 0x800) !== 0)
is_agent_bdv bool BitMask (({@link self::options} & 0x1000) !== 0)
is_agent_payco bool BitMask (({@link self::options} & 0x2000) !== 0)
is_agent_binance bool BitMask (({@link self::options} & 0x4000) !== 0)
is_agent_bancamiga_ci bool BitMask (({@link self::options} & 0x8000) !== 0)
is_agent_sypago_ci bool BitMask (({@link self::options} & 0x10000) !== 0)
admin Admin\|null
agent int Código del agente/pasarela del pago
allLogs ApiLog>
branch Branch\|null
client Client\|null
company Company
data array Datos del pago listos para mostrar
gateway array\|null Datos de la pasarela para la respuesta
gateway_payload array\|null Payload de la pasarela para la respuesta
currency_snapshot Currency Moneda del pago congelada al momento de crearlo
method_name string\|null Nombre del método de pago usado
order_status string Estado de la orden asociada
portal string Portal / pasarela que procesa el pago
total_effective_e2 int Monto efectivamente cobrado (× 100)
transaction array Datos de la transacción para la respuesta
internal_payment_name string Nombre interno del pago
is_affecting_city_balance bool El pago afecta el balance de la ciudad
is_confirmation_bot_enabled bool Hay un bot de confirmación activo para este pago
logs ApiLog>
natural_payment_name string Nombre del pago para mostrar
order Order
payment_method_error string\|null Último error del método de pago
provider Provider\|null
related_amount float Monto del pago en la moneda del pago (no la de la Company)
related_amount_e2 int Monto del pago en la moneda del pago (× 100)
related_money Money Monto del pago en la moneda del pago
related_payment_name string Nombre del pago en la moneda del pago
resources UploadedResource> Comprobantes adjuntos al pago
status string Etiqueta de estado del pago, derivada de status_code
total_paid_e2 Money Monto total efectivamente pagado
warning_message string\|null Aviso a mostrar sobre el pago (si aplica) 
{
    "id": 488,
    "options": 31,
    "payload": [
        {
            "input": {
                "question": "Banco origen",
                "required": true,
                "hint": "Mercantil",
                "regex": "^.+^",
                "type": "bank",
                "answer": "Mercantil"
            }
        },
        {
            "input": {
                "question": "Número de operación",
                "required": true,
                "hint": "0000000",
                "regex": "^[0-9]+^",
                "type": "numeric",
                "answer": "13215"
            }
        },
        {
            "input": {
                "question": "Teléfono emisor del pago",
                "required": true,
                "hint": "+00 000 0000000",
                "regex": "^[0-9]+^",
                "type": "numeric",
                "answer": "584121198667"
            }
        },
        {
            "input": {
                "question": "Fecha de pago",
                "required": true,
                "hint": "00/00/0000",
                "regex": "^([0-2][0-9]|(3)[0-1])(\/)(((0)[0-9])|((1)[0-2]))(\/)\d{4}^",
                "type": "date",
                "answer": "04/05/2020"
            }
        },
        {
            "file": {
                "question": "Captura de pantalla",
                "required": false,
                "type": "file",
                "allowed_types.0": "image/jpeg",
                "allowed_types.1": "image/png",
                "allowed_types.2": "application/pdf",
                "answer": "http://127.0.0.1:8000/storage/companies/69/form/form_149_4_1588638445.png",
                "file_type": "image/png"
            }
        },
        {
            "input": {
                "question": "Descripción",
                "required": false,
                "hint": "Observación",
                "regex": "^.+^",
                "type": "text_area",
                "answer": "asd"
            }
        }
    ],
    "total_e2": 228000,
    "order_e2": 228000,
    "tax_e2": 0,
    "tip_e2": 0,
    "created_at": "2020-05-05 00:27:25",
    "updated_at": "2024-05-31 14:42:04",
    "order_id": 1547,
    "provider_id": null,
    "client_id": 43,
    "admin_id": 98,
    "company_id": 116,
    "branch_id": 41,
    "uid": "custom:488",
    "payment_tax_e2": 0,
    "is_visible": true,
    "is_branch_gateway": false,
    "type": "pago-movil",
    "action_performed_at": null,
    "status_code": 15,
    "agent_code": 1,
    "data": {
        "order": {
            "id": 1547,
            "number": 1,
            "uid": "011-0000001"
        },
        "client": {
            "id": 43,
            "name": "Pedro Parra",
            "display_name": "user_196",
            "email": "pedromiguelp18@gmail.com"
        },
        "transaction": {
            "currency": "USD",
            "sub_total": 228000,
            "tax": 0,
            "total": 228000
        }
    },
    "gateway": {
        "debug": null
    },
    "transaction": {
        "currency": "USD",
        "subtotal_e2": 228000,
        "subtotal": "2,280.00$",
        "order_tax_e2": 0,
        "order_tax": "0.00$",
        "tip_e2": 0,
        "tip": "0.00$",
        "payment_tax_e2": 0,
        "payment_tax": "0.00$",
        "total_e2": 228000,
        "total": "2,280.00$",
        "related_currency": "USD",
        "total_related": "2,280.00$"
    },
    "order_status": "successful",
    "portal": "custom",
    "method_name": "pago móvil",
    "related_payment_name": "Pago Móvil",
    "status": "successful",
    "warning_message": null
}

Endpoints

Insertar Payment

Insertar Payment de Order

Registra un pago

Al registrar un pago, el payload varía según el tipo de pago:

  • stripe:

    "payment_method_id": "nullable|string|max:255"

  • pos:

    {
"authorization": "required_with:message|string|max:16",
"batch": "required_with:message|string|max:16",
"date": "required_with:message|string",
"time": "required_with:message|string",
"dni": "required_with:message|string",
"merchant_id": "required_with:message|string",
"message": "required_without:error_code|string",
"pan": "required_with:message|string",
"receipt": "required_with:message|string",
"response_code": "required_with:message|string",
"stan": "required_with:message|string",
"terminal_id": "required_with:message|string",
"error_code": "nullable|string|min:2",
"error_message": "required_with:error_code|string|max:128",
"error_at": "required_with:error_code|date"
}

  • banco_de_venezuela:

    {
"email": "required|email:rfc,filter",
"phone": "required|string:min:8",
"dni": "required|integer",
"dni_letter": "required|string|in:V,E,P"
}

  • binance:

    {
"terminal_type": "string|in:IOS,ANDROID,WEB"
}

  • bancamiga_ci:

    {
"payout_index" => "required|integer|min:0",
"debug_amount" => "integer|min:1",
}

Sin parámetros adicionales:

  • paypal
  • instapago
  • zelle
  • payco
  • balance

La orden debe estar confirmada y no pagada. Si el método de pago está deshabilitado, removido o no soporta la moneda elegida, se responde con el detalle correspondiente (payment_method_disabled / payment_method_removed / payment_method_unavailable / payment_method_unsupported / currency_unavailable).

Método URI Cabeceras
POST /companies/{companyId}/orders/{orderId}/payments Authorization 
{
    "type": "required|string|max:32|in:paypal,instapago,zelle,payco,stripe,balance,pos,banco_de_venezuela,binance,bancamiga_ci,sypago_ci,post-payment",
    "order_e2": "required_without:currency_amount_e2|nullable|integer|min:0",
    "tax_e2": "integer",
    "tip_e2": "integer|min:0",
    "currency_amount_e2": "required_without:order_e2|nullable|integer|min:0",
    "currency_to_use": "required_with:currency_amount_e2|string|min:3|max:8",
    "payment_identifier": "integer|min:0"
}

Errores de negocio

Código HTTP Cuándo ocurre
EC105 400 La orden ya está pagada.
EA104 400 La moneda del pago no existe para la company.

Reportar pago manual

El cliente declara una transferencia o depósito hecho fuera de la plataforma. Crea un Payment de agente custom en estado pendiente, que luego un administrador acepta o rechaza (accept / set-invalid / set-duplicated). Se puede adjuntar un comprobante. payment_identifier evita reportes duplicados por reenvío.

Método URI Cabeceras
POST /companies/{companyId}/orders/{orderId}/payments/report Authorization 
{
    "type": "required|integer|min:2|max:20",
    "updated_at": "required|date",
    "values": [
        {
            "question_index": "required|integer|distinct",
            "answer": "required"
        }
    ],
    "order_e2": "required|integer|min:0",
    "tip_e2": "required|integer|min:0",
    "payment_identifier": "integer|min:0"
}

Listar Payment

{info} Soporta: Paginación Filters Carga dinámica

Listar pagos

Lista los Payment de la company (con filtros y paginación).

Método URI Cabeceras
GET /companies/{companyId}/payments Authorization

Listar pagos pendientes

{info} Soporta: Paginación Filters Carga dinámica

Lista los Payment de la company a la espera de validación o de una acción de un administrador.

Método URI Cabeceras
GET /companies/{companyId}/payments/pending Authorization

Listar Payment de Order

Listar pagos de una orden

Devuelve todos los Payment registrados sobre la orden.

Método URI Cabeceras
GET /companies/{companyId}/orders/{orderId}/payments Authorization

Listar Payment de Branch

{info} Soporta: Paginación Filters Carga dinámica

Listar pagos de un comercio

Lista los Payment de órdenes de la sucursal indicada.

Método URI Cabeceras
GET /companies/{companyId}/branches/{branchId}/payments Authorization

Mostrar Payment

{info} Soporta: Carga dinámica

Mostrar pago

Devuelve el Payment por su id, con estado, montos y datos de la pasarela.

Método URI Cabeceras
GET /companies/{companyId}/payments/{paymentId} Authorization

Actualizar Payment

Actualizar montos de un pago

Ajusta order_e2 / tax_e2 / tip_e2 de un Payment y recalcula total_e2. Solo si no se ejecutó ya una acción sobre el pago y es de agente custom o requiere confirmación.

Método URI Cabeceras
PATCH /companies/{companyId}/payments/{paymentId} Authorization 
{
    "order_e2": "required_without:currency_amount_e2|nullable|integer|min:0",
    "tax_e2": "integer",
    "tip_e2": "integer|min:0"
}

Acciones de Payment

Calcular comisión para un monto (deprecado)

{warning} Endpoint deprecado.

Dado un monto y un método de pago, devuelve la comisión de la pasarela y el total a cobrar.

Método URI Cabeceras
GET /companies/{companyId}/payments/calculate-debt Authorization

Cancelar pago

Marca un Payment manual como cancelado por el cliente. Solo para pagos que admiten acciones manuales y sobre los que aún no se ejecutó una acción.

Método URI Cabeceras
PATCH /companies/{companyId}/payments/{paymentId}/cancel Authorization

Errores de negocio

Código HTTP Cuándo ocurre
EC507 400 El pago no admite acciones manuales.
EC516 400 El pago tiene un bot de confirmación activo; hay que esperar unos minutos.
EC510 400 Ya se ejecutó una acción sobre este pago.

Aceptar pago

Valida y confirma un Payment manual (transferencia/depósito reportado por el cliente). Acepta un comment del administrador.

Método URI Cabeceras
PATCH /companies/{companyId}/payments/{paymentId}/accept Authorization 
{
    "comment": "string|max:255"
}

Errores de negocio

Código HTTP Cuándo ocurre
EC507 400 El pago no admite acciones manuales.
EC516 400 El pago tiene un bot de confirmación activo; hay que esperar unos minutos.

Marcar pago como inválido

Rechaza un Payment manual porque el comprobante no es válido.

Método URI Cabeceras
PATCH /companies/{companyId}/payments/{paymentId}/set-invalid Authorization

Errores de negocio

Código HTTP Cuándo ocurre
EC507 400 El pago no admite acciones manuales.
EC516 400 El pago tiene un bot de confirmación activo; hay que esperar unos minutos.

Marcar pago como duplicado

Rechaza un Payment manual porque corresponde a una transacción ya registrada.

Método URI Cabeceras
PATCH /companies/{companyId}/payments/{paymentId}/set-duplicated Authorization

Errores de negocio

Código HTTP Cuándo ocurre
EC507 400 El pago no admite acciones manuales.
EC516 400 El pago tiene un bot de confirmación activo; hay que esperar unos minutos.

Preparar pago

Inicializa un Payment pendiente contra la pasarela (crea la intención de pago y devuelve los datos para que el cliente complete el cobro). Requiere que la orden no esté pagada ni finalizada.

Método URI Cabeceras
PATCH /companies/{companyId}/payments/{paymentId}/prepare Authorization

Errores de negocio

Código HTTP Cuándo ocurre
EC105 400 La orden ya está pagada.
EC116 400 La orden ya está finalizada.

Verificar pago

Fuerza la reconsulta del estado del Payment contra la pasarela. Solo actúa si el pago está preparado, esperando efecto, requiere confirmación o listo para cobrar.

Método URI Cabeceras
PATCH /companies/{companyId}/payments/{paymentId}/verify Authorization

Marcar pago como reembolsado

Marca un Payment ya aceptado como reembolsado. Requiere el rol de gestión de facturas.

Método URI Cabeceras
PATCH /companies/{companyId}/payments/{paymentId}/set-refunded Authorization

Errores de negocio

Código HTTP Cuándo ocurre
EC509 400 El pago no está aceptado.

Pagos aceptados de una orden

Devuelve los Payment de la orden que están confirmados/aceptados.

Método URI Cabeceras
GET /companies/{companyId}/orders/{orderId}/payments-accepted Authorization

Calcular deuda de una orden

Devuelve cuánto falta pagar de la orden, opcionalmente para un método de pago y moneda dados (incluye la comisión de la pasarela).

Método URI Cabeceras
GET /companies/{companyId}/orders/{orderId}/calculate-debt Authorization

Relaciones