Admin settlements

Configuration and the manual resolution tray for the Liquidación de Cisterneros (driver settlement) module. Paths are relative to the /api/v1 prefix; these are back-office endpoints requiring a super-admin token.

Requires a super-admin bearer token (see Admin auth). Super-admin only.

See Common errors.

Endpoints

The config object

{
  "cutoff_enabled": false,
  "cutoff_time": "02:00",
  "payout_enabled": false,
  "payout_time": "10:00",
  "min_balance_usd": 0.5,
  "min_balance_cents": 50,
  "active_days": [false, true, false, true, false, true, false],
  "iva_prc": 16,
  "timezone": "-04:00"
}

GET /admin/settlements/config

Response 200 — { "config": { … } } (see the config object).

PATCH /admin/settlements/config

Partial update; every field is optional. Only the sent fields change; unsent fields keep their stored value.

Request body

The payout_time > cutoff_time invariant compares the effective values: a field not sent uses its current stored value.

Response 200

{
  "config": { "…": "see the config object" },
  "audit_entry": {
    "key": "settlement_config",
    "old_values": { "cutoff_enabled": false },
    "new_values": { "cutoff_enabled": true },
    "created_at": "2026-07-29T19:16:35.000000Z"
  }
}

audit_entry records only the fields that changed (previous and new values). A no-op update (all values equal the stored config) returns "audit_entry": null and writes no audit row.

Errors

GET /admin/settlements/receipts

Page-based list of settlement receipts, any status, newest first.

Query params

Response 200

{
  "items": [
    {
      "id": 12,
      "receipt_number": "2026-0000042",
      "driver_id": 5,
      "driver_name": "Cisternero Test",
      "fiscal_period": "2026-07",
      "status": "PAID",
      "payout_method": "PAGO_MOVIL",
      "net_usd": 85.0,
      "payable_usd": 85.0,
      "total_paid_bs_cents": 340000,
      "bank_reference": "FAKE-REF-13",
      "failure_reason": null,
      "issued_at": "2026-07-31T10:00:00+00:00",
      "paid_at": "2026-07-31T14:05:00+00:00",
      "voided_at": null,
      "created_at": "2026-07-31T10:00:00+00:00"
    }
  ],
  "meta": { "total": 1, "per_page": 25, "current_page": 1, "last_page": 1 }
}

GET /admin/settlements/receipts/{id}

Full detail of one receipt: the breakdown totals (USD via _usd, Bs raw via _bs_cents), the frozen beneficiary/payout snapshot, its lines, its payout orders (each with its attempts), and its manual resolution-tray audit trail.

Response 200

{
  "receipt": {
    "id": 12,
    "receipt_number": "2026-0000042",
    "driver_id": 5,
    "city_id": 1,
    "fiscal_period": "2026-07",
    "status": "PAID",
    "failure_reason": null,
    "bank_reference": "FAKE-REF-13",
    "cutoff_from": null,
    "cutoff_to": "2026-07-31T10:00:00+00:00",
    "issued_at": "2026-07-31T10:00:00+00:00",
    "subtotal_usd": 100.0,
    "discount_usd": 0,
    "orders_total_usd": 100.0,
    "commission_usd": -15.0,
    "net_usd": 85.0,
    "payable_usd": 85.0,
    "net_bs_cents": 340000,
    "total_paid_bs_cents": 340000,
    "remuneration_base_usd": 15.0,
    "remuneration_usd": 15.0,
    "iva_prc": "16.00",
    "iva_usd": 2.4,
    "remuneration_total_usd": 17.4,
    "beneficiary_name": "Cisternero Test",
    "beneficiary_id_number": "12345678",
    "payout_method": "PAGO_MOVIL",
    "payout_account": "+584241234567",
    "beneficiary_bank_code": null,
    "beneficiary_account_type": null,
    "paid_at": "2026-07-31T14:05:00+00:00",
    "voided_at": null,
    "created_at": "2026-07-31T10:00:00+00:00",
    "lines": [
      {
        "id": 1, "line_number": 1, "type": "ORDER", "order_id": 40,
        "order_date": "2026-07-30", "description": "…",
        "subtotal_usd": 50.0, "discount_usd": 0, "order_total_usd": 50.0,
        "commission_usd": -7.5, "net_usd": 42.5,
        "exchange_rate_amount": "40.000", "total_bs_cents": 170000
      }
    ],
    "payout_orders": [
      {
        "id": 13, "idempotency_key": "settlement_payout:12", "method": "PAGO_MOVIL",
        "provider": "sypago", "amount_bs_cents": 340000, "status": "CONFIRMED",
        "reference": "FAKE-REF-13", "transaction_id": null, "attempt_count": 1,
        "last_error": null, "sent_at": "…", "confirmed_at": "…", "failed_at": null,
        "attempts": [
          { "attempt_no": 1, "provider_code": "OK", "result": "confirmed", "created_at": "…" }
        ]
      }
    ],
    "receipt_changes": [
      {
        "action": "retry", "admin_id": 3, "admin_name": "Ada Admin",
        "from_status": "FAILED", "to_status": "PAID", "reason": null, "created_at": "…"
      }
    ]
  }
}

