S-Interio Payout API

La API de Payouts te permite crear y gestionar pagos programáticamente. Soporta múltiples monedas y métodos de pago en Latinoamérica.

Segura

Autenticación via API Key con HTTPS obligatorio

Multi-región

Colombia, Argentina, México, Costa Rica, Brasil, Guatemala, Chile, Bolivia y Perú

Simple

REST API con respuestas JSON claras

Base URL

https://dashboard-payouts.s-interio.com/api/v1

Ambientes

La API tiene dos ambientes separados: Production y Sandbox. Cada uno tiene su propia API Key y endpoints diferentes.

Característica	Production	Sandbox
API Key prefix	`pk_live_`	`pk_test_`
Base URL	`/api/v1/payouts`	`/api/v1/sandbox/payouts`
Payouts reales	Sí	No
Aparece en dashboard	Sí	Sí (marcado como SANDBOX)
Uso recomendado	Producción	Desarrollo y pruebas

Importante: Usa siempre el ambiente Sandbox para desarrollo y pruebas. Los payouts de sandbox no se procesan ni generan transferencias reales.

Autenticación

Todas las llamadas a la API requieren autenticación mediante una API Key. Puedes obtener tu API Key desde el panel de administración en la sección de Merchants.

Métodos de Autenticación

Puedes enviar tu API Key de dos formas:

Header X-API-Key (Recomendado)

X-API-Key: pk_live_xxxxxxxxxxxxxxxx

Header Authorization

Authorization: Bearer pk_live_xxxxxxxxxxxxxxxx

Importante: Mantén tu API Key segura. No la compartas ni la incluyas en código del lado del cliente.

Manejo de Errores

La API utiliza códigos de estado HTTP estándar para indicar el resultado de las solicitudes.

Código	Descripción
`200`	Solicitud exitosa
`201`	Recurso creado exitosamente
`400`	Error de validación - revisa los parámetros enviados
`401`	API Key inválida o no proporcionada
`403`	No autorizado para acceder al recurso
`404`	Recurso no encontrado
`500`	Error interno del servidor

Formato de Error

Respuesta de Error

{
  "success": false,
  "error": "Descripción del error"
}

POST

Crear Payout

Crea una nueva solicitud de payout.

POST /api/v1/payouts

Parámetros del Body

Parámetro	Tipo	Requerido	Descripción
`amount`	number	Sí	Monto a pagar (debe ser mayor a 0)
`currency`	string	Sí	Código de moneda: COP, ARS, MXN, CRC, BRL, GTQ, CLP, BOB, PEN
`reference`	string	No	Referencia externa (ej: order-123)
`bankDetails`	object	Sí	Datos bancarios del beneficiario

Ejemplo - Colombia (COP)

Request

curl -X POST https://dashboard-payouts.s-interio.com/api/v1/payouts \
  -H "X-API-Key: pk_live_xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 500000,
    "currency": "COP",
    "reference": "order-12345",
    "bankDetails": {
      "firstName": "Juan",
      "lastName": "Pérez",
      "email": "juan@email.com",
      "idType": "cc",
      "idNumber": "1234567890",
      "bankCode": "1007",
      "bankName": "Bancolombia",
      "accountType": "savings",
      "accountNumber": "12345678901",
      "phone": "+573001234567"
    }
  }'

Ejemplo - Argentina (ARS)

Request

curl -X POST https://dashboard-payouts.s-interio.com/api/v1/payouts \
  -H "X-API-Key: pk_live_xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 50000,
    "currency": "ARS",
    "reference": "order-12345",
    "bankDetails": {
      "firstName": "María",
      "lastName": "González",
      "cvuCbu": "0000003100000000000001",
      "cuitCuil": "20-12345678-9"
    }
  }'

Ejemplo - México (MXN)

Request

curl -X POST https://dashboard-payouts.s-interio.com/api/v1/payouts \
  -H "X-API-Key: pk_live_xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 10000,
    "currency": "MXN",
    "reference": "order-12345",
    "bankDetails": {
      "firstName": "Carlos",
      "lastName": "Rodríguez",
      "curp": "RODC850101HDFRRL06",
      "rfc": "RODC850101AB3",
      "bankCode": "40012",
      "bankName": "BBVA",
      "clabe": "012345678901234567",
      "accountType": "SAVINGS",
      "phone": "+525512345678"
    }
  }'

Ejemplo - Costa Rica (CRC)

Request

