Configurar un método de pago con credenciales del comercio y habilitarlo para API keys.

Métodos de pago de la cuenta

Un Payment Method es una configuración de cobro para un owner: une el procesador habilitado con credenciales y parámetros propios del comercio.

Esta API es de management y usa JWT. No debe confundirse con GET /v1/payment-methods, que acepta API key o JWT y expone la vista pública usable para cobrar.

Endpoints

POST   /v1/account/payment-methods
GET    /v1/account/payment-methods
GET    /v1/account/payment-methods/{payment_method_id}
PATCH  /v1/account/payment-methods/{payment_method_id}
DELETE /v1/account/payment-methods/{payment_method_id}
POST   /v1/account/payment-methods/{payment_method_id}/api-keys
POST   /v1/account/payment-methods/{payment_method_id}/api-keys/{api_key_id}/disable

Crear un método

POST /v1/account/payment-methods
Authorization: Bearer <jwt>
Content-Type: application/json

Campos requeridos: connector_definition_version_id, name, credentials.

{
  "connector_definition_version_id": "019f70b0-2222-7bbb-b222-000000000002",
  "name": "Getnet caja principal",
  "credentials": {
    "client_id": "sandbox-client-id",
    "client_secret": "sandbox-client-secret"
  },
  "configuration": {
    "terminal_id": "T-001"
  },
  "display_configuration": {
    "terminal_name": "Caja 1"
  },
  "capabilities": ["payments", "refunds", "cancellations"]
}

Reglas:

connector_definition_version_id es el identificador de la versión publicada que te entrega PagoFast;
el ambiente (test / live) lo define el deploy (PAYMENTS_ENVIRONMENT); no se envía en el body;
credentials y configuration deben cumplir el schema de esa versión;
capabilities opcionales deben estar soportadas;
display_configuration no puede contener secretos;
user_id solo lo usa un admin para crear el método en nombre de otro owner.

La API acepta secretos únicamente en escrituras autorizadas. Nunca los devuelve en create, list, detail ni errores.

Respuesta

{
  "data": {
    "id": "019f704f-89d7-7e83-b3e1-f07c33801024",
    "user_id": "019f70c0-3333-7ccc-b333-000000000003",
    "connector_definition_version_id": "019f70b0-2222-7bbb-b222-000000000002",
    "name": "Getnet caja principal",
    "type": "pos",
    "provider": "getnet",
    "environment": "live",
    "status": "active",
    "capabilities": ["payments", "refunds", "cancellations"],
    "display_configuration": { "terminal_name": "Caja 1" },
    "enabled": true,
    "created_at": "2026-07-17T16:00:00.000Z",
    "updated_at": "2026-07-17T16:00:00.000Z"
  }
}

Listar y obtener

GET /v1/account/payment-methods?limit=50&offset=0
Authorization: Bearer <jwt>

Query params opcionales: limit (1–100, default 50), offset (default 0), user_id (solo admin).

GET /v1/account/payment-methods/019f704f-89d7-7e83-b3e1-f07c33801024
Authorization: Bearer <jwt>

Las respuestas usan la misma representación del ejemplo anterior. credentials y la configuración sensible se omiten siempre. Un usuario client solo ve métodos propios.

Actualizar

PATCH /v1/account/payment-methods/019f704f-89d7-7e83-b3e1-f07c33801024
Authorization: Bearer <jwt>
Content-Type: application/json

Campos opcionales: name, credentials, configuration, display_configuration, capabilities, enabled.

{
  "name": "Getnet caja 1",
  "enabled": false,
  "display_configuration": {
    "terminal_name": "Caja cerrada temporalmente"
  }
}

enabled: false deja el método en status inactive e impide nuevas operaciones, sin borrar el historial. Si rotás credentials, enviá el objeto exigido por el schema; la respuesta seguirá sin exponerlo.

Borrar

DELETE /v1/account/payment-methods/019f704f-89d7-7e83-b3e1-f07c33801024
Authorization: Bearer <jwt>

Respuesta 204. Soft delete: marca el método como borrado, limpia secretos/configuración sensible y deshabilita links a API keys. Los pagos históricos conservan la referencia. Es idempotente.

Habilitar en una API key

POST /v1/account/payment-methods/019f704f-89d7-7e83-b3e1-f07c33801024/api-keys
Authorization: Bearer <jwt>
Content-Type: application/json

{
  "api_key_id": "019f70d0-4444-7ddd-b444-000000000004"
}

Response

{
  "data": {
    "api_key_id": "019f70d0-4444-7ddd-b444-000000000004",
    "payment_method_id": "019f704f-89d7-7e83-b3e1-f07c33801024",
    "enabled": true,
    "created_at": "2026-07-17T16:05:00.000Z"
  }
}

Método y key deben pertenecer al mismo owner, compartir ambiente y estar activos. Habilitar un método no agrega scopes a la key.

Deshabilitar para una API key

POST /v1/account/payment-methods/019f704f-89d7-7e83-b3e1-f07c33801024/api-keys/019f70d0-4444-7ddd-b444-000000000004/disable
Authorization: Bearer <jwt>

La relación queda deshabilitada para nuevas operaciones de esa key. Otras API keys vinculadas al mismo método no cambian.

Errores frecuentes

Código	HTTP	Causa habitual
`invalid_request`	400	Body incorrecto o capability inválida.
`payment_method_not_found`	404	Método inexistente, ajeno o no visible.
`insufficient_role`	403	El usuario no tiene rol suficiente.

Recorrido de prueba

Crear el método con el identificador y las credenciales de sandbox que te entregó PagoFast.
Crear una API key con los scopes necesarios (vía management / OpenAPI).
Habilitar el método para esa key.
Confirmar que aparece en GET /v1/payment-methods usando la API key.
Crear un pago de prueba y verificar el resultado.