01Resumo

A CredPay publicou uma API nova, documentada no portal GruPag (api2.grupag.com.br). Hoje falamos com a CredPay por oito integrações em dois serviços, com quatro formas de login. Esta RFC propõe:

• Um adaptador novo no phiz-microwd-channel, ao lado do antigo, com códigos de serviço próprios e autenticação por API Key.
• A troca do cliente CredPay no phiz-pay-card-vault pelo contrato novo de cartão.
• Virada controlada pela tabela route_cfg, que o operador já edita no painel interno. Cada operação muda de caminho com uma linha de configuração e volta da mesma forma, sem deploy.
• Cinco fases, começando pelo PIX, que é o fluxo mais simples, e deixando para o fim o 3DS, que muda também o front.

A RFC também lista o que a API nova não cobre: maquininha (TEF), extrato para conciliação, transferência bancária e listagens. Essas operações ficam na integração antiga até a CredPay responder às perguntas em aberto.

02Contexto: como funciona hoje

A CredPay atende cartão (checkout, cartão salvo, pré-autorização, 3DS), PIX por QR Code e a maquininha dos comerciantes. Nenhum serviço do app fala com ela diretamente: o pedido passa pela cadeia de serviços até o channel, que é o único que conhece a CredPay, junto com o cofre de cartões.