curl -X POST https://dashboard-payouts.s-interio.com/api/v1/payouts \
  -H "X-API-Key: pk_live_xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 100000,
    "currency": "CRC",
    "reference": "order-12345",
    "bankDetails": {
      "firstName": "Ana",
      "lastName": "Mora",
      "cedula": "123456789",
      "iban": "CR12345678901234567890",
      "bankName": "Banco Nacional",
      "accountType": "savings",
      "email": "ana@email.com"
    }
  }'

Ejemplo - Brasil (BRL) - Solo PIX

Request

curl -X POST https://dashboard-payouts.s-interio.com/api/v1/payouts \
  -H "X-API-Key: pk_live_xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 1000,
    "currency": "BRL",
    "reference": "order-12345",
    "bankDetails": {
      "firstName": "Pedro",
      "lastName": "Silva",
      "cpf": "123.456.789-00",
      "pixKeyType": "email",
      "pixKey": "pedro@email.com"
    }
  }'

Ejemplo - Guatemala (GTQ)

Request

curl -X POST https://dashboard-payouts.s-interio.com/api/v1/payouts \
  -H "X-API-Key: pk_live_xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 5000,
    "currency": "GTQ",
    "reference": "order-12345",
    "bankDetails": {
      "firstName": "Luis",
      "lastName": "Hernández",
      "dpi": "1234567890101",
      "bankName": "Banco Industrial",
      "accountType": "savings",
      "accountNumber": "1234567890"
    }
  }'

Ejemplo - Chile (CLP)

Request

curl -X POST https://dashboard-payouts.s-interio.com/api/v1/payouts \
  -H "X-API-Key: pk_live_xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 100000,
    "currency": "CLP",
    "reference": "order-12345",
    "bankDetails": {
      "firstName": "Camila",
      "lastName": "Muñoz",
      "rut": "12345678-9",
      "bankName": "Banco de Chile",
      "accountType": "savings",
      "accountNumber": "12345678",
      "email": "camila@email.com"
    }
  }'

Ejemplo - Bolivia (BOB)

Request

curl -X POST https://dashboard-payouts.s-interio.com/api/v1/payouts \
  -H "X-API-Key: pk_live_xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 5000,
    "currency": "BOB",
    "reference": "order-12345",
    "bankDetails": {
      "firstName": "Carlos",
      "lastName": "Mamani",
      "ci": "1234567",
      "bankName": "Banco Union",
      "accountType": "savings",
      "accountNumber": "1234567890"
    }
  }'

Ejemplo - Perú (PEN)

Request

curl -X POST https://dashboard-payouts.s-interio.com/api/v1/payouts \
  -H "X-API-Key: pk_live_xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 500,
    "currency": "PEN",
    "reference": "order-12345",
    "bankDetails": {
      "firstName": "Juan",
      "lastName": "Pérez",
      "dni": "12345678",
      "bankCode": "002",
      "bankName": "Banco de Crédito del Perú",
      "accountType": "savings",
      "accountNumber": "00212345678901234567",
      "phone": "+51987654321"
    }
  }'

Respuesta Exitosa

Response - 201 Created

{
  "success": true,
  "data": {
    "payoutId": "abc123xyz",
    "status": "pending",
    "amount": 500000,
    "currency": "COP",
    "reference": "order-12345",
    "createdAt": "2024-01-15T10:30:00.000Z"
  }
}

GET

Listar Payouts

Obtiene la lista de payouts creados por tu merchant.

GET /api/v1/payouts

Parámetros de Query

Parámetro	Tipo	Default	Descripción
`status`	string	-	Filtrar por estado: pending, approved, completed, rejected
`reference`	string	-	Filtrar por referencia externa
`limit`	number	50	Número máximo de resultados (máx: 100)

Ejemplo

Request

curl -X GET "https://dashboard-payouts.s-interio.com/api/v1/payouts?status=pending&limit=10" \
  -H "X-API-Key: pk_live_xxxxxxxx"

Respuesta

Response - 200 OK

{
  "success": true,
  "data": [
    {
      "payoutId": "abc123xyz",
      "status": "pending",
      "amount": 500000,
      "currency": "COP",
      "reference": "order-12345",
      "beneficiary": {
        "firstName": "Juan",
        "lastName": "Pérez"
      },
      "createdAt": "2024-01-15T10:30:00.000Z",
      "updatedAt": "2024-01-15T10:30:00.000Z",
      "processedAt": null
    }
  ],
  "count": 1
}

GET

Obtener Payout

Obtiene los detalles de un payout específico.

GET /api/v1/payouts/{payoutId}

