Referencia de la API

API REST de e-Payouts para comercios: crear pagos (paymentbox hospedado), consultar su estado, métodos disponibles, saldo y devoluciones. JSON sobre HTTPS; autenticación exclusivamente por cabeceras firmadas con HMAC-SHA256. Los montos viajan siempre como texto con dos decimales y punto ("49.90"), y las fechas en UTC (ISO 8601).

URL base: https://api.e-payouts.com · Todas las rutas requieren las cabeceras firmadas salvo las marcadas "sin autenticación". Autenticación →

Cuenta

Probar las credenciales, consultar el saldo y ver tus módulos y sus métodos de pago.

GET /v2/ping

Probar credenciales

Verifica que tu Key ID, tu secreto y la firma estén bien, sin hacer nada más. Devuelve el nombre del comercio dueño de la clave y la hora del servidor: si la firma falla por timestamp_out_of_range, compará server_time con el reloj de tu servidor. Es la primera llamada recomendada al integrar.

Respuestas

200 OK
401 Firma ausente, inválida, vencida o reutilizada.
429 Límite de solicitudes superado (ver Retry-After).
503 Mantenimiento o API desactivada.

Esquema y ejemplo de respuesta

Campo	Tipo	Descripción
data obligatorio	object
data.object	"ping"
data.merchant	string	Nombre del comercio dueño de la clave.
data.uid	integer \| null	Tu id de comercio de v1, si la cuenta viene de v1; si no, null.
data.server_time	string	Hora del servidor (UTC).

Ejemplo

{
    "data": {
        "object": "ping",
        "merchant": "Mi Tienda SL",
        "uid": 73,
        "server_time": "2026-09-30T15:04:05Z"
    }
}

GET /v2/balance

Saldo por moneda

Devuelve tu saldo en cada moneda en la que tenés cuenta: lo disponible para retirar, lo pendiente (pagos cobrados que esperan su fecha de disponibilidad) y lo retenido (reservas de garantía). Es el mismo saldo que ves en tu panel de comercio.

Respuestas

200 OK
401 Firma ausente, inválida, vencida o reutilizada.
429 Límite de solicitudes superado (ver Retry-After).
503 Mantenimiento o API desactivada.

Esquema y ejemplo de respuesta

Campo	Tipo	Descripción
data obligatorio	array
data.[].object	"balance"
data.[].currency	string · ^[A-Z]{3}$	Moneda del saldo.
data.[].available	string · ^\d+\.\d{2}$	Disponible para retirar.
data.[].pending	string · ^\d+\.\d{2}$	Pendiente: pagos cobrados que todavía esperan su fecha de disponibilidad.
data.[].reserved	string · ^\d+\.\d{2}$	Retenido: reservas de garantía, hasta su fecha de devolución.
data.[].updated_at	string	Último movimiento (UTC).

Ejemplo

{
    "data": [
        {
            "object": "balance",
            "currency": "EUR",
            "available": "1250.40",
            "pending": "486.15",
            "reserved": "62.30",
            "updated_at": "2026-09-30T14:35:10Z"
        }
    ]
}

GET /v2/modules

Listar módulos

Devuelve todos los módulos de tu cuenta con su sitio. Un módulo es una integración de pago (una tienda o un formulario): cada pago se crea para un módulo, que define los métodos habilitados, la URL de notificación y si está en producción (live) o en prueba (sandbox). Usalo para obtener el id del módulo que necesitás al crear pagos.

Respuestas

200 OK
401 Firma ausente, inválida, vencida o reutilizada.
429 Límite de solicitudes superado (ver Retry-After).
503 Mantenimiento o API desactivada.

Esquema y ejemplo de respuesta

Campo	Tipo	Descripción
data obligatorio	array
data.[].id	string	Id del módulo (UUID): el que mandás en module al crear pagos.
data.[].object	"module"
data.[].mid	integer \| null	mid de v1, si el módulo viene de v1.
data.[].name	string	Nombre que le pusiste.
data.[].mode	string (live \| sandbox)	live = cobra de verdad; sandbox = prueba con simulador.
data.[].status	string (created \| enabled \| disabled \| off)	Solo enabled puede cobrar.
data.[].price	string \| null	Precio por defecto, si tiene.
data.[].currency	string \| null	Moneda del precio, si tiene.
data.[].site	object	Sitio al que pertenece.
data.[].site.name	string
data.[].site.url	string
data.[].site.status	string (created \| enabled \| disabled \| locked \| off)	Solo enabled puede cobrar.

Ejemplo

{
    "data": [
        {
            "id": "7c1e4a52-5d0b-4f7e-9a1d-3b8f2c6d9e10",
            "object": "module",
            "mid": 55,
            "name": "Tienda principal",
            "mode": "live",
            "status": "enabled",
            "price": null,
            "currency": null,
            "site": {
                "name": "tienda.example.com",
                "url": "https://tienda.example.com",
                "status": "enabled"
            }
        }
    ]
}

