Pular para o conteúdo principal

Integrações

Associe adquirentes de pagamento a comerciantes para habilitar o processamento de transações. As integrações conectam comerciantes com adquirentes, bancos, entre outros — cada comerciante pode ter múltiplas integrações.

dica

Antes de criar uma credencial, liste os provedores disponíveis para obter o providerId necessário.

Criar Credencial​

POST/v1/credentials
Request
{
  "merchantId": "d6uo5nc42nrc73gv867g",
  "providerId": "d1niaaopa579sdaa4tug",
  "authenticationData": {
    "merchantIdentifier": "T5F6FEF0937427C",
    "terminalIdentifier": "00000001"
  }
}
Response
{
  "id": "d6uoabc42nrc73gv8690",
  "createdAt": "2026-03-20T10:30:00Z",
  "updatedAt": "2026-03-20T10:30:00Z",
  "subacquirerId": "d59gpddc93gc73jvje0g",
  "merchantId": "d6uo5nc42nrc73gv867g",
  "providerId": "d1niaaopa579sdaa4tug",
  "authenticationData": {
    "merchantIdentifier": "T5F6FEF0937427C",
    "terminalIdentifier": "00000001"
  },
  "testMode": false,
  "enabled": true
}

Parâmetros​

ParâmetroTipoObrigatórioDescrição
merchantIdstring✓Identificador do comerciante
providerIdstring✓Identificador (XID) do provedor, obtido em Listar Provedores
authenticationDataobject✓Credenciais específicas do provedor (veja abaixo)
additionalDataobject—Configuração adicional específica do provedor (ex.: schemes para roteamento, voucherEnabled para voucher, pixKey quando o banco exigir)
enabledboolean—Opcional no corpo; default true
O BTG aparece duas vezes na lista de provedores

O BTG está cadastrado como banco (PIX) e como adquirente de cartão. Para a credencial de cartão com roteamento, use o providerId do BTG no canal card_present (type = payment_processor). Veja Listar Provedores.

Dados de Autenticação​

A estrutura de authenticationData varia por provedor.

Adquirente — EMV (ex. PagSeguro)​

CampoTipoObrigatórioDescrição
merchantIdentifierstring✓Código de comerciante do provedor (MID)
terminalIdentifierstring✓Código de terminal do provedor (TID)

Adquirente — EMV com roteamento (BTG)​

CampoTipoObrigatórioDescrição
merchantIdentifierstring✓Código de comerciante no BTG (MID)
terminalIdentifierstring—Código de terminal (TID). Se omitido, a plataforma gera um por terminal na ativação

Banco — PIX (ex. BTG)​

CampoTipoObrigatórioDescrição
clientIdstring—Client ID OAuth do EC junto ao banco (quando exigido por EC)
clientSecretstring—Client Secret OAuth do EC junto ao banco (quando exigido por EC)

Dados Adicionais — Roteamento​

Declara quais arranjos de pagamento esta credencial atende. Em adquirentes de cartão presente (context = card_present) são as bandeiras; em bancos, pix. O roteamento entre adquirentes de cartão está disponível hoje para o BTG.

CampoTipoObrigatórioDescrição
schemesstring[]✓Arranjos atendidos por esta credencial. Adquirente de cartão: visa, master, elo, amex. Banco: pix. Sem repetição

A requisição retorna 400 quando schemes contém um valor fora da lista aceita para o tipo do provedor ou um valor repetido.

Como funciona o roteamento
  • Uma bandeira listada em schemes é processada pelo adquirente da credencial que a listou.
  • Uma bandeira não listada em nenhuma credencial vai para o adquirente cuja credencial não tem regra de roteamento (ex.: PagSeguro).
  • Para migrar o volume de forma gradual, amplie a lista schemes da credencial do novo adquirente.
  • A mudança passa a valer no terminal na próxima carga de tabelas de inicialização (logon diário, atualização manual ou quando o adquirente sinaliza).
  • Transações já autorizadas continuam sendo confirmadas ou canceladas no adquirente que as autorizou.
  • Em bancos, schemes: ["pix"] indica que a credencial atende PIX.

Dados Adicionais — Voucher​

Habilita transações de voucher para o comerciante na credencial do adquirente de cartão presente.

CampoTipoObrigatórioDescrição
voucherEnabledboolean—Habilita transações de voucher para o comerciante. Default false (ausente = voucher desligado)

Só é aceito em credenciais de adquirente de cartão presente (type = payment_processor, context = card_present). A requisição retorna 400 no campo additionalData.voucherEnabled quando o valor não é booleano (ex.: "true" ou 1) ou quando o campo é enviado em credencial de banco.

Como funciona o voucher
  • O voucher fica habilitado para o comerciante se qualquer credencial de cartão presente ativa (enabled: true) dele tiver voucherEnabled: true.
  • Para desligar, envie voucherEnabled: false ou remova a chave da credencial.
  • Pode ser enviado sozinho ou junto de schemes no mesmo additionalData.
  • A mudança passa a valer no terminal na próxima carga de tabelas de inicialização (logon diário, atualização manual ou quando o adquirente sinaliza).
  • A chave é sensível a maiúsculas: use exatamente voucherEnabled. Outra grafia (ex.: VoucherEnabled) é ignorada e não habilita o voucher.
  • Para habilitar ou desabilitar em uma credencial existente, veja Atualizar Credencial.

Dados Adicionais — PIX​

CampoTipoObrigatórioDescrição
pixKeystring—Chave PIX do estabelecimento (CPF, CNPJ, e-mail, telefone ou chave aleatória). Exigida apenas quando o banco solicitar; não é necessária para o BTG

Campos da Resposta​

CampoTipoDescrição
idstringIdentificador único da credencial (XID, 20 caracteres)
merchantIdstringIdentificador do comerciante
providerIdstringIdentificador do provedor/adquirente
subacquirerIdstringID da organização subadquirente
authenticationDataobjectCredenciais específicas do provedor (mesmos campos enviados no request)
additionalDataobjectConfiguração adicional específica do provedor; presente quando aplicável (ex.: schemes para roteamento, voucherEnabled para voucher, pixKey quando o banco exigir)
testModebooleanSe a credencial opera em modo de teste
enabledbooleanSe a credencial está ativa
createdAtstringTimestamp de criação (ISO 8601)
updatedAtstringTimestamp da última atualização (ISO 8601)