Parámetros de URL

Parámetro	Tipo	Descripción
`payoutId`	string	ID del payout a consultar

Ejemplo

Request

curl -X GET https://dashboard-payouts.s-interio.com/api/v1/payouts/abc123xyz \
  -H "X-API-Key: pk_live_xxxxxxxx"

Respuesta

Response - 200 OK

{
  "success": true,
  "data": {
    "payoutId": "abc123xyz",
    "status": "completed",
    "amount": 500000,
    "currency": "COP",
    "reference": "order-12345",
    "beneficiary": {
      "firstName": "Juan",
      "lastName": "Pérez"
    },
    "bankDetails": {
      "bankName": "Bancolombia",
      "accountType": "savings",
      "accountNumberLast4": "8901"
    },
    "createdAt": "2024-01-15T10:30:00.000Z",
    "updatedAt": "2024-01-15T12:00:00.000Z",
    "processedAt": "2024-01-15T12:00:00.000Z"
  }
}

Webhooks

Los webhooks te permiten recibir notificaciones en tiempo real cuando el estado de un payout cambia. Configura una URL de callback y recibirás un POST con los detalles del cambio.

Configuración

Para configurar tu webhook, ve al panel de administración → Merchants → Tu merchant → API Keys → sección Webhook. Ingresa la URL donde quieres recibir las notificaciones.

Funciona en ambos ambientes: Los webhooks se envían tanto para payouts de producción como de sandbox. El campo environment te indica de cuál se trata.

Headers Enviados

Header	Descripción
`Content-Type`	application/json
`X-Webhook-Event`	Tipo de evento: payout.created, payout.status_changed
`X-Merchant-Id`	ID de tu merchant

Respuesta Esperada

Tu endpoint debe responder con un código HTTP 2xx para confirmar la recepción. Si no recibimos una respuesta exitosa, el webhook no se reintentará automáticamente.

Eventos de Webhook

payout.created

Se envía cuando un payout es creado exitosamente via API.

Payload

{
  "event": "payout.created",
  "payoutId": "abc123xyz",
  "status": "pending",
  "amount": 500000,
  "currency": "COP",
  "reference": "order-12345",
  "environment": "production",
  "timestamp": "2024-01-15T10:30:00.000Z"
}

payout.status_changed

Se envía cada vez que el estado de un payout cambia (pending → approved, approved → completed, etc.)

Payload

{
  "event": "payout.status_changed",
  "payoutId": "abc123xyz",
  "status": "completed",
  "previousStatus": "approved",
  "amount": 500000,
  "currency": "COP",
  "reference": "order-12345",
  "environment": "production",
  "timestamp": "2024-01-15T12:00:00.000Z"
}

Campos del Payload

Campo	Tipo	Descripción
`event`	string	Tipo de evento
`payoutId`	string	ID único del payout
`status`	string	Nuevo estado: pending, approved, completed, rejected
`previousStatus`	string	Estado anterior
`amount`	number	Monto del payout
`currency`	string	Código de moneda
`reference`	string \| null	Referencia externa (si se proporcionó)
`environment`	string	`production` o `sandbox`
`timestamp`	string	Fecha/hora del evento (ISO 8601)

Ejemplo de Implementación

Node.js / Express

app.post('/webhook/payouts', (req, res) => {
  const { event, payoutId, status, previousStatus, environment } = req.body;

  // Ignorar webhooks de sandbox en producción
  if (environment === 'sandbox') {
    console.log('Webhook de sandbox recibido, ignorando...');
    return res.sendStatus(200);
  }

  // Payout creado exitosamente
  if (event === 'payout.created') {
    console.log(`Payout ${payoutId} creado con estado ${status}`);
    // Guardar el payoutId en tu base de datos, etc.
  }

  // Procesar cambio de estado
  if (event === 'payout.status_changed') {
    console.log(`Payout ${payoutId}: ${previousStatus} → ${status}`);

    if (status === 'completed') {
      // El payout fue completado exitosamente
      // Actualizar tu base de datos, notificar al usuario, etc.
    } else if (status === 'rejected') {
      // El payout fue rechazado
      // Tomar acciones correspondientes
    }
  }

  res.sendStatus(200);
});

Monedas Soportadas

