Parceiros no Pix JD

Um parceiro pode chamar o Pix JD com uma credencial própria. Você restringe essa credencial aos participantes diretos (ISPBs) ou aos participantes indiretos para os quais ele atua. Isso é necessário quando um deploy do Pix JD atende vários participantes, e o sistema de cada cliente tem que ver e movimentar só o próprio Pix. Todo parceiro do Pix JD precisa de escopo. Um parceiro com permissões no Pix JD e sem restrição no Pix JD é recusado.

Passo a passo

Escolha para quem o parceiro atua

O Pix JD tem duas restrições:

Restrição	Campo na API	Valores
Participante direto do Pix (ISPB)	`participantId`	O ISPB de cada participante direto para o qual o parceiro atua, 8 dígitos.
Participante indireto	`indirectId`	O `indirectId` de cada participante indireto para o qual o parceiro atua, como o Pix JD o devolveu quando você cadastrou o participante indireto.

Use-as de um destes dois jeitos:

O parceiro atua para	Dê a ele	O que ele alcança
Um participante direto, com todos os participantes indiretos dele	Só `participantId`, com o ISPB do participante direto	Todo o Pix desse participante: chaves, reivindicações, limites, pagamentos, devoluções, QR codes, Pix Automático, MED, marcações de fraude e os participantes indiretos dele.
Um participante indireto	Só `indirectId`, com esse participante indireto	Pagamentos e as leituras deles, devoluções, QR codes dinâmicos e a lista de QR codes, infrações, solicitações de devolução e recuperações do MED, a consulta de chave, e o cadastro e as transações do próprio participante indireto. Nada do participante direto, e nada dos outros participantes indiretos.

Para restringir um parceiro a um participante indireto, dê a ele só indirectId. Não adicione o ISPB do participante direto que liquida para ele. Com os dois, o parceiro também lê os dados próprios do participante direto: as chaves, reivindicações, limites, marcações de fraude e registros de Pix Automático dele.

Um parceiro restrito só por ISPB é o parceiro do participante direto inteiro. Ele alcança todos os participantes indiretos desse participante direto.Não coloque o ISPB de um participante indireto em participantId. O Access Manager aceita, mas o parceiro passa a ser recusado em quase todas as rotas, e ele não fica restrito a esse participante indireto. Use indirectId.

Dê ao parceiro as permissões e o escopo

Crie o parceiro, ou altere-o, no Console ou com a API do Identity. O identificador do produto é plugin-br-pix-jd. As duas restrições aceitam vários valores.

Adicione pelo menos uma restrição para o Pix JD. Sem ela, o Access Manager recusa o parceiro com 400 e IDE-1060.
Marque os recursos e as ações. O máximo que você pode dar é o que o papel plugin-br-pix-jd-editor-role tem no seu tenant. Acima disso, o Access Manager recusa com IDE-1043.

O Access Manager confere cada escrita que você dá contra o escopo, e recusa com 400 e IDE-1056 uma escrita mais ampla que o escopo do parceiro. O Console marca a linha como Fora do escopo:

Um parceiro com um participante indireto no escopo só pode receber estas escritas: criar pagamentos, criar devoluções, e criar ou alterar QR codes dinâmicos. Toda outra escrita atua sobre o participante direto inteiro: cadastrar chaves, reivindicações, limites, QR codes estáticos, Pix Automático, marcações de fraude, as ações sobre registros do MED, e cadastrar ou alterar participantes indiretos.
Escritas que atuam sobre o tenant inteiro, como as ações do operador e os callbacks do arranjo, nunca são dadas a um parceiro.

Crie a aplicação dele no Pix JD

Crie a aplicação do parceiro com o produto plugin-br-pix-jd. Veja Criar as aplicações do parceiro no guia da API, ou no Console. Envie o client ID e o client secret ao parceiro por um canal seguro.

Nomeie o participante em toda requisição

Toda requisição nomeia para quem o parceiro atua, num campo que o Pix JD já tem. O valor tem que estar dentro do escopo do parceiro. Uma requisição que não nomeia ninguém é recusada.Um parceiro de um participante direto nomeia o ISPB dele:

Rotas	Escritas	Leituras e rotas por ID
Pagamentos e devoluções: `/v1/transactions`, `/v1/refunds`	Corpo `payerIspb`	Query `ispb`
Limites: `/v1/limits`	Corpo `payerIspb`	Query `payer_ispb`
Chaves e reivindicações: `/v1/entries`, `/v1/claims`, `/v1/account-closures`, `/v1/holder-removals`	Corpo `ispb`, também no `DELETE`	Query `ispb`
QR codes: `/v1/qrcodes`	Corpo `ispb`	Query `ispb`
Pix Automático: `/v1/pix-automatico`	Corpo `recipient.ispb` para criar uma autorização ou um agendamento, `recurrence.recipient.ispb` para criar um QR code composto, `payer.ispb` para confirmar uma autorização, `requesterIspb` para cancelar um agendamento, e `ispb` para decodificar ou validar	Query `ispb`, também para responder, cancelar ou alterar o valor máximo de uma autorização
MED: `/v1/med`	Corpo `ispb` para criar uma recuperação, uma solicitação de devolução ou uma marcação de fraude, e para cancelar uma marcação de fraude. Query `ispb` para as ações sobre uma infração, uma solicitação de devolução ou uma recuperação	Query `ispb`. Para listar infrações, `creatorIspb` ou `counterpartIspb`. Para listar solicitações de devolução, `requesterIspb` ou `contestedIspb`
Participantes indiretos: `/v1/indirects`	Corpo `directIspb` para cadastrar um, query `directIspb` para alterar um	Query `directIspb`

