Medios de pago del sitio
La colección sites[].paymentMethods no define un medio de pago: lo habilita.
Un elemento de esta colección no crea nada nuevo. Toma un medio de pago que el comercio ya tiene y lo habilita en ese sitio, permitiendo además sobrescribir los valores que deban diferir.
Esa es la diferencia esencial con Medios de pago, y de ella se derivan casi todas sus reglas.
Las tres formas de direccionar un elemento
Cada elemento indica de qué fila habla de una sola de estas tres maneras. Enviar más de una responde 422.
siteId responde 422 siempre: el sitio es el elemento que contiene la colección, no un campo suyo.
Los dos identificadores los publica el resultado de un proceso: paymentMethodId sale de result.paymentMethods[].id y el id de la habilitación, de result.sites[].paymentMethods[].id. Consérvalos, porque no hay forma de consultarlos después.
id — modificar una habilitación existente
Es la única dirección que alcanza a un sitio que tiene dos habilitaciones del mismo medio de pago, una situación que el registro permite y que existe en configuraciones antiguas. Está acotado al sitio que lo lleva.
{
"sites": [
{
"id": 16,
"paymentMethods": [
{ "id": 18, "minAmount": 2000.00, "maxAmount": 900000.00 }
]
}
]
}
paymentMethodId — habilitar uno que el comercio ya tiene
Señala el medio de pago del comercio, y está acotado al comercio de la URL. Es el identificador que publica result.paymentMethods[].id.
{
"sites": [
{
"id": 16,
"paymentMethods": [
{
"paymentMethodId": 64,
"financialEntity": 2,
"accountNumber": "1234567890"
}
]
}
]
}
code — habilitar uno que llega en la misma petición
Señala un medio de pago que la colección paymentMethods de la raíz de este mismo cuerpo le está dando al comercio. Nunca consulta lo que ya está registrado, y por eso es la única dirección posible al crear un comercio: en ese momento todavía no existe nada.
Permite registrar un medio de pago y habilitarlo en un sitio con una sola petición:
{
"paymentMethods": [
{ "code": "TS_VS", "financialEntity": 1, "commissionModel": "P", "commissionValue": 2.5 }
],
"sites": [
{
"id": 16,
"paymentMethods": [
{ "code": "TS_VS", "financialEntity": 1 }
]
}
]
}
Un code que la raíz del cuerpo no declara —o que declara dos veces— responde 422.
financialEntity es el banco del sitio
Dentro de un sitio, financialEntity no forma parte de la dirección: es la entidad financiera de la cuenta de depósito propia del sitio, la que usa en lugar de la del comercio.
Si un sitio deposita en el mismo banco que el comercio, no envíes financialEntity en absoluto: se hereda.
Qué se hereda y qué se sobrescribe
Lo que un elemento no nombra no se borra: se hereda del medio de pago del comercio.
Esta herencia es la razón por la que un elemento mínimo funciona: habilitar un medio de pago sin cambiar nada es enviar solo su dirección.
Montos por sitio
minAmount y maxAmount acotan este medio de pago dentro de este sitio. Si no los envías, se aplican los límites generales del bloque control del sitio.
Nombrar uno con un valor obliga a enviar el otro, en las dos direcciones. Es lo que impide dejar un mínimo por encima de un máximo.
Un null es un caso distinto: no nombra nada, así que no exige nada. Eso permite limpiar solo una de las dos mitades — por ejemplo, enviar minAmount: null con un maxAmount concreto significa «hereda el mínimo del control del sitio y conserva este máximo».
commissionModel y commissionValue funcionan igual: hay que enviarlos juntos cuando llevan valor.
La comisión por sitio
La comisión de un medio de pago de sitio se guarda pero no se cobra. El motor transaccional lee la comisión del comercio, no la del sitio. Configurarla aquí no cambia lo que cuesta una transacción.
Se acepta y se almacena porque es el comportamiento existente de la plataforma y hay herramientas administrativas que la leen. Pero si tu objetivo es cambiar la comisión efectiva, el campo que importa es el del medio de pago del comercio.
Hay un segundo efecto que conviene conocer: una comisión heredada —es decir, que no enviaste— se muestra como la del comercio, pero la primera vez que alguien guarde esa fila desde el back office pasará a valer 0.00 de forma permanente.
El bloque settings
Los ajustes se fusionan, igual que en los medios de pago del comercio:
Esto es lo contrario de lo que hacen las integraciones del sitio, donde el bloque se reemplaza entero. Dos colecciones hermanas dentro del mismo sitio con semánticas opuestas: es la fuente más común de configuraciones que desaparecen sin explicación aparente.
En el momento de una transacción, un ajuste del sitio prevalece sobre el mismo ajuste del comercio, que a su vez prevalece sobre el valor por defecto del catálogo.
Comportamiento en una actualización
La colección es upsert-only: un medio de pago que el cuerpo no nombra sigue habilitado en el sitio, y no existe forma de deshabilitarlo desde este contrato.
Dentro de un elemento nombrado, solo cambia lo que envías.
Escribir aquí marca el sitio
A diferencia de las integraciones del sitio, escribir un medio de pago marca el sitio como modificado. Verás ese sitio con action: "updated" en el resultado aunque no hayas cambiado ninguno de sus propios campos.
La marca se escribe solo cuando algo cambió realmente, y nunca en un sitio que esta misma petición acaba de crear.
Errores de direccionamiento
Los dos primeros se reportan sobre el elemento (sites.0.paymentMethods.0), no sobre un campo suyo, porque el problema es cómo está direccionado el elemento entero.
Las tres direcciones son tres espacios distintos: el 41 como habilitación de un sitio y el 41 como medio de pago del comercio nunca se confunden.
El resultado
Un sitio que escribió medios de pago incluye la clave paymentMethods en su entrada de result.sites[].
- Name
code- Type
- string
- is Required
- REQUERIDO
- Description
El código del medio de pago, leído del registro.
- Name
financialEntity- Type
- integer
- is Required
- REQUERIDO
- Description
La entidad financiera efectiva: la propia del sitio, o la del comercio cuando el sitio no tiene una.
- Name
id- Type
- integer
- is Required
- REQUERIDO
- Description
Identificador de la habilitación en este sitio. Es el que usarás para modificarla después.
- Name
action- Type
- string
- is Required
- REQUERIDO
- Description
created,updatedounchanged.
Nunca incluye settings.
result
{
"result": {
"merchantId": 18,
"sites": [
{
"id": 214,
"login": "aabbccdd1234567890aabbccdd123456",
"tranKey": null,
"active": true,
"action": "updated",
"paymentMethods": [
{
"code": "TS_VS",
"financialEntity": 2,
"id": 133,
"action": "created"
}
]
}
]
}
}
Fíjate en que el sitio aparece como updated aunque el cuerpo no cambiara ninguno de sus campos: es el efecto descrito arriba.