Código	País	Moneda	Método de Pago
`COP`	Colombia	Peso Colombiano	Transferencia bancaria
`ARS`	Argentina	Peso Argentino	CVU/CBU
`MXN`	México	Peso Mexicano	Transferencia bancaria
`CRC`	Costa Rica	Colón Costarricense	IBAN
`BRL`	Brasil	Real Brasileño	PIX
`GTQ`	Guatemala	Quetzal	Transferencia bancaria
`CLP`	Chile	Peso Chileno	Transferencia bancaria
`BOB`	Bolivia	Boliviano	Transferencia bancaria
`PEN`	Perú	Sol Peruano	Transferencia bancaria

Estados del Payout

Estado	Descripción
pending	El payout ha sido creado y está pendiente de revisión
approved	El payout ha sido aprobado y está siendo procesado
completed	El payout ha sido completado y el dinero transferido
rejected	El payout ha sido rechazado

Datos Bancarios por País

Colombia (COP)

Campo	Tipo	Requerido	Descripción
`firstName`	string	Sí	Nombre del beneficiario
`lastName`	string	Sí	Apellido del beneficiario
`idType`	string	Sí	Tipo de documento: cc, ce, nit, passport, ti
`idNumber`	string	Sí	Número de documento
`bankCode`	string	Sí	Código del banco (ej: "1007" Bancolombia, "1001" Bogotá)
`bankName`	string	Sí	Nombre del banco
`accountType`	string	Sí	Tipo de cuenta: savings, checking
`accountNumber`	string	Sí	Número de cuenta bancaria
`email`	string	No	Email del beneficiario
`phone`	string	No	Teléfono del beneficiario (ej: +573001234567)

Argentina (ARS)

Campo	Tipo	Requerido	Descripción
`firstName`	string	Sí	Nombre del beneficiario
`lastName`	string	Sí	Apellido del beneficiario
`cvuCbu`	string	Sí	CVU o CBU (22 dígitos)
`cuitCuil`	string	Sí	CUIT o CUIL

México (MXN)

Campo	Tipo	Requerido	Descripción
`firstName`	string	Sí	Nombre del beneficiario
`lastName`	string	Sí	Apellido del beneficiario
`curp`	string	Sí	CURP del beneficiario (18 caracteres)
`rfc`	string	No	RFC fiscal (13 caracteres)
`bankCode`	string	Sí	Código del banco (ej: "40012" BBVA, "90722" Mercado Pago)
`bankName`	string	Sí	Nombre del banco
`clabe`	string	Sí	CLABE interbancaria (18 dígitos)
`accountType`	string	Sí	Tipo de cuenta: SAVINGS, CHECKING
`phone`	string	No	Teléfono del beneficiario (ej: +525512345678)

Costa Rica (CRC)

Campo	Tipo	Requerido	Descripción
`firstName`	string	Sí	Nombre del beneficiario
`lastName`	string	Sí	Apellido del beneficiario
`cedula`	string	Sí	Número de cédula
`iban`	string	Sí	IBAN costarricense
`bankName`	string	Sí	Nombre del banco
`accountType`	string	Sí	Tipo de cuenta: savings, checking
`email`	string	No	Email del beneficiario (opcional)

Brasil (BRL) - Solo PIX

Campo	Tipo	Requerido	Descripción
`firstName`	string	Sí	Nombre del beneficiario
`lastName`	string	Sí	Apellido del beneficiario
`cpf`	string	Sí	CPF del beneficiario
`pixKeyType`	string	Sí	Tipo de clave PIX: cpf, email, phone, random
`pixKey`	string	Sí	Clave PIX

Guatemala (GTQ)

Campo	Tipo	Requerido	Descripción
`firstName`	string	Sí	Nombre del beneficiario
`lastName`	string	Sí	Apellido del beneficiario
`dpi`	string	Sí	Documento Personal de Identificación (DPI)
`bankName`	string	Sí	Nombre del banco
`accountType`	string	Sí	Tipo de cuenta: savings, checking
`accountNumber`	string	Sí	Número de cuenta bancaria

Bancos soportados (Guatemala):

Credito Hipotecario Nacional
BANTRAB
Banco Cuscatlan
Banco Industrial
Banrural
Banco Internacional
Vivibanco
FICOHSA
Banco Promerica
Banco Antigua
BAC
Banco G&T Continental
Banco Azteca
INVA
Credicorp
Nexa
BAM

Chile (CLP)

Campo	Tipo	Requerido	Descripción
`firstName`	string	Sí	Nombre del beneficiario
`lastName`	string	Sí	Apellido del beneficiario
`rut`	string	Sí	RUT del beneficiario (ej: 12345678-9)
`bankName`	string	Sí	Nombre del banco
`accountType`	string	Sí	Tipo de cuenta: savings, checking
`accountNumber`	string	Sí	Número de cuenta bancaria
`email`	string	Sí	Email del beneficiario (requerido para Chile)