GET /v2/modules/{module}

Ver un módulo

Devuelve un módulo de tu cuenta: nombre, modo (live o sandbox), estado, precio por defecto si tiene y su sitio. Sirve, por ejemplo, para comprobar antes de cobrar que el módulo y su sitio están habilitados.

Parámetros

Nombre	En	Tipo	Descripción
module obligatorio	path	string	Id del módulo (UUID) o mid de v1.

Respuestas

200 OK
401 Firma ausente, inválida, vencida o reutilizada.
404 No existe o pertenece a otro comercio.
429 Límite de solicitudes superado (ver Retry-After).
503 Mantenimiento o API desactivada.

Esquema y ejemplo de respuesta

Campo	Tipo	Descripción
data obligatorio	object
data.id	string	Id del módulo (UUID): el que mandás en module al crear pagos.
data.object	"module"
data.mid	integer \| null	mid de v1, si el módulo viene de v1.
data.name	string	Nombre que le pusiste.
data.mode	string (live \| sandbox)	live = cobra de verdad; sandbox = prueba con simulador.
data.status	string (created \| enabled \| disabled \| off)	Solo enabled puede cobrar.
data.price	string \| null	Precio por defecto, si tiene.
data.currency	string \| null	Moneda del precio, si tiene.
data.site	object	Sitio al que pertenece.
data.site.name	string
data.site.url	string
data.site.status	string (created \| enabled \| disabled \| locked \| off)	Solo enabled puede cobrar.

Ejemplo

{
    "data": {
        "id": "7c1e4a52-5d0b-4f7e-9a1d-3b8f2c6d9e10",
        "object": "module",
        "mid": 55,
        "name": "Tienda principal",
        "mode": "live",
        "status": "enabled",
        "price": null,
        "currency": null,
        "site": {
            "name": "tienda.example.com",
            "url": "https://tienda.example.com",
            "status": "enabled"
        }
    }
}

GET /v2/modules/{module}/methods

Métodos disponibles

Devuelve los métodos de pago que el paymentbox le ofrecería al cliente para ese módulo, monto y país, con el código que usa tu integración, el mínimo y el máximo de cada uno y la comisión estimada. Sirve para mostrar los métodos en tu propia tienda o para preseleccionar uno al crear el pago (campo method). amount y currency son obligatorios si el módulo no tiene precio fijo.

Parámetros

Nombre	En	Tipo	Descripción
module obligatorio	path	string	Id del módulo (UUID) o mid de v1.
amount	query	string · ^\d+\.\d{2}$	Monto, con punto decimal.
currency	query	string · ^[A-Z]{3}$	Moneda del monto (ISO 4217). Por defecto: "EUR"
country	query	string · ^[A-Za-z]{2}$	País del cliente (ISO 3166-1 alfa-2). Algunos métodos solo se ofrecen en ciertos países.
lang	query	string (en \| es \| fr \| de \| it \| pt)	Idioma del nombre de cada método (el que ve el cliente en el checkout). Sin este parámetro, el idioma de tu cuenta.

Respuestas

200 OK
401 Firma ausente, inválida, vencida o reutilizada.
403 IP no permitida o comercio deshabilitado.
404 No existe o pertenece a otro comercio.
422 Validación fallida: ver error.fields.
429 Límite de solicitudes superado (ver Retry-After).
503 Mantenimiento o API desactivada.

Esquema y ejemplo de respuesta

Campo	Tipo	Descripción
data	array
data.[].object	"method"
data.[].code	string	El código que usa tu integración (con el ruteo aplicado); es el que mandás en method.
data.[].name	string	Nombre para mostrar.
data.[].min	string \| null	Monto mínimo; null = sin mínimo.
data.[].max	string \| null	Monto máximo; null = sin máximo.
data.[].commission	object	Comisión estimada para ese monto.
data.[].commission.amount	string · ^\d+\.\d{2}$
data.[].commission.currency	string
data.[].requires_phone	boolean	true si el cliente tiene que dar su teléfono (MB WAY).
amount	string · ^\d+\.\d{2}$	Monto usado para el cálculo (el precio fijo del módulo, si tiene).
currency	string · ^[A-Z]{3}$	Moneda del monto.
sandbox	boolean	true si el módulo está en modo prueba.

Ejemplo

{
    "data": [
        {
            "object": "method",
            "code": "safetypay",
            "name": "SafetyPay",
            "min": "10.00",
            "max": "2000.00",
            "commission": {
                "amount": "8.74",
                "currency": "EUR"
            },
            "requires_phone": false
        },
        {
            "object": "method",
            "code": "multibanco",
            "name": "Multibanco",
            "min": "5.00",
            "max": "1000.00",
            "commission": {
                "amount": "3.17",
                "currency": "EUR"
            },
            "requires_phone": false
        },
        {
            "object": "method",
            "code": "mbway",
            "name": "MB WAY",
            "min": "5.00",
            "max": "1000.00",
            "commission": {
                "amount": "3.17",
                "currency": "EUR"
            },
            "requires_phone": true
        }
    ],
    "amount": "49.90",
    "currency": "EUR",
    "sandbox": false
}

