> ## 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.

# Chaves de API da subconta

> Devolve a chave pública e a chave secreta de uma subconta ativa, para criar cobranças em nome do vendedor.

Esta rota devolve as chaves de API (pública e secreta) de uma subconta (SubMerchant). Com a chave secreta da subconta, a sua plataforma cria cobranças **em nome do vendedor**: a venda fica registrada como originada pela subconta, e é a partir dela que o split distribui os valores.

## Quando usar

| Situação | Como usar esta rota |
| - | - |
| Subconta acabou de ser aprovada (`active`) | Busque as chaves e guarde a secreta no seu cofre de segredos |
| Criar cobranças vinculadas ao vendedor | Use a chave secreta da subconta em [`POST /v1/charges`](https://docs.fastpaybrasil.com/referencia/cobrancas/criar) |
| Apple Pay ou 3D Secure no checkout do vendedor | Use a chave pública (`pk_`) da subconta no front-end |
| Cobranças em nome da própria conta master | Use a chave da conta master; esta rota não é necessária |

## Antes de chamar

* Use as chaves para cobrar só depois que a subconta estiver **ativa** (`active`): antes da aprovação ela não está apta a transacionar. Confira com [Consultar subconta](https://docs.fastpaybrasil.com/referencia/fast-connect/consultar-subconta.md). Se a API não encontrar chaves para a subconta, a rota devolve `404`.
* Autentique com a chave secreta (`sk_`) da **conta master** ([Credenciais e ambientes](https://docs.fastpaybrasil.com/primeiros-passos/credenciais-e-ambientes.md)).

## Parâmetros de caminho

**id** `string` *required*

Identificador único da subconta. Ex.: `36OO3bcGjhPjjF3tzrqOGcmQuKo`.

## Respostas

**publicKey** `string`

Chave pública da subconta. Pode ser usada no navegador, nas rotas que pedem a chave pública. Ex.: `pk_2vorkDcXyvzifL63YX09S9VqcnI`.

**secretKey** `string`

Chave secreta da subconta. Só pode ser usada no servidor. Ex.: `sk_2vorkDcXyvzifL63YX09S9VqcnI`.

Em **modo de teste**, as chaves têm prefixo `sk_test_` e `pk_test_`.

| HTTP | Significado | Corpo |
| - | - | - |
| `200` | Chaves devolvidas | `publicKey`, `secretKey` |
| `401` | Chave ausente ou inválida | `{"statusCode": 401, "message": "Unauthorized"}` |
| `403` | Connect não habilitado na conta master | `{"statusCode": 403, "message": "Fast Connect not enabled."}` |
| `404` | Subconta não encontrada ou sem chaves de API | `{"statusCode": 404, "message": "API keys not found for this submerchant."}` |

> [!WARNING]
>
> A chave **secreta** da subconta dá acesso às cobranças e aos dados dela. Guarde-a só no servidor, em um cofre de segredos, e nunca a envie ao navegador, ao aplicativo ou ao próprio vendedor por e-mail ou chat. A chave **pública** (`pk_`) é a que pode ir para o front-end.

> [!NOTE]
>
> **Para o negócio:** para que cada venda fique ligada ao vendedor certo, a cobrança precisa ser criada com a chave secreta **da subconta que vendeu**. Com a chave da conta master, a venda fica registrada na própria conta master. As regras de quem pode enviar valor para quem estão em [Split de pagamentos](https://docs.fastpaybrasil.com/guias/fast-connect/split.md).

> [!TIP]
>
> **Para o desenvolvedor:** guarde a relação entre o `id` da subconta e a referência da chave no seu cofre. Na hora de cobrar, escolha a chave pelo vendedor do pedido. Se receber `404`, confira primeiro o `id` e o status da subconta.

## Erros comuns

| Sintoma | Causa | Como resolver |
| - | - | - |
| `404` "API keys not found for this submerchant." | A API não encontrou chaves para a subconta | Confira o `id` e o status da subconta. Se persistir, fale com o suporte |
| `404` com subconta ativa | `id` de outra conta master, inexistente ou de outro ambiente | Use o `id` correto e a chave da conta master no mesmo ambiente |
| Cobrança registrada na conta master | Cobrança criada com a chave da conta master | Crie a cobrança com a chave secreta da subconta |

```http REST (JSON) theme={null}
GET /v1/submerchants/36OO3bcGjhPjjF3tzrqOGcmQuKo/api-keys HTTP/1.1
Host: api-global.fastpaybrasil.com
Authorization: Basic <base64 de "SUA_CHAVE_SECRETA:">
```

```bash cURL theme={null}
curl "https://api-global.fastpaybrasil.com/v1/submerchants/36OO3bcGjhPjjF3tzrqOGcmQuKo/api-keys" \
  -u "$FINVIA_API_KEY:"
```

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

const response = await fetch(`https://api-global.fastpaybrasil.com/v1/submerchants/${id}/api-keys`, {
  headers: { Authorization: `Basic ${credentials}` },
});

if (response.status === 404) {
  // chaves não encontradas: confira o id e o status da subconta
} else {
  const { publicKey, secretKey } = await response.json();
  // grave secretKey no seu cofre de segredos, nunca em log
}
```

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

import requests

response = requests.request(
    "GET",
    "https://api-global.fastpaybrasil.com/v1/submerchants/36OO3bcGjhPjjF3tzrqOGcmQuKo/api-keys",
    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/submerchants/36OO3bcGjhPjjF3tzrqOGcmQuKo/api-keys');

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/submerchants/36OO3bcGjhPjjF3tzrqOGcmQuKo/api-keys"))
            .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/submerchants/36OO3bcGjhPjjF3tzrqOGcmQuKo/api-keys");

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/submerchants/36OO3bcGjhPjjF3tzrqOGcmQuKo/api-keys", 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/submerchants/36OO3bcGjhPjjF3tzrqOGcmQuKo/api-keys")
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}
{
  "publicKey": "pk_2vorkDcXyvzifL63YX09S9VqcnI",
  "secretKey": "sk_2vorkDcXyvzifL63YX09S9VqcnI"
}
```

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

```json 403 theme={null}
{ "statusCode": 403, "message": "Fast Connect not enabled." }
```

```json 404 theme={null}
{ "statusCode": 404, "message": "API keys not found for this submerchant." }
```

## Veja também

> [card] [Split de pagamentos](https://docs.fastpaybrasil.com/guias/fast-connect/split.md)
>
> Divisão de valores entre contas do grupo.

> [card] [Criar cobrança](https://docs.fastpaybrasil.com/referencia/cobrancas/criar.md)
>
> Cobrança com a chave da subconta.

> [card] [Consultar subconta](https://docs.fastpaybrasil.com/referencia/fast-connect/consultar-subconta.md)
>
> Confirme que a subconta está ativa.

> [card] [Visão geral do Connect](https://docs.fastpaybrasil.com/guias/fast-connect/visao-geral.md)
>
> Conta master, subcontas e chaves.


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