Provedores de pagamento

Este é o catálogo somente leitura de provedores de pagamento que a Tokeflow sabe orquestrar. Cada entrada descreve o que um provedor suporta — métodos de pagamento, países, moedas e capacidades como tokenização ou 3-D Secure — para que você possa decidir quais conectar para um determinado merchant.

Um provedor só se torna utilizável quando um merchant tem um conector para ele, contendo as credenciais desse merchant. O catálogo informa o que é possível; Conectores informa o que está de fato configurado. A Tokeflow orquestra esses provedores — ela não processa nem liquida fundos por conta própria.

O objeto de provedor de pagamento

Uma entrada no catálogo de provedores.

Provedores suportados

O catálogo retornado por GET /payment-providers é a fonte da verdade sobre o que a sua organização pode conectar hoje, e ele é habilitado por organização. A lista pública de provedores suportados não é publicada nesta referência: ela muda conforme novos conectores entram em produção, e nem todo provedor está disponível para toda organização ou mercado. Para saber se um provedor, país ou moeda específico é suportado — ou para solicitá-lo — entre em contato com a equipe da Tokeflow, e ele será habilitado para a sua organização quando disponível.

Duas coisas a conferir no catálogo antes de construir sobre um provedor:

• Cobranças com credencial armazenada. O fluxo em um clique precisa de um provedor que consiga cobrar um cartão salvo depois. Nem todo provedor consegue; quando a credencial do instrumento está em um conector cujo provedor não consegue, uma cobrança credential_on_file é recusada com 400. Pergunte à equipe da Tokeflow quais dos seus provedores suportam isso.
• Dados do pagador exigidos. Alguns provedores exigem o IP do pagador (payer_ip, ou o IP da sessão do Bridge SDK do pagador) e um cliente completo — nome, documento fiscal, e-mail, telefone e um endereço de cobrança com CEP e número — em cobranças com cartão. Enviá-los em toda cobrança deixa o roteamento livre para escolher qualquer conector.

Endpoints

GET/api/v1/payment-providers

Liste todos os PSPs ativos disponíveis para conexão (slug, display_name, logo, supported_auth_methods).

Parâmetros de consulta

Exemplo de requisição

curl -G https://api.tokeflow.com/api/v1/payment-providers \
  -H "Authorization: Bearer sk_live_mer_…" \
  --data-urlencode "page=1" \
  --data-urlencode "limit=20"

Exemplo de resposta — 200

{
  "data": [
    {
      "id": "obj_1a2b3c4d",
      "slug": "provider_a",
      "display_name": "Provider A",
      "logo": "https://cdn.example.com/providers/provider_a.svg",
      "is_active": true,
      "supported_auth_methods": [
        "api_key",
        "oauth2"
      ],
      "default_supported_card_brands": ["visa", "mastercard", "amex"],
      "supported_currencies": null,
      "installment_config": { "credit_card": { "min": 1, "max": 12 } }
    }
  ],
  "meta": {
    "page": 1,
    "limit": 20,
    "total": 42,
    "total_pages": 3,
    "has_next": true,
    "has_prev": false
  }
}

GET/api/v1/payment-providers/:provider_id

Recupere os detalhes de um único PSP, incluindo os métodos de autenticação suportados e os sinalizadores de configuração OAuth.

Parâmetros de caminho

Exemplo de requisição

curl https://api.tokeflow.com/api/v1/payment-providers/123 \
  -H "Authorization: Bearer sk_live_mer_…"

Exemplo de resposta — 200

{
  "id": "obj_1a2b3c4d",
  "slug": "provider_a",
  "display_name": "Provider A",
  "logo": "https://cdn.example.com/providers/provider_a.svg",
  "is_active": true,
  "supported_auth_methods": [
    "api_key",
    "oauth2"
  ],
  "default_supported_card_brands": ["visa", "mastercard", "amex"],
  "supported_currencies": null,
  "installment_config": { "credit_card": { "min": 1, "max": 12 } },
  "oauth_authorization_url": "https://provider.example.com/oauth/authorize",
  "oauth_token_url": "https://provider.example.com/oauth/token",
  "oauth_scopes": "payments:write",
  "oauth_pkce_required": true
}

Erros

Os erros usam o envelope padrão. Os casos mais comuns aqui:

Consulte Erros para o catálogo completo.

Relacionados

• Conectores
• Perfis de roteamento
• Upsells e downsells em um clique
• Como a Tokeflow funciona