Integrações

Associe adquirentes de pagamento a comerciantes para habilitar o processamento de transações. As integrações conectam comerciantes com adquirentes (como PagSeguro, Cielo, Rede, Stone, Getnet, Adiq) — 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

Parâmetros

Parâmetro	Tipo	Obrigatório	Descrição
merchantId	string	✓	Identificador do comerciante
providerId	string	✓	Identificador do provedor (de GET /v1/providers)
providerName	string	✓	Nome do provedor (pagseguro, cielo, rede, stone, getnet, adiq)
authenticationData	object	✓	Credenciais específicas do provedor (veja abaixo)
status	string	—	Status da integração (ex. connected)
additionalData	object	—	Configuração adicional específica do provedor

Dados de Autenticação

A estrutura de authenticationData varia por provedor. Para provedores EMV de cartão presente (ex. PagSeguro):

Campo	Tipo	Obrigatório	Descrição
merchantIdentifier	string	✓	Código de comerciante do provedor (MID)
terminalIdentifier	string	✓	Código de terminal do provedor (TID)

Request

curl -X POST https://yby-dev.positivolabs.com.br/v1/credentials \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
        "merchantId": "d6uo5nc42nrc73gv867g",
        "providerId": "d1niaaopa579sdaa4tug",
        "providerName": "pagseguro",
        "status": "connected",
        "authenticationData": {
          "merchantIdentifier": "T5F6FEF0937427C",
          "terminalIdentifier": "00000001"
        }
      }'

Resposta

{
  "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": true,
  "enabled": true
}

Campos da Resposta

Campo	Tipo	Descrição
id	string	Identificador único da credencial (XID, 20 caracteres)
merchantId	string	Identificador do comerciante
providerId	string	Identificador do provedor/adquirente
subacquirerId	string	ID da organização subadquirente
authenticationData	object	Credenciais específicas do provedor
testMode	boolean	Se a credencial está em modo teste
enabled	boolean	Se a credencial está ativa
createdAt	string	Timestamp de criação (ISO 8601)
updatedAt	string	Timestamp da última atualização (ISO 8601)