Pagos

Crear pagos (obtener el enlace del paymentbox) y consultar su estado.

POST /v2/payments

Crear un pago

Prepara un cobro y devuelve checkout_url, la dirección del paymentbox donde el cliente elige el método y paga: redirigilo ahí (o abrila en un iframe). Todavía no existe un pago: se crea cuando el cliente elige el método y paga. El resultado llega por webhook a la URL de notificación del módulo, con el mismo ucode. El enlace vence en 60 minutos.

Parámetros

Nombre	En	Tipo	Descripción
Idempotency-Key	header	string	Opcional (8 a 64 caracteres [A-Za-z0-9_-]). Sirve para reintentar sin duplicar: si repetís la llamada con la misma clave y el mismo cuerpo dentro de 24 h, se devuelve la respuesta original (con la cabecera Idempotent-Replayed: true) en vez de crear otro recurso. Usá una clave nueva por cada operación distinta.

Cuerpo application/json

Campo	Tipo	Descripción
module obligatorio	string	Id del módulo (UUID) o mid de v1.
amount	string · ^\d+\.\d{2}$	Obligatorio si el módulo no tiene precio por defecto. Si el módulo tiene precio fijo, omitilo o mandá ese valor; si no, reemplaza al precio por defecto.
currency	string · ^[A-Z]{3}$	Por defecto, la moneda de tu cuenta. Si es otra, el pago se convierte a la de tu cuenta.
ucode	string · ^[A-Za-z0-9._:/#-]{1,64}$	Tu código de pedido; vuelve en el webhook y en la redirección.
method	string	Preseleccionar un método (ver /methods). Si no está disponible: 422 method_unavailable.
locale	string (en \| es \| fr \| de \| it \| pt)	Idioma del paymentbox. Por defecto: "es"
customer	object	Datos del cliente para completar el formulario del paymentbox (opcional).
customer.name	string	Nombre y apellido.
customer.email	string	Ahí recibe el comprobante.
customer.country	string · ^[A-Za-z]{2}$	País (ISO 3166-1 alfa-2); define qué métodos se ofrecen. Sin país, el paymentbox lo detecta por la IP del cliente y deja que lo cambie.
customer.phone	string	Móvil de Portugal (+351 9XXXXXXXX) para MB WAY. Si mandás también method, name y email, el cliente va directo al proveedor, salvo en MB WAY: ahí ve la pantalla con los datos cargados y confirma con un clic.

Ejemplo de cuerpo

{
    "module": "7c1e4a52-5d0b-4f7e-9a1d-3b8f2c6d9e10",
    "amount": "49.90",
    "currency": "EUR",
    "ucode": "PEDIDO-1042",
    "locale": "es",
    "customer": {
        "name": "Ana García",
        "email": "[email protected]",
        "country": "ES"
    }
}

Respuestas

201 Creado
400 Parámetro inválido o JSON mal formado.
401 Firma ausente, inválida, vencida o reutilizada.
403 IP no permitida o comercio deshabilitado.
404 No existe o pertenece a otro comercio.
409 El estado actual no permite la operación.
415 Content-Type incorrecto.
422 Validación fallida: ver error.fields.
429 Límite de solicitudes superado (ver Retry-After).
503 Mantenimiento o API desactivada.

Esquema y ejemplo de respuesta

Campo	Tipo	Descripción
data obligatorio	object
data.object	"checkout"
data.checkout_url	string	Enlace del paymentbox: llevá al cliente ahí.
data.expires_at	string	Vencimiento del enlace (UTC).
data.sandbox	boolean	true si el módulo está en modo prueba (no se cobra dinero real).
data.module	object	Módulo al que pertenece.
data.module.id	string	Id del módulo (UUID).
data.module.mid	integer \| null	mid de v1, si el módulo viene de v1.
data.amount	string · ^\d+\.\d{2}$	Monto a cobrar.
data.currency	string · ^[A-Z]{3}$	Moneda del monto.
data.ucode	string \| null	Tu código de pedido, si lo mandaste.
data.method	string \| null	Método preseleccionado, si pediste uno.
data.methods	array	Códigos de los métodos que va a ver el cliente.

Ejemplo

{
    "data": {
        "object": "checkout",
        "checkout_url": "http://paymentbox2.e-payouts.local/pagar?t=Xk3v9QpL2mZ7wR4tY8bN1cF6hJ0sD5aG",
        "expires_at": "2026-09-30T16:04:05Z",
        "sandbox": false,
        "module": {
            "id": "7c1e4a52-5d0b-4f7e-9a1d-3b8f2c6d9e10",
            "mid": 55
        },
        "amount": "49.90",
        "currency": "EUR",
        "ucode": "PEDIDO-1042",
        "method": null,
        "methods": [
            "sofort",
            "safetypay",
            "ppal",
            "16cards",
            "multibanco",
            "mbway"
        ]
    }
}

GET /v2/payments

Listar pagos

Busca pagos de tu cuenta y los devuelve del más nuevo al más viejo. Sirve para conciliar: por ejemplo, encontrar el pago de un pedido (ucode), revisar los completados de un día o recuperar el estado si se perdió un webhook. Los filtros se combinan. Devuelve hasta limit pagos por página: si has_more es true, pedí la siguiente pasando next_cursor en cursor. Los pagos de prueba (sandbox) se listan aparte, con sandbox=true.

Parámetros

Nombre	En	Tipo	Descripción
ucode	query	string	Solo los pagos de ese código de pedido.
module	query	string	Solo los de ese módulo: id (UUID) o mid.
status	query	string (created \| pending \| completed \| failed \| cancelled \| refunded \| charged_back)	Solo los que están en ese estado.
created_from	query	string	Creados desde esta fecha (UTC), inclusive: YYYY-MM-DD o YYYY-MM-DDTHH:MM:SSZ.
created_to	query	string	Creados antes de esta fecha (UTC), exclusiva.
sandbox	query	boolean	true = listar los pagos de prueba de módulos en modo sandbox en vez de los reales. Por defecto: false
limit	query	integer	Cantidad de resultados por página (1 a 100). Por defecto: 20
cursor	query	string	Para pedir la página siguiente: el next_cursor de la respuesta anterior.

Respuestas

200 OK
400 Parámetro inválido o JSON mal formado.
401 Firma ausente, inválida, vencida o reutilizada.
404 No existe o pertenece a otro comercio.
429 Límite de solicitudes superado (ver Retry-After).
503 Mantenimiento o API desactivada.

Esquema y ejemplo de respuesta

Campo	Tipo	Descripción
data obligatorio	array
data.[].code	string	Código del pago (UUID).
data.[].object	"payment"
data.[].sandbox	boolean	true = pago de prueba (no movió dinero).
data.[].status	string (created \| pending \| completed \| failed \| cancelled \| refunded \| charged_back)	Solo completed significa cobrado. pending = esperando que el cliente termine (p. ej. referencia Multibanco sin pagar).
data.[].ucode	string \| null	Tu código de pedido.
data.[].method	string	Código del método que eligió el cliente.
data.[].effective_method	string	Método que efectivamente cobró el pago. Distinto de method solo si ese método tiene un ruteo (p. ej. method ppal, effective_method 16cards).
data.[].amount	string · ^\d+\.\d{2}$	Monto que pediste cobrar.
data.[].currency	string · ^[A-Z]{3}$	Moneda de amount.
data.[].charged	object \| null	Solo si el método elegido no acepta la moneda del pago (p. ej. MB WAY y Multibanco cobran en EUR): lo que se le cobró al cliente y la tasa usada (mercado + margen). amount y currency siguen siendo lo que pediste. Si no, null.
data.[].charged.amount	string · ^\d+\.\d{2}$
data.[].charged.currency	string
data.[].charged.exchange_rate	string
data.[].module	object	Módulo al que pertenece.
data.[].module.id	string	Id del módulo (UUID).
data.[].module.mid	integer \| null	mid de v1, si el módulo viene de v1.
data.[].customer	object	Datos que dejó el cliente (cada uno puede ser null).
data.[].customer.name	string \| null
data.[].customer.email	string \| null
data.[].customer.country	string \| null
data.[].commission	object	Comisión de e-Payouts. Solo pagos reales.
data.[].commission.amount	string · ^\d+\.\d{2}$
data.[].commission.currency	string
data.[].net_amount	string \| null	Monto menos comisión, en la moneda de amount (solo pagos reales; null si se cobró en otra moneda: ver settlement).
data.[].settlement	object \| null	Lo que se acredita en tu saldo: monto en la moneda de tu cuenta y tasa aplicada (con margen; null si no hubo conversión). Solo pagos reales.
data.[].settlement.amount	string · ^\d+\.\d{2}$
data.[].settlement.currency	string (EUR \| USD)
data.[].settlement.exchange_rate	string \| null
data.[].completed_at	string \| null	Cuándo se cobró; null si todavía no. Solo pagos reales.
data.[].created_at	string	Cuándo se creó el pago (UTC).
has_more obligatorio	boolean	true si hay más resultados después de esta página.
next_cursor obligatorio	string \| null	Pasalo como cursor para pedir la página siguiente; null en la última página.

Ejemplo

{
    "data": [
        {
            "code": "8a2c4e6f-1b3d-4f5a-9c7e-0d2f4a6b8c1e",
            "object": "payment",
            "sandbox": false,
            "status": "pending",
            "ucode": "PEDIDO-1043",
            "method": "multibanco",
            "effective_method": "multibanco",
            "amount": "12.00",
            "currency": "USD",
            "charged": {
                "amount": "10.65",
                "currency": "EUR",
                "exchange_rate": "0.8877599005"
            },
            "module": {
                "id": "7c1e4a52-5d0b-4f7e-9a1d-3b8f2c6d9e10",
                "mid": 55
            },
            "customer": {
                "name": "João Silva",
                "email": "[email protected]",
                "country": "PT"
            },
            "commission": {
                "amount": "0.82",
                "currency": "EUR"
            },
            "net_amount": null,
            "settlement": {
                "amount": "11.93",
                "currency": "USD",
                "exchange_rate": "1.120629575"
            },
            "completed_at": null,
            "created_at": "2026-09-30T14:35:10Z"
        },
        {
            "code": "3f6b2d10-9a4c-4e21-8b7f-5c0d1e2f3a4b",
            "object": "payment",
            "sandbox": false,
            "status": "completed",
            "ucode": "PEDIDO-1042",
            "method": "sofort",
            "effective_method": "sofort",
            "amount": "49.90",
            "currency": "EUR",
            "charged": null,
            "module": {
                "id": "7c1e4a52-5d0b-4f7e-9a1d-3b8f2c6d9e10",
                "mid": 55
            },
            "customer": {
                "name": "Ana García",
                "email": "[email protected]",
                "country": "ES"
            },
            "commission": {
                "amount": "2.15",
                "currency": "EUR"
            },
            "net_amount": "47.75",
            "settlement": {
                "amount": "49.90",
                "currency": "EUR",
                "exchange_rate": null
            },
            "completed_at": "2026-09-18T14:35:02Z",
            "created_at": "2026-09-18T14:33:22Z"
        }
    ],
    "has_more": true,
    "next_cursor": "MTAyNA"
}

GET /v2/payments/{code}

Ver un pago

Devuelve el estado actual y el detalle de un pago: método, montos, comisión, neto y liquidación. Usalo para confirmar un webhook antes de entregar el pedido (consultá el pago por su id y verificá status y amount) o para mostrar el estado en tu sistema. Sirve para pagos reales y de prueba; los de prueba no traen commission, net_amount, settlement ni completed_at.

Parámetros

Nombre	En	Tipo	Descripción
code obligatorio	path	string	Código del pago (UUID, el campo code del pago).

Respuestas

200 OK
401 Firma ausente, inválida, vencida o reutilizada.
404 No existe o pertenece a otro comercio.
429 Límite de solicitudes superado (ver Retry-After).
503 Mantenimiento o API desactivada.

Esquema y ejemplo de respuesta

Campo	Tipo	Descripción
data obligatorio	object
data.code	string	Código del pago (UUID).
data.object	"payment"
data.sandbox	boolean	true = pago de prueba (no movió dinero).
data.status	string (created \| pending \| completed \| failed \| cancelled \| refunded \| charged_back)	Solo completed significa cobrado. pending = esperando que el cliente termine (p. ej. referencia Multibanco sin pagar).
data.ucode	string \| null	Tu código de pedido.
data.method	string	Código del método que eligió el cliente.
data.effective_method	string	Método que efectivamente cobró el pago. Distinto de method solo si ese método tiene un ruteo (p. ej. method ppal, effective_method 16cards).
data.amount	string · ^\d+\.\d{2}$	Monto que pediste cobrar.
data.currency	string · ^[A-Z]{3}$	Moneda de amount.
data.charged	object \| null	Solo si el método elegido no acepta la moneda del pago (p. ej. MB WAY y Multibanco cobran en EUR): lo que se le cobró al cliente y la tasa usada (mercado + margen). amount y currency siguen siendo lo que pediste. Si no, null.
data.charged.amount	string · ^\d+\.\d{2}$
data.charged.currency	string
data.charged.exchange_rate	string
data.module	object	Módulo al que pertenece.
data.module.id	string	Id del módulo (UUID).
data.module.mid	integer \| null	mid de v1, si el módulo viene de v1.
data.customer	object	Datos que dejó el cliente (cada uno puede ser null).
data.customer.name	string \| null
data.customer.email	string \| null
data.customer.country	string \| null
data.commission	object	Comisión de e-Payouts. Solo pagos reales.
data.commission.amount	string · ^\d+\.\d{2}$
data.commission.currency	string
data.net_amount	string \| null	Monto menos comisión, en la moneda de amount (solo pagos reales; null si se cobró en otra moneda: ver settlement).
data.settlement	object \| null	Lo que se acredita en tu saldo: monto en la moneda de tu cuenta y tasa aplicada (con margen; null si no hubo conversión). Solo pagos reales.
data.settlement.amount	string · ^\d+\.\d{2}$
data.settlement.currency	string (EUR \| USD)
data.settlement.exchange_rate	string \| null
data.completed_at	string \| null	Cuándo se cobró; null si todavía no. Solo pagos reales.
data.created_at	string	Cuándo se creó el pago (UTC).

Ejemplo

{
    "data": {
        "code": "3f6b2d10-9a4c-4e21-8b7f-5c0d1e2f3a4b",
        "object": "payment",
        "sandbox": false,
        "status": "completed",
        "ucode": "PEDIDO-1042",
        "method": "sofort",
        "effective_method": "sofort",
        "amount": "49.90",
        "currency": "EUR",
        "charged": null,
        "module": {
            "id": "7c1e4a52-5d0b-4f7e-9a1d-3b8f2c6d9e10",
            "mid": 55
        },
        "customer": {
            "name": "Ana García",
            "email": "[email protected]",
            "country": "ES"
        },
        "commission": {
            "amount": "2.15",
            "currency": "EUR"
        },
        "net_amount": "47.75",
        "settlement": {
            "amount": "49.90",
            "currency": "EUR",
            "exchange_rate": null
        },
        "completed_at": "2026-09-18T14:35:02Z",
        "created_at": "2026-09-18T14:33:22Z"
    }
}

Devoluciones y contracargos

Pedir la devolución de un pago y consultar devoluciones y contracargos.

POST /v2/payments/{code}/refunds

Solicitar devolución

Pide la devolución total de un pago completado. Queda en estado created hasta que e-Payouts la procesa; solo una devolución viva por pago. Solo se puede pedir dentro del plazo configurado por e-Payouts desde que se completó el pago (hoy, 2 meses); pasado el plazo responde 409 refund_window_expired y hay que pedirla por ticket en tu panel de comercio. Los pagos de prueba no se devuelven.

Parámetros

Nombre	En	Tipo	Descripción
code obligatorio	path	string	Código del pago (UUID, el campo code del pago).
Idempotency-Key	header	string	Opcional (8 a 64 caracteres [A-Za-z0-9_-]). Sirve para reintentar sin duplicar: si repetís la llamada con la misma clave y el mismo cuerpo dentro de 24 h, se devuelve la respuesta original (con la cabecera Idempotent-Replayed: true) en vez de crear otro recurso. Usá una clave nueva por cada operación distinta.

Cuerpo application/json

Campo	Tipo	Descripción
reason	string	Motivo (opcional), para tu registro y el de e-Payouts.

Ejemplo de cuerpo

{
    "reason": "El cliente canceló el pedido"
}

Respuestas

201 Creada
401 Firma ausente, inválida, vencida o reutilizada.
404 No existe o pertenece a otro comercio.
409 El estado actual no permite la operación.
422 Validación fallida: ver error.fields.
429 Límite de solicitudes superado (ver Retry-After).
503 Mantenimiento o API desactivada.

Esquema y ejemplo de respuesta

Campo	Tipo	Descripción
data obligatorio	object
data.id	string	Id de la devolución o del contracargo (UUID).
data.object	string (refund \| chargeback)	refund = devolución; chargeback = contracargo (el cliente reclamó el cobro a su banco).
data.status	string (created \| processing \| completed \| rejected)	created = pedida; processing = en curso; completed = hecha; rejected = rechazada.
data.amount	string · ^\d+\.\d{2}$	Monto devuelto o reclamado.
data.currency	string · ^[A-Z]{3}$	Moneda de amount.
data.reason	string \| null	Motivo, si hay.
data.payment	string	Id del pago (UUID).
data.created_at	string	Cuándo se creó (UTC).
data.resolved_at	string \| null	Cuándo terminó (completed o rejected); null mientras sigue en curso.

Ejemplo

{
    "data": {
        "id": "c4d5e6f7-0a1b-4c2d-8e3f-4a5b6c7d8e9f",
        "object": "refund",
        "status": "created",
        "amount": "49.90",
        "currency": "EUR",
        "reason": "El cliente canceló el pedido",
        "payment": "3f6b2d10-9a4c-4e21-8b7f-5c0d1e2f3a4b",
        "created_at": "2026-09-20T09:12:44Z",
        "resolved_at": null
    }
}

GET /v2/payments/{code}/adjustments

Devoluciones y contracargos de un pago

Devuelve las devoluciones y los contracargos de un pago, del más nuevo al más viejo, con su estado. Sirve para seguir una devolución que pediste o ver si el cliente reclamó el cobro a su banco.

Parámetros

Nombre	En	Tipo	Descripción
code obligatorio	path	string	Código del pago (UUID, el campo code del pago).
limit	query	integer	Cantidad de resultados por página (1 a 100). Por defecto: 20
cursor	query	string	Para pedir la página siguiente: el next_cursor de la respuesta anterior.

Respuestas

200 OK
400 Parámetro inválido o JSON mal formado.
401 Firma ausente, inválida, vencida o reutilizada.
404 No existe o pertenece a otro comercio.
429 Límite de solicitudes superado (ver Retry-After).
503 Mantenimiento o API desactivada.

Esquema y ejemplo de respuesta

Campo	Tipo	Descripción
data obligatorio	array
data.[].id	string	Id de la devolución o del contracargo (UUID).
data.[].object	string (refund \| chargeback)	refund = devolución; chargeback = contracargo (el cliente reclamó el cobro a su banco).
data.[].status	string (created \| processing \| completed \| rejected)	created = pedida; processing = en curso; completed = hecha; rejected = rechazada.
data.[].amount	string · ^\d+\.\d{2}$	Monto devuelto o reclamado.
data.[].currency	string · ^[A-Z]{3}$	Moneda de amount.
data.[].reason	string \| null	Motivo, si hay.
data.[].payment	string	Id del pago (UUID).
data.[].created_at	string	Cuándo se creó (UTC).
data.[].resolved_at	string \| null	Cuándo terminó (completed o rejected); null mientras sigue en curso.
has_more obligatorio	boolean	true si hay más resultados después de esta página.
next_cursor obligatorio	string \| null	Pasalo como cursor para pedir la página siguiente; null en la última página.

Ejemplo

{
    "data": [
        {
            "id": "c4d5e6f7-0a1b-4c2d-8e3f-4a5b6c7d8e9f",
            "object": "refund",
            "status": "created",
            "amount": "49.90",
            "currency": "EUR",
            "reason": "El cliente canceló el pedido",
            "payment": "3f6b2d10-9a4c-4e21-8b7f-5c0d1e2f3a4b",
            "created_at": "2026-09-20T09:12:44Z",
            "resolved_at": null
        }
    ],
    "has_more": false,
    "next_cursor": null
}

GET /v2/adjustments

Listar devoluciones y contracargos

Devuelve las devoluciones y los contracargos de toda tu cuenta, del más nuevo al más viejo. Sirve para conciliar los montos que se descontaron de tu saldo. Se puede filtrar por tipo, estado o pago, y se pagina igual que los pagos.

Parámetros

Nombre	En	Tipo	Descripción
type	query	string (refund \| chargeback)	refund = devoluciones; chargeback = contracargos.
status	query	string (created \| processing \| completed \| rejected)	Solo los que están en ese estado.
payment	query	string	Solo los de ese pago (id UUID).
limit	query	integer	Cantidad de resultados por página (1 a 100). Por defecto: 20
cursor	query	string	Para pedir la página siguiente: el next_cursor de la respuesta anterior.

Respuestas

200 OK
400 Parámetro inválido o JSON mal formado.
401 Firma ausente, inválida, vencida o reutilizada.
404 No existe o pertenece a otro comercio.
429 Límite de solicitudes superado (ver Retry-After).
503 Mantenimiento o API desactivada.

Esquema y ejemplo de respuesta

Campo	Tipo	Descripción
data obligatorio	array
data.[].id	string	Id de la devolución o del contracargo (UUID).
data.[].object	string (refund \| chargeback)	refund = devolución; chargeback = contracargo (el cliente reclamó el cobro a su banco).
data.[].status	string (created \| processing \| completed \| rejected)	created = pedida; processing = en curso; completed = hecha; rejected = rechazada.
data.[].amount	string · ^\d+\.\d{2}$	Monto devuelto o reclamado.
data.[].currency	string · ^[A-Z]{3}$	Moneda de amount.
data.[].reason	string \| null	Motivo, si hay.
data.[].payment	string	Id del pago (UUID).
data.[].created_at	string	Cuándo se creó (UTC).
data.[].resolved_at	string \| null	Cuándo terminó (completed o rejected); null mientras sigue en curso.
has_more obligatorio	boolean	true si hay más resultados después de esta página.
next_cursor obligatorio	string \| null	Pasalo como cursor para pedir la página siguiente; null en la última página.

Ejemplo

{
    "data": [
        {
            "id": "c4d5e6f7-0a1b-4c2d-8e3f-4a5b6c7d8e9f",
            "object": "refund",
            "status": "created",
            "amount": "49.90",
            "currency": "EUR",
            "reason": "El cliente canceló el pedido",
            "payment": "3f6b2d10-9a4c-4e21-8b7f-5c0d1e2f3a4b",
            "created_at": "2026-09-20T09:12:44Z",
            "resolved_at": null
        },
        {
            "id": "d1e2f3a4-5b6c-4d7e-8f9a-0b1c2d3e4f5a",
            "object": "chargeback",
            "status": "completed",
            "amount": "30.00",
            "currency": "EUR",
            "reason": null,
            "payment": "9b8a7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d",
            "created_at": "2026-09-10T16:40:00Z",
            "resolved_at": "2026-09-12T10:05:31Z"
        }
    ],
    "has_more": false,
    "next_cursor": null
}

Compatibilidad v1

Mismos parámetros y respuestas que api.e-payouts.com (v1), con la autenticación nueva. Para migrar sin reescribir la integración. Solo disponibles si la integración v1 está habilitada en tu cuenta.

POST /v1/createCode

createCode (v1): crear pago

Lo mismo que POST /v2/payments con los parámetros de v1: devuelve el enlace del paymentbox al que tenés que llevar al cliente. Con direct presente, en vez de responder JSON redirige (302) directamente a ese enlace. Ojo: a diferencia de las demás rutas v1, la respuesta no trae message ni data.

Cuerpo application/x-www-form-urlencoded

Campo	Tipo	Descripción
uid obligatorio	string	Id de comercio de v1 (el de tu cuenta).
mid obligatorio	string	Id de módulo de v1 (mid).
price	string	Monto (moneda de tu cuenta). Obligatorio si el módulo no tiene precio por defecto; si su precio es fijo, se cobra ese.
type	string	Código de método para preseleccionarlo (opcional).
cc	string	País del cliente (2 letras).
email	string	Email del cliente.
name	string	Nombre del cliente.
lastname	string	Apellido del cliente.
ucode	string	Tu código de pedido.
direct	string	Si está presente (cualquier valor), redirige (302) al paymentbox.

Ejemplo de cuerpo

uid=73&mid=55&price=49.90&cc=es&email=ana%40example.com&name=Ana&lastname=Garc%C3%ADa&ucode=PEDIDO-1042

Respuestas

200 Siempre HTTP 200. Si salió bien, error = 0 con el enlace; si no, error trae el número de error de v1 (ver Errores).
302 Con direct: redirección al paymentbox (cabecera Location).

Esquema y ejemplo de respuesta

Campo	Tipo	Descripción
error	integer	0 = salió bien.
code	string	Código de la sesión de pago (la parte final de url).
url	string	Enlace del paymentbox al que llevás al cliente.
expires_at	string	Vencimiento del enlace (UTC).

Ejemplo

{
    "error": 0,
    "code": "Xk3v9QpL2mZ7wR4tY8bN1cF6hJ0sD5aG",
    "url": "http://paymentbox2.e-payouts.local/pagar?t=Xk3v9QpL2mZ7wR4tY8bN1cF6hJ0sD5aG",
    "expires_at": "2026-09-30T16:04:05Z"
}

POST /v1/getData

getData (v1): sitio, módulo y métodos

Devuelve el estado del sitio y del módulo y los métodos disponibles para un país, con su mínimo y máximo, y la dirección para crear pagos. Equivale a GET /v2/modules/{module}/methods en el formato de v1.

Cuerpo application/x-www-form-urlencoded

Campo	Tipo	Descripción
uid obligatorio	string	Id de comercio de v1 (el de tu cuenta).
mid obligatorio	string	Id de módulo de v1 (mid).
cc obligatorio	string	País del cliente (2 letras).
price	string	Monto; obligatorio si el módulo no tiene precio fijo.

Ejemplo de cuerpo

uid=73&mid=55&cc=pt&price=49.90

Respuestas

200 Siempre HTTP 200. Si salió bien, error = 0 y los datos en data; si no, error trae el número de error de v1 (ver Errores).

Esquema y ejemplo de respuesta

Campo	Tipo	Descripción
error	integer	0 = salió bien.
message	string	Texto fijo de v1.
data	object
data.error	integer	Siempre 0 (se repite dentro de data, como en v1).
data.sites	object	Estado y URL del sitio del módulo.
data.modules	object	Precio, estado, moneda, IPs permitidas (api_ip, separadas por coma) y métodos por país (price, pmin, pmax, name).
data.gateway	object	URL de createCode.

Ejemplo

{
    "error": 0,
    "message": "API response -> successful request.",
    "data": {
        "error": 0,
        "sites": {
            "status": "enabled",
            "url": "https://tienda.example.com"
        },
        "modules": {
            "price": null,
            "status": "enabled",
            "currency": "EUR",
            "country": "pt",
            "api_ip": "",
            "methods": {
                "pt": [
                    {
                        "method": "multibanco",
                        "country": "pt",
                        "price": "49.90",
                        "pmin": "5.00",
                        "pmax": "1000.00",
                        "name": "Multibanco"
                    },
                    {
                        "method": "mbway",
                        "country": "pt",
                        "price": "49.90",
                        "pmin": "5.00",
                        "pmax": "1000.00",
                        "name": "MB WAY"
                    }
                ]
            }
        },
        "gateway": {
            "url": "http://api2.e-payouts.local/v1/createCode"
        }
    }
}

Sin autenticación

Estado del servicio.

GET /health sin autenticación

Estado del servicio

Indica si la API está en línea. No necesita firma: sirve para monitoreo (por ejemplo, un chequeo periódico desde tu servidor).

Respuestas

200 OK

Esquema y ejemplo de respuesta

Campo	Tipo	Descripción
data obligatorio	object
data.status	"ok"	Siempre "ok" si la API responde.

Ejemplo

{
    "data": {
        "status": "ok"
    }
}