> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fastpaybrasil.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Listar meios de pagamento

> Mostra quais formas de pagamento estão habilitadas para a sua conta, com países e moedas aceitos em cada uma.

Esta rota responde a uma pergunta direta: **quais formas de pagamento esta conta pode oferecer?** Para cada uma, ela informa os países onde funciona e as moedas aceitas. Use essa lista para montar as opções do seu checkout. A Finvia oferece cartão de crédito (inclusive cartão salvo e Apple Pay) e Pix.

Ela também é a chamada mais simples para validar uma chave de API: uma resposta `200` confirma que a autenticação está correta.

## Quando usar

| Situação | Como usar esta rota |
| - | - |
| Montar as opções do checkout | Liste e mostre só os meios retornados |
| Mostrar só o que aceita a moeda do carrinho | Filtre por `currency`, por exemplo `BRL` |
| Validar a chave de API logo depois de gerar | Chame sem filtros. `200` significa autenticação correta |
| Conferir o que uma subconta pode oferecer | Filtre por `merchantId` |
| Conferir o saldo da conta | Use [`GET /v1/wallets`](https://docs.fastpaybrasil.com/referencia/carteiras/listar) |

> [!NOTE]
>
> **Para o negócio:** as formas de pagamento disponíveis dependem da configuração da sua conta na Finvia. Se um meio que você espera não aparece na lista, fale com o seu contato comercial antes de pedir ao time técnico para integrar.

## Antes de chamar

* Tenha uma chave secreta (`sk_` ou `sk_test_`) e monte o cabeçalho Basic ([Credenciais e ambientes](https://docs.fastpaybrasil.com/primeiros-passos/credenciais-e-ambientes.md)).

## Parâmetros de consulta

Nenhum parâmetro é obrigatório.

**merchantId** `string`

Filtra os meios de pagamento pelo ID do merchant. Ex.: `2vorkDcXyvzifL63YX09S9VqcnI`.

**currency** `string`

Filtra os meios de pagamento pela moeda (código ISO 4217). Ex.: `BRL`.

## Respostas

A resposta `200` é um **array** de meios de pagamento, sem paginação.

**id** `string`

Identificador único do meio de pagamento. Ex.: `2vorkDcXyvzifL63YX09S9VqcnI`.

**name** `string`

Nome técnico do meio de pagamento. Ex.: `pix`.

**countries** `string[]`

Países onde o meio está disponível (ISO 3166-1 alpha-3). Ex.: `["BRA"]`.

**currencies** `string[]`

Moedas aceitas pelo meio (ISO 4217). Ex.: `["BRL"]`.

**description** `string`

Nome para exibir na tela. Ex.: `Pix`.

> [!TIP]
>
> **Para o desenvolvedor:** use `description` como rótulo no checkout e `name` como chave no seu código. O contrato não garante que `name` seja igual ao `type` usado em `POST /v1/charges`. Confira os valores devolvidos na sua conta antes de mapear um para o outro. O exemplo desta página é ilustrativo.

| HTTP | Significado | Corpo |
| - | - | - |
| `200` | Lista obtida | Array de meios de pagamento |
| `401` | Credencial inválida | `{"statusCode": 401, "message": "Unauthorized"}` |
| `403` | Usuário dono da chave sem permissão para o recurso | `{ "message": "Acesso negado", "error": "Forbidden", "statusCode": 403 }` |

## Exemplos por caso de uso

> [tab] Validar a chave
>
> A primeira chamada depois de gerar a chave.
>
> ```bash theme={null}
> curl -X GET "https://api-global.fastpaybrasil.com/v1/payment-methods" \
>   -u "$FINVIA_API_KEY:"
> ```
>
> > [!TIP]
> >
> > Resposta `200` com um array (mesmo vazio) confirma que a chave e o cabeçalho estão corretos.

> [tab] Opções por moeda
>
> Mostra só os meios que aceitam a moeda do carrinho.
>
> ```javascript theme={null}
> const metodos = await listarMeios({ currency: 'BRL' });
> const opcoes = metodos.map((m) => ({ valor: m.name, rotulo: m.description }));
> ```

## Erros comuns

| Sintoma | Causa | Como resolver |
| - | - | - |
| `401` | Cabeçalho ausente, chave inválida ou Base64 sem os dois pontos no final | Decodifique o Base64 e confira se termina em `:` |
| `403` | A chave não tem permissão para o recurso. A chave herda as permissões do usuário que a gerou | Confira o perfil do usuário que gerou a chave ([Credenciais e ambientes](https://docs.fastpaybrasil.com/primeiros-passos/credenciais-e-ambientes.md)) |
| Um meio esperado não aparece | O meio não está habilitado para a conta ou para a moeda filtrada | Consulte sem filtros e fale com o seu contato comercial |

```http REST (JSON) theme={null}
GET /v1/payment-methods?currency=BRL HTTP/1.1
Host: api-global.fastpaybrasil.com
Authorization: Basic <base64 de "SUA_CHAVE_SECRETA:">
```

```bash cURL theme={null}
curl -X GET "https://api-global.fastpaybrasil.com/v1/payment-methods?currency=BRL" \
  -u "$FINVIA_API_KEY:"
```

```javascript Node.js theme={null}
const credentials = Buffer.from(`${process.env.FINVIA_API_KEY}:`).toString('base64');

const response = await fetch('https://api-global.fastpaybrasil.com/v1/payment-methods?currency=BRL', {
  headers: { Authorization: `Basic ${credentials}` },
});

const paymentMethods = await response.json();
```

```python Python theme={null}
import os

import requests

response = requests.request(
    "GET",
    "https://api-global.fastpaybrasil.com/v1/payment-methods?currency=BRL",
    auth=(os.environ["FINVIA_API_KEY"], ""),
    timeout=30,
)

print(response.status_code)
if response.content:
    print(response.json())
```

```php PHP theme={null}
<?php

$ch = curl_init('https://api-global.fastpaybrasil.com/v1/payment-methods?currency=BRL');

curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => 'GET',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_USERPWD => getenv('FINVIA_API_KEY') . ':',
]);

$body = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

echo $status, PHP_EOL;
print_r(json_decode($body, true));
```

```java Java theme={null}
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.util.Base64;

public class Exemplo {
    public static void main(String[] args) throws Exception {
        String credentials = Base64.getEncoder()
            .encodeToString((System.getenv("FINVIA_API_KEY") + ":").getBytes());

        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://api-global.fastpaybrasil.com/v1/payment-methods?currency=BRL"))
            .header("Authorization", "Basic " + credentials)
            .method("GET", HttpRequest.BodyPublishers.noBody())
            .build();

        HttpResponse<String> response = HttpClient.newHttpClient()
            .send(request, HttpResponse.BodyHandlers.ofString());

        System.out.println(response.statusCode());
        System.out.println(response.body());
    }
}
```

```csharp C# theme={null}
using System.Net.Http.Headers;
using System.Text;

var apiKey = Environment.GetEnvironmentVariable("FINVIA_API_KEY");
var credentials = Convert.ToBase64String(Encoding.UTF8.GetBytes($"{apiKey}:"));

using var client = new HttpClient();
client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Basic", credentials);

var request = new HttpRequestMessage(HttpMethod.Get, "https://api-global.fastpaybrasil.com/v1/payment-methods?currency=BRL");

var response = await client.SendAsync(request);
Console.WriteLine((int)response.StatusCode);
Console.WriteLine(await response.Content.ReadAsStringAsync());
```

```go Go theme={null}
package main

import (
	"fmt"
	"io"
	"net/http"
	"os"
)

func main() {
	req, err := http.NewRequest("GET", "https://api-global.fastpaybrasil.com/v1/payment-methods?currency=BRL", nil)
	if err != nil {
		panic(err)
	}
	req.SetBasicAuth(os.Getenv("FINVIA_API_KEY"), "")

	res, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()

	body, _ := io.ReadAll(res.Body)
	fmt.Println(res.StatusCode)
	fmt.Println(string(body))
}
```

```ruby Ruby theme={null}
require "net/http"
require "uri"

uri = URI("https://api-global.fastpaybrasil.com/v1/payment-methods?currency=BRL")
request = Net::HTTP::Get.new(uri)
request.basic_auth(ENV.fetch("FINVIA_API_KEY"), "")

response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
  http.request(request)
end

puts response.code
puts response.body
```

```json 200 theme={null}
[
  {
    "id": "2vorkDcXyvzifL63YX09S9VqcnI",
    "name": "pix",
    "countries": ["BRA"],
    "currencies": ["BRL"],
    "description": "Pix"
  }
]
```

```json 401 theme={null}
{
  "statusCode": 401,
  "message": "Unauthorized"
}
```

```json 403 theme={null}
{
  "message": "Acesso negado",
  "error": "Forbidden",
  "statusCode": 403
}
```

## Veja também

> [card] [Credenciais e ambientes](https://docs.fastpaybrasil.com/primeiros-passos/credenciais-e-ambientes.md)
>
> Gere a chave e faça a primeira chamada.

> [card] [Formas de pagamento](https://docs.fastpaybrasil.com/guias/cobrancas/visao-geral.md)
>
> Quando usar cada forma de pagamento.

> [card] [Saldos e meios de pagamento](https://docs.fastpaybrasil.com/guias/saldos-e-meios-de-pagamento.md)
>
> Guia de saldo, saque e meios de pagamento.

> [card] [Consultar saldos](https://docs.fastpaybrasil.com/referencia/carteiras/listar.md)
>
> Saldo por moeda.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.