EFXPay Middleware

Arquitetura

Regra central do projeto: nenhum controller chama HTTP diretamente. Toda integração passa por serviços em App\Services\GlobalSCM.

Stack e configuração

Variáveis de ambiente principais

Prefixo da API EFXPay: {APP_URL}/api/v1/

Contrato mobile (OpenAPI)

Para integração do app, use os artefactos versionados nesta pasta — não este HTML como fonte de verdade.

Visualizar/editar o spec: Swagger Editor (importar o YAML).

Autenticação

O login do app usa duas validações: credenciais no banco EFXPay (users) e login na GlobalSCM com o mesmo email/senha. O token do provider fica em banking_sessions; o app recebe apenas o JWT EFXPay.

Request — login

{
  "email": "usuario@exemplo.com",
  "password": "senha"
}

Response — login

{
  "access_token": "<jwt-efxpay>",
  "token_type": "Bearer"
}

Provider: POST /internal/api/v1/auth/login

Contas

Todos os endpoints abaixo exigem Authorization: Bearer {jwt}.

Provider saldo/extrato: GET /internal/api/v1/account/balance, .../statement

PIX — envio e cobrança

Enviar PIX — POST /api/v1/pix/send

Fluxo interno (2 passos no provider):

1. POST /internal/api/v1/keys/dict — consulta chave (payerId = CPF/CNPJ do user, key = chave destino)
2. POST /internal/api/v1/payments — pagamento DICT com endToEnd retornado na consulta

Headers:
  Authorization: Bearer {jwt}
  Idempotency-Key: {uuid-unico}

Body:
{
  "pix_key": "destino@email.com",
  "amount": 10.50,
  "description": "Opcional"
}

Response:
{
  "transaction_id": "uuid-local",
  "status": "PROCESSING",
  "end_to_end": "E..." 
}

Status possíveis: PROCESSING, COMPLETED, FAILED.

Atualização de status: modelo webhook-first na GlobalSCM. GET /api/v1/pix/{id} lê apenas o registro local — não consulta o provider.

Cobrança QR — POST /api/v1/pix/charge

Campo type obrigatório:

• dynamic → POST .../payments/qrcode/dynamic (valor + expiração)
• static → POST .../payments/qrcode/static (valor fixo)

O EFXPay gera automaticamente transactionIdentification (26 caracteres alfanuméricos).

Headers:
  Authorization: Bearer {jwt}
  Idempotency-Key: {uuid-unico}

Body (exemplo dynamic):
{
  "type": "dynamic",
  "amount": 129.47,
  "description": "Pagamento pedido 123",
  "key": "opcional — default: email ou documento do user",
  "receiver_name": "opcional — max 25 chars",
  "city": "opcional — default Sao Paulo",
  "zipcode": "opcional — 8 dígitos",
  "expiration_qr": 3600,
  "payer_name": "opcional",
  "payer_cpf": "opcional",
  "reusable": false
}

Response:
{
  "transaction_id": "uuid-local",
  "status": "PROCESSING",
  "qr_code": "...",
  "copy_paste": "00020126..."
}

Consultar transação — GET /api/v1/pix/{id}

{
  "transaction_id": "uuid",
  "status": "PROCESSING"
}

Para cobranças, inclui qr_code e copy_paste se gravados no envio.

Chaves PIX

Gestão de chaves DICT da conta do utilizador autenticado (token banking_sessions).

Criar chave — body

{
  "key_type": "EVP_ENDERECO_VIRTUAL_DE_PAGAMENTO",
  "email": "opcional — só se key_type=E_MAIL e diferente do cadastro"
}

Valores key_type: CPF, CNPJ, CELULAR, E_MAIL, EVP_ENDERECO_VIRTUAL_DE_PAGAMENTO.

Excluir chave — body

{
  "key": "chave@email.com"
}

Listagem usa dados da conta do user (agência, conta, CPF/CNPJ, ISPB do .env).

Webhooks

Header opcional: X-Webhook-Secret (validado se GLOBALSCM_WEBHOOK_SECRET estiver definido). Payload é persistido em webhook_events e processado em fila (ProcessGlobalScmWebhookJob). Deduplicação por hash do payload.

Onboarding (pessoa física)

API EFXPay — prefixo /api/v1/onboarding/:

Mapa GlobalSCM (implementado)

Estrutura de código

app/
├── Http/Controllers/Api/
│   ├── AuthController.php
│   ├── AccountController.php
│   ├── PixController.php
│   ├── PixKeysController.php
│   ├── OnboardingController.php
│   └── WebhookController.php
├── Services/
│   ├── GlobalSCM/
│   │   ├── GlobalScmClient.php
│   │   ├── GlobalScmConnector.php
│   │   ├── GlobalScmPix.php
│   │   ├── GlobalScmPixKeys.php
│   │   ├── GlobalScmPaymentRequestMapper.php
│   │   ├── GlobalScmPixResponseMapper.php
│   │   ├── GlobalScmAccountContext.php
│   │   └── ...
│   └── Onboarding/
config/globalscm.php    # paths, ISPB, timeouts
routes/api.php          # rotas /api/v1
docs/
├── globalscm-pix-endpoint-probes.md
└── pix-manual-validation-checklist.md

Ferramentas de desenvolvimento

Apenas com APP_ENV=local:

Comando útil: php artisan efxpay:ensure-dev-user — cria user local com credenciais do .env.

Testes e validação

php artisan test
php artisan migrate

Testes usam GLOBALSCM_STUB=true (phpunit.xml). Checklist manual em docs/pix-manual-validation-checklist.md.

Ordem sugerida para homologação PIX

1. POST /api/v1/auth/login — user onboarded no banco
2. GET /api/v1/accounts/me — conta com agência/número/documento
3. GET /api/v1/accounts/balance
4. POST /api/v1/pix/charge com type: dynamic
5. POST /api/v1/pix/send com valor mínimo
6. GET /api/v1/pix/keys e CRUD de chaves

Limitações conhecidas

• Onboarding GlobalSCM — rotas /core/v2/* e /integracoes não disponíveis nos hosts testados (404). Integração reversa (webhooks CONTA_CRIADA) ainda não implementada.
• Status PIX outbound — sem polling no provider; depende de webhook ou consulta futura ao extrato por endToEnd.
• baas/list — fora do escopo do MVP.
• User precisa de document, agency e account_number em accounts após login para PIX e chaves.