Skip to main content
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.
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 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

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 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}, 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. 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. 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. La llave de producción solo sale para un comercio activo.
6

Cobra

Con la llave del comercio, crea el cobro con POST /payments 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.
  • 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.
  • Liquidación. Sus cobros liquidan enteros en un saldo del programa. El saldo del comercio queda en cero. Mira 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.

Alcance de la llave del comercio

La llave de un comercio del programa solo puede usar estas rutas: 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.
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 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. 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.
  • 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) 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: 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.
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

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.

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

El detalle de cada uno, con qué hacer, está en Errores comunes, Empresas y métodos de pago y Recaudo.