Parceiros no Pix JD

Restrinja a credencial de um parceiro no Pix JD aos participantes diretos ou aos participantes indiretos para os quais ele atua, nomeie esse participante em toda requisição, leia as recusas que ele recebe e dê à JD as rotas de canal dela como parceiro.

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.

Um parceiro do Pix JD precisa de escopo, a menos que tenha apenas as permissões de canal da JD. Um parceiro com outras permissões no Pix JD e sem restrição no Pix JD é recusado. Veja A JD como parceiro.

​

Passo a passo

---

1. 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 letras maiúsculas ou 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, a decodificação de QR 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.

   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 não fica restrito a esse participante indireto. Use indirectId.

2. 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, mais as permissões de canal da JD. 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, criar ou alterar QR codes dinâmicos, e decodificar QR codes. 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.
   • As ações do operador atuam sobre o tenant inteiro, e nunca são dadas a um parceiro. Dê as permissões de canal da JD apenas em uma entrada de permissões própria. Veja A JD como parceiro.
3. 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.

4. 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
   Decodificar um QR code: POST /v1/qrcodes/decode, POST /v1/qrcodes/decode/url	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.

   Uma requisição por um participante indireto declara o cliente e não nomeia nenhuma conta: payer em um pagamento, X-Payer-Document na consulta de chave e na decodificação de QR, e recipient em um QR code dinâmico. Uma devolução não precisa de conta. Vinda de um parceiro, uma conta nessas requisições (accountId, ou account_id na consulta) responde 400 com PIX-0061. Veja Declare o cliente do participante indireto.

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

​

A JD como parceiro

---

A JD pode chamar as rotas que ela chama no Pix JD como parceiro do seu tenant. Essas rotas recebem Pix de entrada, devoluções, validações de conta e as mensagens do Pix Automático. Dê ao parceiro estas nove permissões no produto plugin-br-pix-jd, em uma entrada de permissões que não tem mais nada:

Recurso	Ações
cash-ins	post
reversals	post
validates	post
validates-async	post
authorizations-inbound	post
schedules-inbound	post
settlements-inbound	post, delete
events	post

Essa entrada não precisa de escopo, e vale para todos os participantes do seu tenant. O Access Manager a aceita apenas quando o Pix JD publica a declaração de permissões dele. Crie o parceiro e a aplicação dele com a API do Identity. Depois, dê à JD o client ID e o client secret.

​

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 não é mantido sob o participante que a requisição nomeia. Nada é lido nem alterado, e a resposta não diz quem tem o registro.	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.