Las piezas y cómo encajan
Para recibir pagos con la API Productos manejas dos piezas, y una tercera solo si repartes: el destino (en la API, el acuerdo), la sesión de pago, y el partner.
Si vienes a entender cómo funciona un pago de principio a fin, léelo en orden en → Conceptos base. Aquí están las piezas sueltas, con sus formas y sus campos, para volver a consultarlas.
El destino: dónde declaras cómo recibes
Un destino —agreement en la API— es un juego de reglas que dice cómo recibes el dinero: a qué cuenta bancaria tuya se acredita, qué métodos de pago aceptas, y si lo que llegue ahí se reparte con otros.
Se define una vez y se reutiliza. No creas uno por pago: creas uno por cada forma distinta de recibir que tenga tu negocio.
{
"title": "Acuerdo sin Split",
"description": "Sin distribución de fondos",
"split": false,
"payment_methods": { "immediate_debit": true, "crypto": false, "mobile_payment": true },
"default_bank_account_id": "uuid_sofitasa_001",
"rules": [{ "origin_bank_code": "0105", "destination_bank_account_id": "uuid_mercantil_007" }]
}
| Campo | Qué dice |
|---|---|
payment_methods | Qué métodos aceptas: débito inmediato, pago móvil, cripto |
default_bank_account_id | A qué cuenta tuya se acredita por defecto |
split | Si lo que llega por aquí puede repartirse. Habilita; no distribuye |
rules | A qué cuenta va según el banco desde el que pagan. El contrato lo marca «En Desarrollo» — no lo pongas en tu integración todavía |
Cada destino tiene su agreement_id, y es lo que dice, en cada pago, por dónde lo enruta SPIDI.
→ A fondo: El acuerdo de liquidación — sus campos uno a uno y por qué split es un booleano.
La sesión: cada pago concreto
Cada pago que recibes es una sesión, y la creas con una sola llamada sobre un destino. SPIDI te devuelve una payment_url —dentro de data— y un status que arranca en pending.
Lo que eliges en cada sesión son dos cosas independientes: cuánto vive esa dirección —minutos con un Botón, hasta una fecha con una Solicitud, o para siempre dentro de una Parada— y si el dinero va a una cuenta o repartido.
→ A fondo: Las formas de recibir un pago
El partner: quién más recibe, cuando repartes
Si repartes un pago, la otra parte tiene que poder recibirlo. Pero no tiene por qué ser cliente de SPIDI.
Un partner es un receptor de fondos: una persona o un negocio con una cuenta bancaria donde llega su cuotaparte. No es una cuenta en SPIDI — no se registra, no tiene token, no entra a ningún sitio.
Lo das de alta tú, por API, y sin que él haga nada. Ni un correo, ni una clave, ni una confirmación. Y es autoservicio: no hay que pedirle el alta a nadie ni esperar aprobación.
Lo que sí necesitas son sus datos bancarios exactos, porque se validan de verdad. Un dígito mal y el alta no pasa.
Al darlo de alta recibes un identificador que empieza por rcv_. Ese identificador es su acuerdo de recepción: dice a qué cuenta va su parte, y es lo que usas en cada sesión para indicar cuánto le toca.
Hay además un endpoint dedicado de acuerdos de recepción, para cuando necesites reglas más finas que «esta cuenta». Al usarlos son indistinguibles: la sesión solo lleva el rcv_, y ningún campo dice de qué endpoint salió.
→ A fondo: Split
Cómo encaja todo
El destino habilita el reparto; la sesión lo detalla. Poner split: true en el destino no distribuye nada por sí solo: dice que por ahí puede entrar un pago repartido. Cuánto le toca a cada rcv_ se dice en cada sesión.