flowchart LR
  APP["phiz-flutter
app"] --> AS["microwd-appserver
API do app"]
  AS --> BA["microwd-backapply
escolhe a rota"]
  BA --> CH["microwd-channel
fala com os canais"]
  CH --> CP[("CredPay
4 APIs")]
  CH --> CV["pay-card-vault
cofre de cartões"]
  CV --> CP
  IF["phiz-inner-front
painel"] --> IN["phiz-inner"]
  IN --> DB[("route_cfg
road_info")]
  DB -. "lê a rota" .-> BA
  DB -. "lê a URL" .-> CH

Linhas tracejadas são leituras de configuração. O painel não participa do pagamento: define as regras antes e mostra o resultado depois.

Como uma operação chega à CredPay

1. O backapply procura em route_cfg a rota para o tipo de transação, a forma de pagamento e o BIN do cartão (RoadRouteServiceImpl.getRouteByTranPayAcct). A rota diz qual canal e qual código de serviço atendem.
2. O channel recebe o código (por exemplo B21, pagamento com cartão salvo) e executa o serviço Spring registrado com esse nome.
3. O serviço busca a URL base do canal em road_info e chama a CredPay.

03Integrações atuais

Levantamento no código do phiz-microwd-channel e do phiz-pay-card-vault.

04A API nova

A documentação fica no portal GruPag (exige login) e tem quatro partes: Acesso e API Key, APIs PIX, API Compra com Cartão e API de Simulação.

flowchart LR
  subgraph HOJE["Hoje"]
    direction TB
    A1["/AuthCredPay
checkout · TEF · cofre"]
    A2["/oauth/token
PIX"]
    A3["autenticacao/gerar-token
3DS"]
    A4["api-services /AuthCredPay
conciliação"]
  end
  subgraph NOVO["API GruPag"]
    K["Authorization: Bearer gpk_…
Cliente-Id: empresa"]
  end
  HOJE ==> NOVO

Quatro logins com token, cache e renovação viram uma chave fixa enviada em toda chamada.

Regras gerais

# Today: four different logins, each with its own token and renewal
POST {road_info.url}/AuthCredPay            # checkout, pre-auth, TEF, card-vault
POST {road_info.url}/oauth/token            # PIX and bank transfer
POST {road_info.url}autenticacao/gerar-token # 3DS (platform API)
POST https://api-services.credpay.com.br/AuthCredPay/   # reconciliation (hard-coded URL)

# New: one API Key (gpk_...) on every call, no login, no renewal
curl -X GET "https://api2-homolog.grupag.com.br/v1/pagamento/consulta/nit?nit=$NIT" \
  -H "Authorization: Bearer $GRUPAG_API_KEY" \
  -H "Cliente-Id: $CLIENTE_ID"   # same value on every call of the flow

05Objetivos e fora de escopo

Objetivos

• Levar cartão, cartão salvo, 3DS, pré-autorização e PIX para a API nova, sem perder nenhuma operação que hoje está ativa.
• Trocar os quatro logins e o CredPayAuthTask por uma API Key guardada no cofre de segredos.
• Virar e desvirar cada operação por configuração, por comerciante, sem deploy.
• Concentrar conversões de valor e de status num único adaptador.

Fora do escopo

• Usar a API de Simulação para mostrar parcelas e taxas no app. É uma melhoria possível, não um requisito da migração.
• TEF, conciliação e transferência bancária, enquanto não houver equivalente na API nova.
• Outros canais (Pinbank, Cronos, Afro).

06Mapeamento rota a rota

Cartão salvo e checkout

{
  "nomeDoCliente": "JOAO DA SILVA",
  "documento": "12345678901",
  "quantidadeDeParcelas": 1,
  "valorInicial": 150.0,
  "token": "TOKEN_DO_CARTAO",
  "numeroInterno": "PED-4711",
  "subDominioId": 1234,
  "lojaId": 1
}

{
  "merchantChargeId": "20260901010707410895669",
  "orderId": "PED-4711",
  "installments": "1",
  "authorizerId": "2",
  "amount": "15000",
  "typeTransaction": "C",
  "card": {
    "token": "crd_d6dc9c299d15…"
  }
}

Mesmo pagamento com cartão salvo, antes e depois. O valor passa de reais para centavos, e o número interno vira orderId.

Pré-autorização

Cartão com 3DS

PIX

Cofre de cartões

07Novo fluxo de cartão com 3DS

A maior mudança de fluxo está no 3DS. Hoje o backapply devolve uma URL pronta (certifyUrl, em CardCertifyServiceImpl) e o front só a abre. Na API nova, dois passos rodam no navegador do pagador, e o front precisa montar e enviar os formulários.

sequenceDiagram
  autonumber
  participant F as Front do pagador
  participant BA as backapply
  participant CH as channel
  participant G as API GruPag
  participant E as Banco emissor
  BA->>CH: iniciar 3DS do pedido
  CH->>G: POST /3ds/autenticacao
  G-->>CH: merchantChargeId e threeDsMethod
  CH-->>BA: dados do 3DS Method
  BA-->>F: dados para o navegador
  F->>E: 3DS Method em iframe invisível
  BA->>CH: autenticar com dados do navegador
  CH->>G: POST /3ds/configuracao
  G-->>CH: frictionless ou desafio
  F->>E: desafio com creq, se houver
  CH->>G: GET /3ds/consultar3DS
  G-->>CH: eci e CAVV
  CH->>G: POST /v1/pagamento com merchantChargeId
  G-->>CH: nit e status CONFIRMADO

O mesmo Cliente-Id precisa ir em todas as chamadas à API GruPag deste fluxo. Se ele faltar em uma, o pagamento responde "3DS não encontrado".

08Novo fluxo PIX

O PIX quase não muda de forma: gerar, consultar até pagar. O que entra de novo é a devolução com regra de prazo e a disputa.

sequenceDiagram
  autonumber
  participant CH as channel
  participant G as API GruPag
  participant P as Pagador
  CH->>G: POST /transacional/pix/qrcode
  G-->>CH: transactionId e copia-e-cola
  CH-->>P: QR Code
  P->>G: paga no banco
  loop até CONFIRMADO ou EXPIRADO
    CH->>G: GET /transacional/pix/consulta/{id}
    G-->>CH: status
  end

stateDiagram-v2
  [*] --> GERADO
  GERADO --> CONFIRMADO: pagamento
  GERADO --> EXPIRADO: venceu
  CONFIRMADO --> ESTORNANDO: devolução até 24 h
  ESTORNANDO --> ESTORNADO
  CONFIRMADO --> DISPUTA: devolução após 24 h
  DISPUTA --> CANCELANDO: admin aprova
  CANCELANDO --> CANCELADO
  DISPUTA --> PAGO: admin nega

Status de uma cobrança PIX na API nova. A disputa é decidida por um usuário Admin, o que pede uma tela no painel interno.

curl -X POST "https://api2-homolog.grupag.com.br/transacional/pix/qrcode" \
  -H "Authorization: Bearer $GRUPAG_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "amount": 15.00, "description": "Pedido PED-12345", "expirationSeconds": 3600 }'
# 200 → { "transactionId": "a1b2…", "status": "GERADO", "pixCopyAndPaste": "000201…", "destination": "TRANSACIONAL-PIX-SICREDI" }

09Lacunas

Estas operações não aparecem na documentação nova. Continuam na integração atual até a CredPay dizer qual é o substituto.

10Mudanças que quebram contrato

// Single conversion point in the channel's GruPag adapter
static String toCents(BigDecimal reais) {           // card: cents as a string
    return reais.setScale(2, RoundingMode.UNNECESSARY).movePointRight(2).toPlainString();
}
static BigDecimal toPixReais(BigDecimal reais) {      // PIX: reais as a decimal
    return reais.setScale(2, RoundingMode.UNNECESSARY);
}

11Proposta técnica

Um provedor novo, ao lado do antigo

Em vez de alterar os serviços atuais, o channel ganha um adaptador novo (service/grupag/) com códigos de serviço próprios e um road_info apontando para api2.grupag.com.br. Os dois caminhos convivem; a rota decide qual é usado.

flowchart LR
  BA["backapply"] --> RC{"route_cfg
por comerciante
e operação"}
  RC -- "código antigo" --> OLD["Serviços CredPay atuais
B10 · B21 · B61 …"]
  RC -- "código novo" --> NEW["Adaptador GruPag
códigos novos"]
  OLD --> CP[("APIs CredPay atuais")]
  NEW --> GP[("api2.grupag.com.br")]
  OP["Operador no painel"] -. "troca a linha
para virar ou voltar" .-> RC

Virar uma operação é editar route_cfg no painel. Voltar é desfazer a edição.

Mudanças por repositório

# Full or partial refund (card). Only until 23:59 on the capture day (Brasília time).
curl -X DELETE "https://api2-homolog.grupag.com.br/v1/pagamento/cancelar" \
  -H "Authorization: Bearer $GRUPAG_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "nit": "pag_59c416ca3552…", "amount": "5000" }'

12Plano de migração

Em cada fase

1. Testes de contrato em homologação, usando a coleção Postman da CredPay como referência.
2. Um comerciante piloto em produção, virado pela rota.
3. Acompanhar taxa de aprovação, erros 4xx/5xx por código e tempo de resposta, comparando com o caminho antigo.
4. Virar o restante dos comerciantes em lotes.

Datas serão definidas depois da Fase 0, quando soubermos o que está ativo e o que a CredPay respondeu.

13Riscos

14Perguntas em aberto para a CredPay

1. Tokens. Tokens criados em /Tokenizacao/CriarToken e no cofre valem em /v1/pagamento? Existe migração em lote?
2. Lacunas. Qual o substituto para TEF, extrato, transferência bancária e listagem de transações?
3. Webhooks. Há notificação de confirmação para PIX e cartão, ou só consulta?
4. Recorrência. Quais são as rotas do contrato de recorrência citado na documentação?
5. Simulação. O hashSimulacao é conferido no pagamento? A página de simulação diz que sim; a de cartão diz que é aceito e ignorado.
6. Empresas. Como mapear nossos comerciantes para Cliente-Id: uma chave por ambiente com todos vinculados, ou uma por comerciante?
7. Limites. Há limite de requisições por chave?
8. Prazo. Quando as APIs atuais serão desligadas?

15Referências

• Documentação GruPag (exige login): Acesso e API Key, APIs PIX, API Compra com Cartão, API de Simulação.
• channel: CheckOutTokenServiceImpl, CheckOutOperationServiceImpl, PreAuthService, service/credpay/impl/*, ThreeDomainSecurePaymentService, TefService, SynChannelDataService, ApiCodeConstant.
• card-vault: CredpagamentosClient, CredpayClient, application.yaml.
• backapply: RoadRouteServiceImpl, CardCertifyServiceImpl.

01Summary

CredPay has published a new API, documented in the GruPag portal (api2.grupag.com.br). Today we talk to CredPay through eight integrations in two services, with four different logins. This RFC proposes:

• A new adapter in phiz-microwd-channel, next to the old one, with its own service codes and API Key authentication.
• Replacing the CredPay client in phiz-pay-card-vault with the new card contract.
• A cutover driven by the route_cfg table, which operators already edit in the internal panel. Each operation switches path with one configuration row and switches back the same way, with no deploy.
• Five phases, starting with PIX, the simplest flow, and leaving 3DS for last because it also changes the front end.

The RFC also lists what the new API does not cover: card terminals (TEF), statements for reconciliation, bank transfers and listings. Those operations stay on the old integration until CredPay answers the open questions.

02Context: how it works today

CredPay handles cards (checkout, saved cards, pre-authorization, 3DS), PIX by QR Code and the merchants' card terminals. No app-facing service talks to it directly: the request goes down the service chain to the channel, which is the only service that knows CredPay, together with the card vault.

flowchart LR
  APP["phiz-flutter
app"] --> AS["microwd-appserver
app API"]
  AS --> BA["microwd-backapply
picks the route"]
  BA --> CH["microwd-channel
talks to providers"]
  CH --> CP[("CredPay
4 APIs")]
  CH --> CV["pay-card-vault
card vault"]
  CV --> CP
  IF["phiz-inner-front
panel"] --> IN["phiz-inner"]
  IN --> DB[("route_cfg
road_info")]
  DB -. "reads the route" .-> BA
  DB -. "reads the URL" .-> CH

Dashed lines are configuration reads. The panel is not part of the payment: it sets the rules before and shows the result after.

How an operation reaches CredPay

1. backapply looks up route_cfg for the transaction type, payment method and card BIN (RoadRouteServiceImpl.getRouteByTranPayAcct). The route says which provider and which service code handle it.
2. channel receives the code (for example B21, payment with a saved card) and runs the Spring service registered under that name.
3. The service reads the provider base URL from road_info and calls CredPay.

03Current integrations

Inventory taken from the code of phiz-microwd-channel and phiz-pay-card-vault.

04The new API

The documentation lives in the GruPag portal (login required) and has four parts: Access and API Key, PIX APIs, Card Purchase API and Simulation API.

flowchart LR
  subgraph HOJE["Today"]
    direction TB
    A1["/AuthCredPay
checkout · TEF · vault"]
    A2["/oauth/token
PIX"]
    A3["autenticacao/gerar-token
3DS"]
    A4["api-services /AuthCredPay
reconciliation"]
  end
  subgraph NOVO["GruPag API"]
    K["Authorization: Bearer gpk_…
Cliente-Id: company"]
  end
  HOJE ==> NOVO

Four logins, each with a token, cache and renewal, become one fixed key sent on every call.

General rules

# Today: four different logins, each with its own token and renewal
POST {road_info.url}/AuthCredPay            # checkout, pre-auth, TEF, card-vault
POST {road_info.url}/oauth/token            # PIX and bank transfer
POST {road_info.url}autenticacao/gerar-token # 3DS (platform API)
POST https://api-services.credpay.com.br/AuthCredPay/   # reconciliation (hard-coded URL)

# New: one API Key (gpk_...) on every call, no login, no renewal
curl -X GET "https://api2-homolog.grupag.com.br/v1/pagamento/consulta/nit?nit=$NIT" \
  -H "Authorization: Bearer $GRUPAG_API_KEY" \
  -H "Cliente-Id: $CLIENTE_ID"   # same value on every call of the flow

05Goals and non-goals

Goals

• Move card, saved card, 3DS, pre-authorization and PIX to the new API without losing any operation that is live today.
• Replace the four logins and CredPayAuthTask with an API Key kept in the secrets vault.
• Switch each operation on and off by configuration, per merchant, with no deploy.
• Keep amount and status conversions in a single adapter.

Out of scope

• Using the Simulation API to show installments and fees in the app. A possible improvement, not a migration requirement.
• TEF, reconciliation and bank transfers, while the new API has no equivalent.
• Other providers (Pinbank, Cronos, Afro).

06Route-by-route mapping

Saved card and checkout

{
  "nomeDoCliente": "JOAO DA SILVA",
  "documento": "12345678901",
  "quantidadeDeParcelas": 1,
  "valorInicial": 150.0,
  "token": "TOKEN_DO_CARTAO",
  "numeroInterno": "PED-4711",
  "subDominioId": 1234,
  "lojaId": 1
}

{
  "merchantChargeId": "20260901010707410895669",
  "orderId": "PED-4711",
  "installments": "1",
  "authorizerId": "2",
  "amount": "15000",
  "typeTransaction": "C",
  "card": {
    "token": "crd_d6dc9c299d15…"
  }
}

The same saved-card payment, before and after. The amount goes from reais to cents, and the internal number becomes orderId.

Pre-authorization

Card with 3DS

PIX

Card vault

07New card flow with 3DS

The biggest flow change is in 3DS. Today backapply returns a ready-made URL (certifyUrl, in CardCertifyServiceImpl) and the front end just opens it. With the new API, two steps run in the payer's browser, and the front end has to build and post the forms.

sequenceDiagram
  autonumber
  participant F as Payer front end
  participant BA as backapply
  participant CH as channel
  participant G as GruPag API
  participant E as Issuing bank
  BA->>CH: start 3DS for the order
  CH->>G: POST /3ds/autenticacao
  G-->>CH: merchantChargeId and threeDsMethod
  CH-->>BA: 3DS Method data
  BA-->>F: data for the browser
  F->>E: 3DS Method in a hidden iframe
  BA->>CH: authenticate with browser data
  CH->>G: POST /3ds/configuracao
  G-->>CH: frictionless or challenge
  F->>E: challenge with creq, if any
  CH->>G: GET /3ds/consultar3DS
  G-->>CH: eci and CAVV
  CH->>G: POST /v1/pagamento with merchantChargeId
  G-->>CH: nit and status CONFIRMADO

The same Cliente-Id must go on every call to the GruPag API in this flow. If one call misses it, the payment answers "3DS not found".

08New PIX flow

PIX barely changes shape: generate, then poll until paid. What is new is the refund with a time rule, and disputes.

sequenceDiagram
  autonumber
  participant CH as channel
  participant G as GruPag API
  participant P as Payer
  CH->>G: POST /transacional/pix/qrcode
  G-->>CH: transactionId and copy-and-paste code
  CH-->>P: QR Code
  P->>G: pays at the bank
  loop until CONFIRMADO or EXPIRADO
    CH->>G: GET /transacional/pix/consulta/{id}
    G-->>CH: status
  end

stateDiagram-v2
  [*] --> GERADO
  GERADO --> CONFIRMADO: payment
  GERADO --> EXPIRADO: expired
  CONFIRMADO --> ESTORNANDO: refund within 24 h
  ESTORNANDO --> ESTORNADO
  CONFIRMADO --> DISPUTA: refund after 24 h
  DISPUTA --> CANCELANDO: admin approves
  CANCELANDO --> CANCELADO
  DISPUTA --> PAGO: admin denies

Status of a PIX charge in the new API. Disputes are decided by an Admin user, which calls for a screen in the internal panel.

curl -X POST "https://api2-homolog.grupag.com.br/transacional/pix/qrcode" \
  -H "Authorization: Bearer $GRUPAG_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "amount": 15.00, "description": "Pedido PED-12345", "expirationSeconds": 3600 }'
# 200 → { "transactionId": "a1b2…", "status": "GERADO", "pixCopyAndPaste": "000201…", "destination": "TRANSACIONAL-PIX-SICREDI" }

09Gaps

These operations are not in the new documentation. They stay on the current integration until CredPay names a replacement.

10Breaking changes

// Single conversion point in the channel's GruPag adapter
static String toCents(BigDecimal reais) {           // card: cents as a string
    return reais.setScale(2, RoundingMode.UNNECESSARY).movePointRight(2).toPlainString();
}
static BigDecimal toPixReais(BigDecimal reais) {      // PIX: reais as a decimal
    return reais.setScale(2, RoundingMode.UNNECESSARY);
}

11Technical proposal

A new provider, next to the old one

Instead of changing the current services, the channel gets a new adapter (service/grupag/) with its own service codes and a road_info entry pointing to api2.grupag.com.br. Both paths coexist; the route decides which one is used.

flowchart LR
  BA["backapply"] --> RC{"route_cfg
per merchant
and operation"}
  RC -- "old code" --> OLD["Current CredPay services
B10 · B21 · B61 …"]
  RC -- "new code" --> NEW["GruPag adapter
new codes"]
  OLD --> CP[("Current CredPay APIs")]
  NEW --> GP[("api2.grupag.com.br")]
  OP["Operator in the panel"] -. "edits the row
to switch or roll back" .-> RC

Switching an operation means editing route_cfg in the panel. Rolling back means undoing the edit.

Changes per repository

# Full or partial refund (card). Only until 23:59 on the capture day (Brasília time).
curl -X DELETE "https://api2-homolog.grupag.com.br/v1/pagamento/cancelar" \
  -H "Authorization: Bearer $GRUPAG_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "nit": "pag_59c416ca3552…", "amount": "5000" }'

12Migration plan

In every phase

1. Contract tests in staging, using CredPay's Postman collection as the reference.
2. One pilot merchant in production, switched by route.
3. Watch approval rate, 4xx/5xx errors per code and response time, compared with the old path.
4. Switch the remaining merchants in batches.

Dates will be set after Phase 0, once we know what is live and what CredPay has answered.

13Risks

14Open questions for CredPay

1. Tokens. Do tokens created in /Tokenizacao/CriarToken and in the vault work in /v1/pagamento? Is there a bulk migration?
2. Gaps. What replaces TEF, statements, bank transfers and transaction listings?
3. Webhooks. Is there a confirmation notification for PIX and card, or only polling?
4. Recurring. What are the routes of the recurrence contract mentioned in the docs?
5. Simulation. Is hashSimulacao checked on payment? The simulation page says yes; the card page says it is accepted and ignored.
6. Companies. How should our merchants map to Cliente-Id: one key per environment with all of them linked, or one key per merchant?
7. Limits. Is there a rate limit per key?
8. Timeline. When will the current APIs be switched off?

15References

• GruPag documentation (login required): Access and API Key, PIX APIs, Card Purchase API, Simulation API.
• channel: CheckOutTokenServiceImpl, CheckOutOperationServiceImpl, PreAuthService, service/credpay/impl/*, ThreeDomainSecurePaymentService, TefService, SynChannelDataService, ApiCodeConstant.
• card-vault: CredpagamentosClient, CredpayClient, application.yaml.
• backapply: RoadRouteServiceImpl, CardCertifyServiceImpl.

01摘要

CredPay 发布了新的 API，文档位于 GruPag 门户（api2.grupag.com.br）。目前我们通过两个服务中的八个集成对接 CredPay，使用四种不同的登录方式。本 RFC 提议：

• 在 phiz-microwd-channel 中新增一个适配器，与旧适配器并存，使用独立的服务编码，并通过 API Key 认证。
• 将 phiz-pay-card-vault 中的 CredPay 客户端替换为新的银行卡接口。
• 通过 route_cfg 表控制切换。运营人员已经在内部管理后台维护这张表。每项操作改一行配置即可切换，改回即可回滚，无需发版。
• 分五个阶段：先做最简单的 PIX，最后做 3DS，因为 3DS 还涉及前端改动。

本 RFC 也列出了新 API 尚未覆盖的能力：刷卡终端（TEF）、对账用的流水、银行转账和列表查询。这些操作在 CredPay 回答待定问题之前继续使用旧集成。

02背景：当前的工作方式

CredPay 负责银行卡（收银台、已保存的卡、预授权、3DS）、PIX 二维码收款以及商户的刷卡终端。面向 App 的服务都不直接调用它：请求沿服务链传到 channel，只有 channel 和卡片保险库（card-vault）对接 CredPay。

flowchart LR
  APP["phiz-flutter
App"] --> AS["microwd-appserver
App 接口"]
  AS --> BA["microwd-backapply
选择路由"]
  BA --> CH["microwd-channel
对接渠道"]
  CH --> CP[("CredPay
4 套 API")]
  CH --> CV["pay-card-vault
卡片保险库"]
  CV --> CP
  IF["phiz-inner-front
管理后台"] --> IN["phiz-inner"]
  IN --> DB[("route_cfg
road_info")]
  DB -. "读取路由" .-> BA
  DB -. "读取地址" .-> CH

虚线表示读取配置。管理后台不参与支付本身：它在支付之前设定规则，在支付之后展示结果。

一次操作如何到达 CredPay

1. backapply 按交易类型、支付方式和卡 BIN 在 route_cfg 中查找路由（RoadRouteServiceImpl.getRouteByTranPayAcct）。路由决定由哪个渠道、哪个服务编码处理。
2. channel 收到编码（例如 B21，已保存卡支付），执行以该名称注册的 Spring 服务。
3. 该服务从 road_info 读取渠道基础地址，然后调用 CredPay。

03现有集成

以下清单来自 phiz-microwd-channel 和 phiz-pay-card-vault 的代码。

04新 API

文档位于 GruPag 门户（需要登录），共四部分：访问与 API Key、PIX API、银行卡支付 API、费率模拟 API。

flowchart LR
  subgraph HOJE["现在"]
    direction TB
    A1["/AuthCredPay
收银台 · TEF · 保险库"]
    A2["/oauth/token
PIX"]
    A3["autenticacao/gerar-token
3DS"]
    A4["api-services /AuthCredPay
对账"]
  end
  subgraph NOVO["GruPag API"]
    K["Authorization: Bearer gpk_…
Cliente-Id: 公司"]
  end
  HOJE ==> NOVO

四种各自带令牌、缓存和续期的登录方式，变成每次调用都携带的一个固定密钥。

通用规则

# Today: four different logins, each with its own token and renewal
POST {road_info.url}/AuthCredPay            # checkout, pre-auth, TEF, card-vault
POST {road_info.url}/oauth/token            # PIX and bank transfer
POST {road_info.url}autenticacao/gerar-token # 3DS (platform API)
POST https://api-services.credpay.com.br/AuthCredPay/   # reconciliation (hard-coded URL)

# New: one API Key (gpk_...) on every call, no login, no renewal
curl -X GET "https://api2-homolog.grupag.com.br/v1/pagamento/consulta/nit?nit=$NIT" \
  -H "Authorization: Bearer $GRUPAG_API_KEY" \
  -H "Cliente-Id: $CLIENTE_ID"   # same value on every call of the flow

05目标与非目标

目标

• 将银行卡、已保存的卡、3DS、预授权和 PIX 迁移到新 API，不丢失任何当前在用的操作。
• 用存放在密钥库中的 API Key 取代四种登录方式和 CredPayAuthTask。
• 按商户、通过配置开启或关闭每项操作，无需发版。
• 金额和状态的转换集中在一个适配器中。

不在范围内

• 使用费率模拟 API 在 App 中展示分期和费率。这是可选的改进，不是迁移的前提。
• 新 API 尚无对应能力的 TEF、对账和银行转账。
• 其他渠道（Pinbank、Cronos、Afro）。

06逐条路由映射

已保存的卡与收银台

{
  "nomeDoCliente": "JOAO DA SILVA",
  "documento": "12345678901",
  "quantidadeDeParcelas": 1,
  "valorInicial": 150.0,
  "token": "TOKEN_DO_CARTAO",
  "numeroInterno": "PED-4711",
  "subDominioId": 1234,
  "lojaId": 1
}

{
  "merchantChargeId": "20260901010707410895669",
  "orderId": "PED-4711",
  "installments": "1",
  "authorizerId": "2",
  "amount": "15000",
  "typeTransaction": "C",
  "card": {
    "token": "crd_d6dc9c299d15…"
  }
}

同一笔已保存卡支付的前后对比。金额从雷亚尔改为分，内部编号改为 orderId。

预授权

3DS 银行卡

PIX

卡片保险库

07新的 3DS 银行卡流程

流程上最大的变化在 3DS。现在 backapply 返回一个现成的地址（CardCertifyServiceImpl 中的 certifyUrl），前端只需打开。新 API 中有两个步骤在付款人的浏览器中执行，前端需要自己构造并提交表单。

sequenceDiagram
  autonumber
  participant F as 付款人前端
  participant BA as backapply
  participant CH as channel
  participant G as GruPag API
  participant E as 发卡行
  BA->>CH: 为订单发起 3DS
  CH->>G: POST /3ds/autenticacao
  G-->>CH: merchantChargeId 和 threeDsMethod
  CH-->>BA: 3DS Method 数据
  BA-->>F: 交给浏览器的数据
  F->>E: 在隐藏 iframe 中执行 3DS Method
  BA->>CH: 携带浏览器数据进行认证
  CH->>G: POST /3ds/configuracao
  G-->>CH: 无感通过或需要挑战
  F->>E: 如有挑战，提交 creq
  CH->>G: GET /3ds/consultar3DS
  G-->>CH: eci 和 CAVV
  CH->>G: POST /v1/pagamento 携带 merchantChargeId
  G-->>CH: nit 和状态 CONFIRMADO

此流程中对 GruPag API 的每次调用都必须携带相同的 Cliente-Id。只要有一次缺失，支付就会返回"3DS 未找到"。

08新的 PIX 流程

PIX 的流程形态基本不变：生成二维码，然后轮询直到支付完成。新增的是带时限规则的退款，以及争议处理。

sequenceDiagram
  autonumber
  participant CH as channel
  participant G as GruPag API
  participant P as 付款人
  CH->>G: POST /transacional/pix/qrcode
  G-->>CH: transactionId 和复制粘贴码
  CH-->>P: 二维码
  P->>G: 在银行完成付款
  loop 直到 CONFIRMADO 或 EXPIRADO
    CH->>G: GET /transacional/pix/consulta/{id}
    G-->>CH: 状态
  end

stateDiagram-v2
  [*] --> GERADO
  GERADO --> CONFIRMADO: 付款
  GERADO --> EXPIRADO: 过期
  CONFIRMADO --> ESTORNANDO: 24 小时内退款
  ESTORNANDO --> ESTORNADO
  CONFIRMADO --> DISPUTA: 超过 24 小时退款
  DISPUTA --> CANCELANDO: 管理员批准
  CANCELANDO --> CANCELADO
  DISPUTA --> PAGO: 管理员驳回

新 API 中一笔 PIX 收款的状态。争议由 Admin 用户裁决，因此需要在内部管理后台提供页面。

curl -X POST "https://api2-homolog.grupag.com.br/transacional/pix/qrcode" \
  -H "Authorization: Bearer $GRUPAG_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "amount": 15.00, "description": "Pedido PED-12345", "expirationSeconds": 3600 }'
# 200 → { "transactionId": "a1b2…", "status": "GERADO", "pixCopyAndPaste": "000201…", "destination": "TRANSACIONAL-PIX-SICREDI" }

09缺口

以下操作在新文档中没有出现。在 CredPay 给出替代方案之前，继续使用现有集成。

10不兼容变更

// Single conversion point in the channel's GruPag adapter
static String toCents(BigDecimal reais) {           // card: cents as a string
    return reais.setScale(2, RoundingMode.UNNECESSARY).movePointRight(2).toPlainString();
}
static BigDecimal toPixReais(BigDecimal reais) {      // PIX: reais as a decimal
    return reais.setScale(2, RoundingMode.UNNECESSARY);
}

11技术方案

新渠道与旧渠道并存

不改动现有服务，而是在 channel 中新增适配器（service/grupag/），使用独立的服务编码，并新增一条指向 api2.grupag.com.br 的 road_info。两条路径并存，由路由决定走哪一条。

flowchart LR
  BA["backapply"] --> RC{"route_cfg
按商户
按操作"}
  RC -- "旧编码" --> OLD["现有 CredPay 服务
B10 · B21 · B61 …"]
  RC -- "新编码" --> NEW["GruPag 适配器
新编码"]
  OLD --> CP[("现有 CredPay API")]
  NEW --> GP[("api2.grupag.com.br")]
  OP["管理后台的运营人员"] -. "修改该行
切换或回滚" .-> RC

切换一项操作就是在管理后台修改 route_cfg，回滚就是撤销这次修改。

各仓库的改动

# Full or partial refund (card). Only until 23:59 on the capture day (Brasília time).
curl -X DELETE "https://api2-homolog.grupag.com.br/v1/pagamento/cancelar" \
  -H "Authorization: Bearer $GRUPAG_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "nit": "pag_59c416ca3552…", "amount": "5000" }'

12迁移计划

每个阶段

1. 在测试环境做接口契约测试，以 CredPay 的 Postman 集合为参考。
2. 在生产环境选一个试点商户，通过路由切换。
3. 与旧路径对比，观察授权成功率、各编码的 4xx/5xx 错误和响应时间。
4. 分批切换其余商户。

具体日期在第 0 阶段之后确定，届时我们会知道哪些编码在用以及 CredPay 的答复。

13风险

14需要 CredPay 回答的问题

1. 令牌。在 /Tokenizacao/CriarToken 和保险库中创建的令牌能否在 /v1/pagamento 中使用？是否支持批量迁移？
2. 缺口。TEF、流水、银行转账和交易列表的替代方案是什么？
3. Webhook。PIX 和银行卡是否有结果通知，还是只能轮询？
4. 周期扣款。文档中提到的周期扣款合约有哪些路由？
5. 模拟。支付时是否校验 hashSimulacao？模拟页面说会校验，银行卡页面说会接收但忽略。
6. 公司。我们的商户如何对应到 Cliente-Id：每个环境一个密钥并关联所有商户，还是每个商户一个密钥？
7. 限流。每个密钥是否有请求频率限制？
8. 时间表。现有 API 何时下线？

15参考资料

• GruPag 文档（需要登录）：访问与 API Key、PIX API、银行卡支付 API、费率模拟 API。
• channel：CheckOutTokenServiceImpl、CheckOutOperationServiceImpl、PreAuthService、service/credpay/impl/*、ThreeDomainSecurePaymentService、TefService、SynChannelDataService、ApiCodeConstant。
• card-vault：CredpagamentosClient、CredpayClient、application.yaml。
• backapply：RoadRouteServiceImpl、CardCertifyServiceImpl。