Bolivia (BOB)

Campo	Tipo	Requerido	Descripción
`firstName`	string	Sí	Nombre del beneficiario
`lastName`	string	Sí	Apellido del beneficiario
`ci`	string	Sí	Cédula de Identidad boliviana (7-10 dígitos)
`bankName`	string	Sí	Nombre del banco
`accountType`	string	Sí	Tipo de cuenta: savings, checking
`accountNumber`	string	Sí	Número de cuenta bancaria
`email`	string	No	Email del beneficiario

Perú (PEN)

Campo	Tipo	Requerido	Descripción
`firstName`	string	Sí	Nombre del beneficiario
`lastName`	string	Sí	Apellido del beneficiario
`dni`	string	Sí	DNI peruano (8 dígitos)
`bankCode`	string	Sí	Código del banco (ej: "002" BCP, "003" Interbank)
`bankName`	string	Sí	Nombre del banco
`accountType`	string	Sí	Tipo de cuenta: savings, checking
`accountNumber`	string	Sí	Código de Cuenta Interbancario - CCI (20 dígitos)
`phone`	string	No	Teléfono del beneficiario (ej: +51987654321)

POST SANDBOX

Crear Payout (Sandbox)

Crea un payout de prueba en el ambiente sandbox.

POST /api/v1/sandbox/payouts

Sandbox: Requiere una Test API Key (pk_test_...). Los payouts creados aquí no se procesan ni generan transferencias reales.

Los parámetros son idénticos a los del endpoint de producción. La única diferencia es que debes usar tu Test API Key.

Ejemplo

Request

curl -X POST https://dashboard-payouts.s-interio.com/api/v1/sandbox/payouts \
  -H "X-API-Key: pk_test_xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 500000,
    "currency": "COP",
    "reference": "test-order-123",
    "bankDetails": {
      "firstName": "Juan",
      "lastName": "Pérez",
      "idType": "cc",
      "idNumber": "1234567890",
      "bankName": "Bancolombia",
      "accountType": "savings",
      "accountNumber": "12345678901"
    }
  }'

Respuesta

Response - 201 Created

{
  "success": true,
  "environment": "sandbox",
  "data": {
    "payoutId": "abc123xyz",
    "status": "pending",
    "amount": 500000,
    "currency": "COP",
    "reference": "test-order-123",
    "createdAt": "2024-01-15T10:30:00.000Z"
  }
}

GET SANDBOX

Listar Payouts (Sandbox)

Lista los payouts de prueba creados en sandbox.

GET /api/v1/sandbox/payouts

Acepta los mismos parámetros de query que el endpoint de producción: status, reference, limit.

Ejemplo

Request

curl -X GET "https://dashboard-payouts.s-interio.com/api/v1/sandbox/payouts?limit=10" \
  -H "X-API-Key: pk_test_xxxxxxxx"

Respuesta

Response - 200 OK

{
  "success": true,
  "environment": "sandbox",
  "data": [
    {
      "payoutId": "abc123xyz",
      "status": "pending",
      "amount": 500000,
      "currency": "COP",
      "reference": "test-order-123",
      "environment": "sandbox",
      "beneficiary": {
        "firstName": "Juan",
        "lastName": "Pérez"
      },
      "createdAt": "2024-01-15T10:30:00.000Z"
    }
  ],
  "count": 1
}

GET SANDBOX

Obtener Payout (Sandbox)

Obtiene los detalles de un payout de prueba específico.

GET /api/v1/sandbox/payouts/{payoutId}

Ejemplo

Request

curl -X GET https://dashboard-payouts.s-interio.com/api/v1/sandbox/payouts/abc123xyz \
  -H "X-API-Key: pk_test_xxxxxxxx"

Respuesta

Response - 200 OK

{
  "success": true,
  "environment": "sandbox",
  "data": {
    "payoutId": "abc123xyz",
    "status": "pending",
    "amount": 500000,
    "currency": "COP",
    "reference": "test-order-123",
    "beneficiary": {
      "firstName": "Juan",
      "lastName": "Pérez"
    },
    "bankDetails": {
      "bankName": "Bancolombia",
      "accountType": "savings",
      "accountNumberLast4": "8901"
    },
    "createdAt": "2024-01-15T10:30:00.000Z",
    "updatedAt": "2024-01-15T10:30:00.000Z"
  }
}