# Movimientos --- - [Movimientos](#movimientos) - [Qué es un movimiento](#overview) - [Listar movimientos](#lista) - [Consultar un movimiento](#consultar) - [Cómo se reparte el dinero](#anatomia) ## Qué es un movimiento [#overview] Cada transacción aprobada genera un **movimiento** en tu cuenta virtual: el registro de cuánto entró, qué se descontó por comisiones, fees, IVA y retenciones, cuánto queda liquidado y **desde cuándo puedes disponer de ese dinero**. Es lo que necesitas para conciliar: la transacción te dice qué cobraste, el movimiento te dice qué recibes. El ambiente (**Pruebas** o **Producción**) sale del token que uses (`api-access:test` o `api-access:production`); no se envía como parámetro. Ver [Autenticación](/authentication#ambientes). :::note Solo aparecen movimientos de transacciones liquidadas por Efipay como agregador. Si operas con tu propio código de comercio ante la red, el dinero no pasa por tu cuenta virtual y no verás movimientos. ::: ## Listar movimientos [#lista] **Descripción:** Devuelve los movimientos de tu cuenta virtual, paginados y ordenados del más reciente al más antiguo. `GET /api/v1/virtual-account/movements` | Nombre del campo | Descripción | Reglas | | - | - | - | | start_date | Inicio del rango, sobre la fecha de creación del movimiento | `['nullable', 'date_format:Y-m-d', 'before_or_equal:finish_date']` | | finish_date | Fin del rango. No puede ser futura | `['nullable', 'date_format:Y-m-d', 'before_or_equal:today', 'after_or_equal:start_date']` | | offices | Ids de las sucursales a consultar. Si lo omites, se consultan todas [tus sucursales](/commercio) | `['nullable', 'array']` | | offices.* | Cada id debe ser de una de tus sucursales | `['required', 'exists:offices,id']` | | availability | `all` todas, `available` solo el dinero ya disponible, `to_release` solo el que falta por liberar | `['nullable', 'in:all,available,to_release']` | | transaction_id | Filtra por el `transaction_id` exacto de la transacción asociada | `['nullable', 'string']` | | per_page | Movimientos por página. Por defecto `15` | `['nullable', 'integer', 'min:1', 'max:100']` | `GET /api/v1/virtual-account/movements` ```bash curl -X GET \ '/api/v1/virtual-account/movements?start_date=2026-08-01&finish_date=2026-08-31&availability=available&per_page=50' \ -H 'Authorization: Bearer ACCESS_TOKEN' \ -H 'Accept: application/json' ``` :::tip Respuesta satisfactoria ::: Código de respuesta: 200 ```json { "data": [ { "environment": "Producción", "concept": "Venta con tarjeta de crédito", "transaction_id": 20481, "authorization_number": "163427", "transaction_amount": 120000, "subtotal": 116154.4, "liquidated_amount": 115690.78, "commission": 3230.4, "fee": 0, "gravamen": 463.62, "iva": 0, "iva_commission": 613.78, "iva_fee": 0, "rete_iva": 0, "rete_ica": 0, "rete_fte": 0, "transaction_date": "2026-08-14T15:22:41.000000Z", "available_at": "2026-08-16T00:00:00.000000Z", "days_difference": "hace 2 semanas", "plan_detail_feature": { "commission": 2.69, "min_commission": 900, "fee": 0, "gravamen": 0.4 } } ], "links": { "first": "https://sag.efipay.co/api/v1/virtual-account/movements?page=1", "last": "https://sag.efipay.co/api/v1/virtual-account/movements?page=3", "prev": null, "next": "https://sag.efipay.co/api/v1/virtual-account/movements?page=2" }, "meta": { "current_page": 1, "from": 1, "last_page": 3, "per_page": 50, "to": 50, "total": 118 } } ``` :::danger Rango de fechas inválido ::: Código de respuesta: 422 ```json { "message": "El campo finish_date debe ser una fecha anterior o igual a hoy.", "errors": { "finish_date": [ "El campo finish_date debe ser una fecha anterior o igual a hoy." ] } } ``` ## Consultar un movimiento [#consultar] **Descripción:** Devuelve el movimiento de una transacción concreta, por su `transaction_id`. La respuesta es **el objeto plano**, sin el sobre `data` de los listados. `GET /api/v1/virtual-account/movements/{transaction_id}` | Nombre del campo | Descripción | Reglas | | - | - | - | | transaction_id | El `transaction_id` (consecutivo) de la transacción asociada, en la ruta | `['required', 'string']` | `GET /api/v1/virtual-account/movements/your-transaction-id` ```bash curl -X GET \ '/api/v1/virtual-account/movements/20481' \ -H 'Authorization: Bearer ACCESS_TOKEN' \ -H 'Accept: application/json' ``` :::tip Respuesta satisfactoria ::: Código de respuesta: 200 ```json { "environment": "Producción", "concept": "Venta con tarjeta de crédito", "transaction_id": 20481, "authorization_number": "163427", "transaction_amount": 120000, "subtotal": 116154.4, "liquidated_amount": 115690.78, "commission": 3230.4, "fee": 0, "gravamen": 463.62, "iva": 0, "iva_commission": 613.78, "iva_fee": 0, "rete_iva": 0, "rete_ica": 0, "rete_fte": 0, "transaction_date": "2026-08-14T15:22:41.000000Z", "available_at": "2026-08-16T00:00:00.000000Z", "days_difference": "hace 2 semanas", "plan_detail_feature": { "commission": 2.69, "min_commission": 900, "fee": 0, "gravamen": 0.4 } } ``` :::danger No existe, no es tuya, o es del otro ambiente ::: Código de respuesta: 404 :::caution Un `404` aquí casi siempre significa una de tres cosas: estás consultando con el token del otro ambiente, la transacción todavía no está aprobada, o no se liquidó por agregador. No significa que la transacción no exista. ::: ## Cómo se reparte el dinero [#anatomia] Todos los importes van en pesos colombianos. | Campo | Qué es | | - | - | | environment | `Producción` o `Pruebas` | | concept | Descripción del movimiento | | transaction_id | El consecutivo de la transacción asociada, o el id del ajuste | | authorization_number | Código de autorización de la red. Puede ser `null` | | transaction_amount | Lo que pagó tu cliente | | commission | Comisión de Efipay | | iva_commission | IVA sobre esa comisión | | fee | Fee fijo por transacción, si tu plan lo tiene | | iva_fee | IVA sobre el fee | | iva | IVA de la transacción misma | | subtotal | `transaction_amount` menos comisiones, fees e IVAs | | gravamen | 4×1000 sobre el subtotal | | liquidated_amount | **Lo que efectivamente recibes**: `subtotal` menos `gravamen` | | rete_iva, rete_ica, rete_fte | Retenciones, cuando aplican a tu comercio | | transaction_date | Fecha de compensación; si aún no compensa, la de creación | | available_at | Desde cuándo puedes disponer del dinero. `null` si aún no se define | | days_difference | Lectura humana de `available_at` (`"en 2 días"`, `"hace 2 semanas"`). `null` si no hay fecha | | plan_detail_feature | Las tasas de tu plan que se aplicaron. Puede ser `null` | **Campos de `plan_detail_feature`** | Campo | Qué es | | - | - | | commission | Porcentaje de comisión de tu plan | | min_commission | Comisión mínima por transacción | | fee | Fee fijo configurado | | gravamen | Porcentaje de gravamen configurado | :::note **Concilia con `liquidated_amount`.** `transaction_amount` es lo que pagó tu cliente, no lo que entra a tu cuenta. :::