Para pagar por um dos participantes indiretos dele, ele envia o próprio ISPB em payerIspb e o participante indireto em indirectId.Um parceiro de um participante indireto nomeia o indirectId dele:

Rotas	Onde
Criar um pagamento ou uma devolução: `POST /v1/transactions`, `POST /v1/refunds`	Corpo `indirectId`. `payerIspb` não é necessário.
Criar ou alterar um QR code dinâmico: `/v1/qrcodes/dynamic`	Corpo `indirectId`
Ler pagamentos: `GET /v1/transactions`, `GET /v1/transactions/{transactionId}`	Query `indirectId`
Listar QR codes, consultar uma chave: `GET /v1/qrcodes/list`, `GET /v1/entries/{entryId}/lookup`	Query `indirectId`
Infrações, solicitações de devolução e recuperações do MED: `/v1/med`	Query `indirectId`
O próprio cadastro e as transações dele: `/v1/indirects/{indirectId}`	O path

Um campo de corpo que aceita um participante aceita um valor. Não envie uma lista nele.

Confirme que funciona

Use a credencial do parceiro. Leia um dos pagamentos do próprio parceiro, nomeando o próprio ISPB. A resposta é 200:

PIX_JD_BASE_URL="https://pix.<your-domain>"            # your Pix JD base URL
PIX_JD_BEARER_TOKEN="paste-the-partner-access-token-here"
OWN_ISPB="12345678"                                    # an ISPB in the partner's scope
TRANSACTION_ID="paste-a-transaction-id-here"

curl -s -o /dev/null -w '%{http_code}\n' \
  -H "Authorization: Bearer ${PIX_JD_BEARER_TOKEN}" \
  "${PIX_JD_BASE_URL}/v1/transactions/${TRANSACTION_ID}?ispb=${OWN_ISPB}"

Para um parceiro de um participante indireto, envie indirectId no lugar de ispb, com o valor dele.Envie a mesma requisição com um ISPB fora do escopo do parceiro. A resposta é 403 com PIX-0005. Envie-a com o ID de um pagamento de outro participante. A resposta é 404 com PIX-0147.

Rotas que nenhum parceiro alcança

Um parceiro com escopo no Pix JD é recusado com 403 nestas rotas:

Os diretórios que não nomeiam participante: GET /v1/banks, GET /v1/banks/participants e GET /v1/refunds/reasons.
As alterações de QR code composto: PUT /v1/pix-automatico/composite/cobv/{id}, PUT /v1/pix-automatico/composite/dynamic/{id} e PUT /v1/pix-automatico/composite/recurrence/{id}.

Use uma aplicação da sua própria instituição para essas rotas.

Se algo falhar

Código	Status	O que significa	O que fazer
`PIX-0005`	403	A requisição nomeia um participante fora do escopo do parceiro, não nomeia nenhum, ou está fora das permissões do parceiro. Uma lista numa query com um valor fora do escopo também é recusada.	Nomeie o participante no campo dessa rota, com um valor do escopo do parceiro. Confira também se o parceiro tem a permissão dessa rota.
`PIX-0002`	400	Um campo de corpo recebeu vários participantes, ou dois campos da mesma requisição nomeiam participantes diferentes.	Envie um participante, o mesmo em todos os campos.
`PIX-0147`	404	O registro que a requisição endereça pertence a outro participante. Nada é lido nem alterado, e a resposta não diz quem tem o registro.	Nomeie o participante sob o qual o registro foi criado, ou confira o ID.
`PIX-0061`	400	Numa consulta por ID do Pix Automático (uma autorização, um agendamento ou os cancelamentos deles), o registro pertence a outro participante.	Nomeie o participante sob o qual a autorização ou o agendamento foi criado.
`PIX-0128`	422	O ISPB está no escopo do parceiro, mas a sua instituição não o opera no Pix JD.	Confira o ISPB.
`PIX-0004`	401	O parceiro está suspenso, ou a requisição está fora da janela de validade dele.	Reative o parceiro, ou altere a janela de validade dele.

PIX-0005 não diz se foram as permissões ou o escopo que recusaram a requisição. Isso é proposital: um parceiro não consegue usar uma recusa para descobrir quais participantes existem fora do escopo dele. Para todos os outros códigos, veja a lista de erros do Pix JD. Para as recusas ao criar ou alterar um parceiro, veja os códigos de erro no guia da API.

Introdução

Access Manager

Console

Streaming Hub

Multi-tenancy

Observabilidade

Narya

Lifecycle Management

Licenciamento

Parceiros no Pix JD

Passo a passo

Rotas que nenhum parceiro alcança

Se algo falhar

​Passo a passo

​Rotas que nenhum parceiro alcança

​Se algo falhar

Passo a passo

Rotas que nenhum parceiro alcança

Se algo falhar