> ## Documentation Index
> Fetch the complete documentation index at: https://docs.onepay.la/llms.txt
> Use this file to discover all available pages before exploring further.

# Programa de aliado

> Da de alta cada comercio final como una empresa propia de OnePay y opera su ingreso y sus cobros por el API.

Un **programa de aliado** le permite a una empresa, el **aliado**, dar de alta por el API cada comercio final como una empresa propia de OnePay y operarlo de punta a punta: el alta, los documentos, la revisión de cumplimiento, las llaves y los cobros. En esta documentación esas empresas se llaman **comercios del programa**.

> [!NOTE]
>
> El programa lo configura OnePay sobre la cuenta del aliado, junto con el módulo de alta de empresas: no se crea por el API. Mientras tu empresa no tenga un programa, [`POST /companies`](https://docs.onepay.la/client/companies/create) crea empresas sueltas y las rutas de esta sección responden `404` para cualquier empresa. Si responden `403 Company does not have this feature.`, al módulo de alta de empresas le falta activarse.

## Dos llaves

| Llave | Cómo se obtiene | Para qué sirve |
| - | - | - |
| **Llave del aliado** | Es la llave secreta de tu empresa (`sk_test_` o `sk_live_`), creada en el panel. | Dar de alta comercios, cargar sus documentos, enviarlos a revisión, consultar la revisión y emitir o revocar las llaves de cada comercio. |
| **Llave del comercio** | La emites con [Crear llave de un comercio](https://docs.onepay.la/client/companies/api-keys-create.md). | Cobrar a nombre del comercio: cobros, links de pago, consulta y reembolso de cargos, movimientos y webhooks. Nada más: mira [Alcance de la llave del comercio](#alcance-de-la-llave-del-comercio). |

Todo lo que creas por el API queda en el entorno de la llave con que lo creas. Con tu llave `sk_test_` el comercio existe solo en pruebas y sus llaves son de pruebas; con `sk_live_` el comercio es de producción y lo revisa cumplimiento.

## Flujo

**1. Da de alta el comercio**

[`POST /companies`](https://docs.onepay.la/client/companies/create) con tu llave de aliado, tu referencia del comercio en `external_id` y las URLs de sus documentos en `documents`. El comercio nace en `pending`.

**2. Corrige sus documentos si hace falta**

[`POST /companies/{company_id}/documents/{type}`](https://docs.onepay.la/client/companies/documents), una llamada por documento, para reemplazar uno, por ejemplo después de un pedido de cambios.

**3. Envíalo a revisión**

[`POST /companies/{company_id}/submit`](https://docs.onepay.la/client/companies/submit). El comercio pasa a `onboarding`.

**4. Espera el resultado**

Escucha `company.verified`, `company.rejected` y `company.changes_requested`, o consulta [`GET /companies/{company_id}/review`](https://docs.onepay.la/client/companies/review). `company.verified` llega cuando el comercio ya puede cobrar: cumplimiento lo aprobó y el procesador de tarjetas registró su comercio.

**5. Emite su llave**

[`POST /companies/{company_id}/api-keys`](https://docs.onepay.la/client/companies/api-keys-create). La llave de producción solo sale para un comercio activo.

**6. Cobra**

Con la llave del comercio, crea el cobro con [`POST /payments`](https://docs.onepay.la/client/payments/create) y envía al pagador al `payment_link`. El pago con tarjeta pasa siempre por 3DS en el checkout de OnePay.

## Qué cambia en un comercio del programa

* **Tarifas.** Cobra con las tarifas del aliado. Si el programa traslada el costo de las tarjetas, mira [Comisión](#comisión).
* **Contacto.** OnePay no contacta al comercio: no le envía contrato, ni facturas, ni solicitudes de datos de facturación.
* **Activación.** Pasa a `active` solo cuando termina el registro de su comercio propio para cobrar con tarjeta, con su MCC (`industry`). Si cumplimiento ya lo aprobó y ese registro sigue en curso, el comercio sigue en `onboarding`; el estado del alta lo ves en `processor`, en [la revisión](https://docs.onepay.la/client/companies/review.md).
* **Liquidación.** Sus cobros liquidan enteros en un saldo del programa. El saldo del comercio queda en cero. Mira [Destino del dinero](#destino-del-dinero).
* **Sin splits.** Un cobro con `splits` se rechaza con `partner_program_splits_not_allowed` (`10819`).
* **Sin recargos al pagador.** El pagador paga el monto del cobro: no se le suma ningún costo del medio de pago.
* **Tarjetas.** Solo Visa y Mastercard, siempre con 3DS. Mira [Tarjetas](#tarjetas).

## Alcance de la llave del comercio

La llave de un comercio del programa solo puede usar estas rutas:

| Recurso | Rutas |
| - | - |
| Cobros | `GET` y `POST /payments` · `GET` y `DELETE /payments/{payment_id}` · `GET /payments/{payment_id}/intents` · `GET /payments/{payment_id}/timeline` |
| Links de pago | `GET` y `POST /links` · `GET` y `DELETE /links/{link_id}` |
| Cargos | `GET /charges` · `GET /charges/{id}` · `POST /charges/{charge_id}/refund` |
| Movimientos | `GET /transactions` · `GET /transactions/{transaction_id}` |
| Webhooks | `GET` y `POST /webhooks` · `GET`, `PUT` y `DELETE /webhooks/{webhook_id}` |
| Catálogos | `GET /banks` · `GET /cities` · `GET /states` · `GET /fiscal-responsibilities` |

`HEAD` y `QUERY` cuentan como `GET`. Cualquier otra ruta responde `403` con `partner_program_route_not_allowed` (`10821`): por ejemplo crear empresas o llaves, crear cargos con `POST /charges`, actualizar o reenviar un cobro, dispersar o consultar saldos. Si la ruta lleva el id de un recurso que no existe, puede responder antes `404`. La llave del aliado no tiene esta restricción.

> [!NOTE]
>
> Como la llave del comercio no crea cargos directos, en un comercio del programa no hay cobros por API con una tarjeta guardada: el pagador paga en el `payment_link`.

## Destino del dinero

El cobro de un comercio del programa liquida entero en el saldo de un **destino del programa**: el aliado o una de las empresas que OnePay agregó como destino al configurar el programa. Un destino no puede ser, a su vez, un comercio de un programa.

* **Sin `target_wallet_id`**, el cobro liquida en el saldo principal del destino por defecto del programa, que es el aliado salvo que OnePay configure otro.
* **Con `target_wallet_id`**, tiene que ser un saldo de dinero en pesos (COP) de un destino del programa, del mismo entorno que el cobro. El saldo del propio comercio, el de otra empresa o el de otro programa responden igual que un saldo que no existe: `422` con «El balance destino no existe o no pertenece a la empresa.».
* En producción el destino tiene que estar activo. En pruebas basta con que exista.
* Si el destino no puede recibir el cobro, por ejemplo porque el destino por defecto no tiene saldo en pesos o, en producción, no está activo, el cobro no se crea: `422` con `partner_program_destination_unavailable` (`10818`).

El `id` de un saldo lo obtienes con [`GET /wallets`](https://docs.onepay.la/client/movimientos/wallets) usando la llave de la empresa destino; la llave del comercio no puede consultar saldos. El destino recibe un cobro en cualquier moneda: un cobro en USD se convierte a pesos al liquidar.

La comisión y las retenciones se descuentan en ese mismo saldo, y cada movimiento llega a los webhooks de la empresa dueña del saldo como `wallet.transaction.created`. Un reembolso también sale de ese saldo.

### Contracargos

Un contracargo se descuenta del saldo destino donde liquidó el cobro, no del saldo del comercio. Al abrirse la disputa salen dos débitos, el monto del cargo (convertido a pesos si el cobro fue en USD) y la tarifa del contracargo, y se aplican aunque el saldo quede en negativo.

* El cargo pasa a `disputed` y sale `charge.disputed` a los webhooks del comercio. El pago conserva su estado.
* Los dos débitos llegan a los webhooks de la empresa dueña del saldo como `wallet.transaction.created`, con el `id` del cargo en `transaction.node_id`.
* La evidencia se envía, o el contracargo se acepta, desde el panel de OnePay, en las disputas del comercio.
* La comisión y el costo de procesamiento del cobro no se devuelven, gane o pierda la disputa. Qué vuelve según el resultado está en [Gestión de contracargos](https://docs.onepay.la/docs/dispute/introduction.md). Donde esa guía habla de la cuenta del comercio, en un comercio del programa se trata del saldo destino: de ahí salen los débitos y ahí vuelve lo que se devuelve.

## Tarjetas

* El comercio cobra con tarjeta solo por el procesador de tarjetas de OnePay, con su comercio propio. Acepta **Visa y Mastercard**. Con otra marca (Amex, Diners) el checkout responde «Este comercio no recibe pagos con esta tarjeta. Usa una Visa o Mastercard, u otro medio de pago.».
* **Cada cobro con tarjeta pasa por 3DS**, sin excepción: la autenticación del banco sirve para un solo cobro, de ese comercio y por ese monto. El pagador la completa en el checkout de OnePay, en el `payment_link` del cobro.
* El 3DS funciona en cobros en COP y en USD. Si el cobro está en otra moneda, o el 3DS no está disponible, el checkout responde «El pago con tarjeta no está disponible para este comercio. Usa otro medio de pago.».
* Si un cargo llega al procesador sin su autenticación 3DS, falla con el motivo `THREE_DS_REQUIRED` (`10156`) y `retry: false`: el pagador tiene que pagar de nuevo y completar la verificación. Mira [Motivos de rechazo de cargos](https://docs.onepay.la/client/base/errors/codes.md).
* El tope por cobro con tarjeta es el que tenga el programa; si no tiene uno, aplica el general de USD 2.500. Un cargo que llega a ese tope falla con `MAX_AMOUNT`.

## Comisión

Un programa arranca cobrando las tarjetas con las **tarifas del aliado**. Con ellas, el bloque `commission` del pago es el de cualquier cobro (ver [Webhooks de pagos](https://docs.onepay.la/client/webhooks/payments#comisión)) y no trae `status`.

Si OnePay activa en el programa el **costo trasladado** para tarjetas:

* El cobro paga el costo real de procesarlo más la comisión de OnePay. El IVA (19 %) va solo sobre la comisión; el costo no lleva IVA.
* Mientras llega el costo real, se retiene una **reserva**: un porcentaje del monto, sin IVA.
* Cuando llega el costo real, se devuelve la reserva y se descuenta el costo. Si en 45 días no llega, la reserva queda como costo final.
* La comisión y la reserva quedan congeladas en el cobro: un cambio posterior del programa no toca los cobros ya hechos.

El bloque `commission` del pago lleva entonces `status`:

| `status` | Qué significa | Líneas de `details` |
| - | - | - |
| `provisional` | La reserva sigue retenida y el costo real no ha llegado. | `COMMISSION` (comisión con IVA) y `PAYIN_COST_RESERVE` (reserva) |
| `final` | Se cerró la reserva contra el costo real. En ese momento sale [`payment.commission_finalized`](https://docs.onepay.la/client/webhooks/payments#comisión-final). | `COMMISSION` y `PAYIN_COST_VARIABLE` (costo real) |

`commission.amount` suma solo la comisión de OnePay (las líneas `COMMISSION` o `COMMISSION_INTL`). `commission.accredited_amount` es el monto pagado menos todas las líneas de `details`, así que cambia al pasar de `provisional` a `final`.

> [!NOTE]
>
> Si el costo que llega no pasa los controles de OnePay (fuera del rango esperado, o el cobro ya fue reembolsado o disputado), la reserva sigue retenida y `status` sigue en `provisional` hasta que OnePay la cierre con el costo confirmado. Un reembolso no devuelve la comisión ni el costo.

## Webhooks

| Evento | Llega a | Cuándo |
| - | - | - |
| `company.verified` | Los webhooks del aliado | El comercio quedó activo y ya puede cobrar. |
| `company.rejected` | Los webhooks del aliado | Cumplimiento rechazó el ingreso. El motivo va en `company.status_reason`. |
| `company.changes_requested` | Los webhooks del aliado | Cumplimiento pidió cambios. Las notas van en `review.notes` y el comercio vuelve a `pending`. |
| `payment.*` y `charge.*`, incluido `payment.commission_finalized` | Los webhooks del comercio | Eventos de los cobros del comercio. Regístralos con [`POST /webhooks`](https://docs.onepay.la/client/webhooks/create) usando la llave del comercio. |
| `wallet.transaction.created` | Los webhooks de la empresa dueña del saldo destino | Cada movimiento del saldo: el abono, la comisión, la reserva y su cierre, y los débitos de un [contracargo](#contracargos). |

Los eventos `company.*` se entregan en los dos entornos: cada webhook del aliado los recibe según el entorno en que esté suscrito. El payload de cada uno está en [Webhooks de empresas](https://docs.onepay.la/client/webhooks/companies.md).

## Pruebas

* Un comercio creado con tu llave `sk_test_` existe **solo en pruebas**: no se envía a revisión, nunca pasa a producción y no recibe llave de producción (`partner_program_merchant_not_live`, `10822`).
* Su revisión se simula al crearlo, con `test_scenario`: `VERIFIED` entrega `company.verified` y `REJECTED` entrega `company.rejected` a tus webhooks de pruebas. El comercio sigue en `pending`.
* En pruebas el cobro con tarjeta no exige 3DS.
* Si el programa traslada el costo, en pruebas se simula con el 2,2 % del cobro apenas se acredita: ves el paso de `provisional` a `final` y recibes `payment.commission_finalized`.
* `external_id` es único por programa y por entorno: en producción puedes usar la misma referencia que usaste en pruebas.
* Los cargos de prueba no se reembolsan (`charge_is_test`, `10806`).

## Errores

| `code` | `code_name` | HTTP | Cuándo |
| - | - | - | - |
| `10816` | `partner_program_suspended` | 403 | El programa está suspendido: no se pueden crear comercios ni llaves. |
| `10818` | `partner_program_destination_unavailable` | 422 | El destino del cobro no puede recibirlo. |
| `10819` | `partner_program_splits_not_allowed` | 422 | El cobro de un comercio del programa trae `splits`. |
| `10821` | `partner_program_route_not_allowed` | 403 | La llave del comercio pidió una ruta fuera de su alcance. |
| `10822` | `partner_program_merchant_not_live` | 422 | Pediste la llave de producción de un comercio que todavía no opera en producción. |
| `10823` | `partner_program_merchant_environment` | 422 | Cambiaste el ingreso de un comercio con la llave del otro entorno. |

El detalle de cada uno, con qué hacer, está en [Errores comunes](https://docs.onepay.la/client/base/errors/common.md), [Empresas y métodos de pago](https://docs.onepay.la/client/base/errors/companies-payment-methods.md) y [Recaudo](https://docs.onepay.la/client/base/errors/collections.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.