Cuentas de retiro

Una cuenta de retiro es la cuenta bancaria o la wallet a la que va el saldo cuando retiras. Por la API puedes ver qué métodos hay para tu país, qué datos pide cada uno, agregar cuentas y listarlas. El retiro en sí se pide desde el dashboard (Retirar): no se crean retiros por API (ver Retiros).

Hay tres tipos (type):

Para gestionar cuentas de retiro hace falta la identidad verificada (si no, 409 payment_account_not_ready).

Seguridad: los datos que mandas en fields viajan cifrados al procesador de pagos y vexorpay no los guarda: la API sólo devuelve una referencia enmascarada (•••• 4567). Cada alta le manda un email de aviso al dueño de la cuenta, se haga por la API o desde el dashboard. Estos endpoints no aceptan el header Vexor-Account: una app de marketplace nunca agrega cuentas de retiro de otro usuario (403 invalid_connected_account).

El flujo para agregar una cuenta es:

1. Listar los métodos disponibles para el type y el país.
2. Ver los campos que pide el método elegido.
3. Agregar la cuenta con esos campos.
4. Listar tus cuentas para confirmarla.

En sandbox (https://api.sandbox.vexorpay.com) el procesador de pagos no tiene retiros: el catálogo de métodos viene vacío y no se pueden agregar cuentas. Las cuentas de retiro se agregan en producción (https://api.vexorpay.com), con tu identidad verificada.

El objeto PayoutMethod

{
  "id": "potk_1a2b3c",
  "type": "local",
  "country": "AR",
  "name": "Transferencia a tu banco (ARS)",
  "nickname": "Mi cuenta sueldo",
  "reference": "•••• 4567",
  "destinationCurrency": "ars",
  "available": true,
  "isDefault": true,
  "createdAt": "2026-11-08T14:20:00.000Z",
  "lastPaidOutAt": null
}

Listar los métodos disponibles

GET /api/v1/payout-methods/supported

Devuelve los métodos con los que se puede agregar una cuenta, sin paginación.

curl "https://api.vexorpay.com/api/v1/payout-methods/supported?type=local&country=AR" \
  -H "Authorization: Bearer vxp_live_tu_clave"

Respuesta exitosa

200 OK

{
  "data": [
    {
      "id": "podst_hWWwr49qe5Wm",
      "type": "local",
      "country": "AR",
      "name": "Transferencia a tu banco (ARS)",
      "destinationCurrency": "ars",
      "feeCents": 150,
      "estimatedArrival": "2026-11-10T12:00:00.000Z"
    }
  ],
  "has_more": false,
  "total_count": 1,
  "url": "/v1/payout-methods/supported?type=local&country=AR"
}

Ver un método y sus campos

GET /api/v1/payout-methods/supported/{id}

Devuelve el método con los fields que hay que mandar al agregar la cuenta. El parámetro country es obligatorio: el mismo con el que listaste el método (US para usd_bank).

curl "https://api.vexorpay.com/api/v1/payout-methods/supported/podst_hWWwr49qe5Wm?country=AR" \
  -H "Authorization: Bearer vxp_live_tu_clave"

Respuesta exitosa

200 OK

{
  "id": "podst_hWWwr49qe5Wm",
  "type": "local",
  "country": "AR",
  "name": "Transferencia a tu banco (ARS)",
  "destinationCurrency": "ars",
  "feeCents": 150,
  "estimatedArrival": "2026-11-10T12:00:00.000Z",
  "fields": [
    {
      "id": "fld_bank_account_number",
      "label": "CBU",
      "type": "text",
      "required": true,
      "sensitive": true,
      "pattern": "^[0-9]{22}$",
      "options": [],
      "fixed": null
    },
    {
      "id": "fld_identification_type",
      "label": "Tipo de documento",
      "type": "select",
      "required": true,
      "sensitive": false,
      "pattern": null,
      "options": [
        { "value": "Tax Payer Identification Card/Number", "label": "Identificación fiscal (CUIT, RUT, RFC…)" }
      ],
      "fixed": "Tax Payer Identification Card/Number"
    },
    {
      "id": "fld_identification_number",
      "label": "CUIT / CUIL",
      "type": "text",
      "required": true,
      "sensitive": true,
      "pattern": "^(20|23|24|27|30|33|34)[-]*[0-9]{8}[-]*[0-9]$",
      "options": [],
      "fixed": null
    }
  ]
}

Los campos cambian según el método y el país: léelos siempre de este endpoint en vez de fijarlos en tu código.

Agregar una cuenta de retiro

POST /api/v1/payout-methods

Agrega una cuenta bancaria o wallet sin hacer un retiro y sin necesitar saldo. Responde 201 Created con el objeto PayoutMethod. Con un token OAuth exige el scope payout_methods:write.

A diferencia del resto de la API, acá un campo desconocido en el body no se ignora: responde 400 validation_error, para que un typo en datos bancarios no pase en silencio.

Idempotencia: manda un header Idempotency-Key (p. ej. un UUID por alta). Un replay con el mismo body devuelve la cuenta ya creada (200) y, si el procesador de pagos no respondió (502 upstream_error), reintentar con la misma clave no crea una segunda cuenta. Ver Idempotencia.

curl -X POST "https://api.vexorpay.com/api/v1/payout-methods" \
  -H "Authorization: Bearer vxp_live_tu_clave" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 8f14e45f-ceea-4b6a-9f8e-2d1c3b4a5f60" \
  -d '{
    "type": "local",
    "supported_method_id": "podst_hWWwr49qe5Wm",
    "country": "AR",
    "destination_currency": "ars",
    "nickname": "Mi cuenta sueldo",
    "fields": {
      "fld_bank_account_number": "0110599520000001234567",
      "fld_identification_type": "Tax Payer Identification Card/Number",
      "fld_identification_number": "20123456789"
    }
  }'