lines[].type is ORDER for a delivered order or ADJUSTMENT for anything else in the window: manual wallet adjustments and promotion movements (PROMO_BONUS, PROMO_REIMBURSEMENT). ADJUSTMENT lines carry order_id: null and subtotal_usd, order_total_usd and commission_usd at 0, so they never enter the receipt's commission or IVA base.

Errors

Manual resolution tray

Receipts that dispersion (pago) or reconciliation left in FAILED land here for a super-admin to resolve. Each action is audited (status transition + reason + admin).

failure_kind classifies why a receipt is FAILED:

GET /admin/settlements/tray

Page-based list of FAILED receipts, newest first.

Query params

Response 200

{
  "items": [
    {
      "id": 12,
      "receipt_number": "2026-0000042",
      "driver_id": 5,
      "driver_name": "Cisternero Test",
      "payout_method": "PAGO_MOVIL",
      "net_usd": 85.0,
      "payable_usd": 85.0,
      "total_paid_bs_cents": 340000,
      "failure_reason": "Cuenta inválida",
      "failure_kind": "business",
      "provider_code": "RJCT",
      "attempts": 1,
      "failed_at": "2026-07-31T14:05:00+00:00",
      "created_at": "2026-07-31T10:00:00+00:00"
    }
  ],
  "meta": { "total": 1, "per_page": 25, "current_page": 1, "last_page": 1 }
}

Fields per item: id, receipt_number, driver_id, driver_name, payout_method (PAGO_MOVIL|BANK_TRANSFER|null), net_usd, payable_usd, total_paid_bs_cents (bolívares), failure_reason, failure_kind, provider_code (latest attempt, nullable), attempts (count on the latest order), failed_at (nullable), created_at.

POST /admin/settlements/receipts/{id}/retry

Re-disperse a FAILED receipt. Mints a new payout order (fresh idempotency key); the old order is never re-opened. No request body.

Response 200

{
  "receipt": { "id": 12, "receipt_number": "2026-0000042", "status": "PAID", "bank_reference": "FAKE-REF-13", "failure_reason": null, "paid_at": "…", "voided_at": null },
  "order": { "id": 13, "status": "CONFIRMED", "idempotency_key": "settlement_payout:12:r1" },
  "audit_entry": { "action": "retry", "from_status": "FAILED", "to_status": "PAID", "reason": null, "created_at": "…" }
}

receipt.status / order.status reflect the dispersion outcome: a synchronous confirm → PAID / CONFIRMED; an acknowledgement → IN_PAYMENT / SENT.

Errors

POST /admin/settlements/receipts/{id}/mark-external

Record that a FAILED receipt was paid to the driver outside Agüita. Settles the wallet and sets status = PAID_EXTERNALLY with the external reference in bank_reference.

Request body

Response 200 — { "receipt": { …, "status": "PAID_EXTERNALLY", "bank_reference": "MANUAL-REF-123" }, "audit_entry": { "action": "mark_external", … } }

Errors

POST /admin/settlements/receipts/{id}/annul

Annul a FAILED receipt: status = VOIDED and the reserved payout is released back to the driver's withdrawable balance (no money is sent).

Request body

Response 200 — { "receipt": { …, "status": "VOIDED", "voided_at": "…" }, "audit_entry": { "action": "annul", … } }

Errors