PIX V4 API

Visão Geral

A API de PIX V4 permite a criação de pagamentos PIX usando um payment initiation previamente autorizado. Este endpoint é utilizado para realizar transferências PIX após a autorização do consentimento e autenticação FIDO.

Características Principais

• Pagamentos PIX: Permite criar pagamentos PIX associados a um payment initiation autorizado
• Validação de Consentimento: Verifica se o consentimento está autorizado antes de criar o pagamento

Endpoint

POST /open-keys/itp/api/v2/payments/v4/payment-initiation/{paymentInitiationId}/pix

Onde {paymentInitiationId} é o identificador único do payment initiation retornado na criação da iniciação de pagamento (PAYMENTS_V4).

Autenticação

A API requer autenticação OAuth2 com a seguinte permissão:

• app: Para integrações diretas via API

O token de acesso deve ser enviado no header:

Authorization: Bearer {access_token}

Estrutura da Requisição

Payload Completo

{
    "data": [
        {
            "localInstrument": "DICT",
            "payment": {
                "amount": "1.00",
                "currency": "BRL"
            },
            "creditorAccount": {
                "accountType": "{account_type}",
                "ispb": "{ispb}",
                "issuer": "{issuer}",
                "number": "{account_number}"
            },
            "cnpjInitiator": "{cnpjInitiator}",
            "proxy": "{payment_proxy}",
            "endToEndId": "{endToEndId}",
            "authorisationFlow": "FIDO_FLOW"
        }
    ]
}

Campos da Requisição

Nível Raiz

Objeto data[]

Objeto payment

Objeto creditorAccount

Formato de Valores Monetários

Todos os valores monetários devem seguir o formato:

• Padrão: ^((\d{1,16}.\d{2}))$
• Exemplo: "150.00", "100000.12", "25.50"
• Mínimo: 4 caracteres (ex: "0.01")
• Máximo: 19 caracteres

Validações Importantes

1. Payment Initiation ID: O paymentInitiationId informado na URL deve existir e pertencer à aplicação autenticada
2. Status do Consentimento: O consentimento associado deve estar no status AUTHORISED
3. Fluxo de Autorização: Deve ser "FIDO_FLOW" para pagamentos com FIDO
4. Campos Obrigatórios: Todos os campos marcados como obrigatórios devem ser fornecidos

Implementação

Fluxo de Criação de Pagamento PIX

1. O sistema valida o paymentInitiationId e verifica se pertence à aplicação autenticada
2. Busca o payment initiation e o consentimento associado
3. Valida que o consentimento está no status AUTHORISED
4. Valida que o fluxo de autorização é compatível
5. Gera ou valida o endToEndId único para o pagamento
6. Cria o registro do pagamento na base de dados
7. Envia a requisição para a detentora de conta criar o pagamento PIX
8. Atualiza o registro do pagamento com a resposta da detentora
9. Atualiza o consentimento na detentora de conta
10. Dispara webhook para a aplicação
11. Retorna o payment initiation atualizado com o pagamento criado

Exemplo de Requisição (cURL)

curl -X POST \
  https://api.exemplo.com/open-keys/itp/api/v2/payments/v4/payment-initiation/{paymentInitiationId}/pix \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "data": [
        {
            "localInstrument": "DICT",
            "payment": {
                "amount": "1.00",
                "currency": "BRL"
            },
            "creditorAccount": {
                "accountType": "CACC",
                "ispb": "12345678",
                "issuer": "1774",
                "number": "12345678"
            },
            "cnpjInitiator": "12345678000123",
            "proxy": "[email protected]",
            "endToEndId": "E12345678202501011234567890123456",
            "authorisationFlow": "FIDO_FLOW"
        }
    ]
}'

Resposta da API

Sucesso (200 OK)

A API retorna um objeto contendo o payment initiation atualizado com o pagamento criado:

{
    "id": "{paymentInitiationId}",
    "paymentInitiationApi": "PAYMENTS_V4",
    "ofPayments": [
        {
            "id": "{payment_id}",
            "status": "ACSC",
            "endToEndId": "E12345678202501011234567890123456",
            "localInstrument": "DICT",
            "payment": {
                "amount": "1.00",
                "currency": "BRL"
            },
            "creditorAccount": {
                "accountType": "CACC",
                "ispb": "12345678",
                "issuer": "1774",
                "number": "12345678"
            },
            "proxy": "[email protected]",
            "authorisationFlow": "FIDO_FLOW"
        }
    ],
    "ofConsent": {
        "status": "AUTHORISED"
    },
    "updatedAt": 1234567890
}

Campos Importantes da Resposta

Erros Comuns

400 Bad Request

{
    "error": "Validation Error",
    "message": "Campo 'amount' é obrigatório"
}

Causas comuns:

• Campos obrigatórios ausentes
• Formato de dados inválido (datas, valores monetários, endToEndId)
• Validação de schema falhou

401 Unauthorized

{
    "error": "Unauthorized",
    "message": "Token inválido ou expirado"
}

Solução: Verifique se o token de acesso é válido e possui a permissão app.

403 Forbidden

{
    "error": "Forbidden",
    "message": "Payment initiation não autorizado"
}

Solução: O consentimento deve estar autorizado (AUTHORISED) antes de criar pagamentos PIX.

404 Not Found

{
    "error": "Not Found",
    "message": "Payment initiation não encontrado"
}

Solução: Verifique se o paymentInitiationId informado na URL existe e pertence à aplicação autenticada.

422 Unprocessable Entity

{
    "error": "Unprocessable Entity",
    "message": "End-to-End ID já existe"
}

Solução: O endToEndId deve ser único. Gere um novo identificador.

Boas Práticas

1. Validação de Consentimento: Sempre verifique se o consentimento está autorizado antes de criar pagamentos
2. Geração de End-to-End ID: Garanta que o endToEndId seja único e siga o formato do SPI
3. Tratamento de Erros: Implemente tratamento adequado para todos os códigos de erro possíveis
4. Idempotência: Use o endToEndId como chave para evitar duplicação de pagamentos