Respuesta exitosa

201 Created (o 200 OK en un replay de idempotencia)

{
  "id": "potk_1a2b3c",
  "type": "local",
  "country": "AR",
  "name": "Transferencia a tu banco (ARS)",
  "nickname": "Mi cuenta sueldo",
  "reference": "•••• 4567",
  "destinationCurrency": "ars",
  "available": true,
  "isDefault": true,
  "createdAt": "2026-11-08T14:20:00.000Z",
  "lastPaidOutAt": null
}

Si un valor no pasa la validación (la tuya o la del procesador de pagos), la respuesta es 400 validation_error y detail.field dice cuál fue: type, supported_method_id, country, destination_currency, nickname, fields o el id fld_… rechazado:

{
  "error": "validation_error",
  "message": "The payment processor rejected a value: check that field.",
  "detail": { "field": "fld_bank_account_number" }
}

Listar cuentas de retiro

GET /api/v1/payout-methods

Lista tus cuentas de retiro guardadas, incluidas las que agregaste desde el dashboard, con su referencia enmascarada. Parámetros: limit, starting_after y ending_before (ver Paginación).

curl "https://api.vexorpay.com/api/v1/payout-methods?limit=10" \
  -H "Authorization: Bearer vxp_live_tu_clave"

Respuesta exitosa

200 OK

{
  "data": [
    {
      "id": "potk_1a2b3c",
      "type": "local",
      "country": "AR",
      "name": "Transferencia a tu banco (ARS)",
      "nickname": "Mi cuenta sueldo",
      "reference": "•••• 4567",
      "destinationCurrency": "ars",
      "available": true,
      "isDefault": true,
      "createdAt": "2026-11-08T14:20:00.000Z",
      "lastPaidOutAt": null
    }
  ],
  "has_more": false,
  "total_count": 1,
  "url": "/v1/payout-methods?limit=10"
}

Errores