Create Payment Initiation V5 API

Visão Geral

A API de Create Payment Initiation V5 permite a criação de iniciações de pagamento usando um vínculo (enrollment) já autorizado. Este tipo de consentimento permite que uma instituição iniciadora de pagamento realize pagamentos utilizando autenticação FIDO (WebAuthn) para autorização.

Características Principais

• Uso de Vínculo Autorizado: Requer um enrollment previamente autorizado com FIDO
• Controle de Validade: Define data de vencimento do consentimento

Endpoint

POST /open-keys/itp/api/v2/payments/v5/payment-initiation

Autenticação

A API requer autenticação OAuth2 com uma das seguintes permissões:

• journey: Para fluxos que utilizam redirecionamento à detentora de conta
• 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

{
    "brandId": "{enrollment_brand_id}",
    "redirectUrl": "{redirect_url}",
    "directoryCallback": false,
    "enrollment": {
        "rp": "{fido_rp}",
        "platform": "{fido_platform}",
        "enrollmentId": "{itp_enrollment_id}"
    },
    "data": {
        "loggedUser": {
            "document": {
                "identification": "{enrollment_cpf}",
                "rel": "CPF"
            }
        },
        "creditor": {
            "cpfCnpj": "{cpf_recebedor}",
            "personType": "{tipo_pessoa_recebedor}",
            "name": "{nome_recebedor}"
        },
        "payment": {
            "type": "PIX",
            "date": "{payment_date}",
            "currency": "BRL",
            "amount": "{valor}",
						"purpose": "{purpose}",
            "details": {
                "localInstrument": "{payment_local_instrument}",
                "proxy": "{payment_proxy}",
                "creditorAccount": {
                    "accountType": "{account_type}",
                    "ispb": "{ispb}",
                    "issuer": "{issuer}",
                    "number": "{account_number}"
                }
            }
        },
        "remittanceInformation": "{descricao}"
    }
}

Campos da Requisição

Nível Raiz

Objeto enrollment

Objeto data

Objeto loggedUser

Objeto document

Objeto creditor

Objeto payment

Objeto details

Objeto creditorAccount

Formato de Valores Monetários

Todos os valores monetários devem seguir o formato:

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

Validações Importantes

1. Enrollment: O vínculo deve estar autorizado e válido
2. Redirect URL: Deve estar cadastrada e autorizada para a aplicação
3. Brand ID: Deve existir no sistema
4. Payment Date: Deve ser futura ou atual
5. Creditor Account: Deve ser válida para o tipo de pagamento

   Validações de QR Code Dinâmico (QRDN)

   Quando localInstrument = QRDN, os dados da cobrança são obtidos do payloadJWS enviado na requisição. Eles são comparados com os dados do pagamento antes da criação do consentimento. Se alguma validação falhar, a requisição é rejeitada com HTTP 422 e o consentimento não é criado.

   Validação	Regra	type do erro	data.field
   payloadJWS	Deve ser um payloadJWS válido, obtido na leitura do QR Code dinâmico	a definir	payloadJWS
   Valor	payment.amount deve ser igual ao valor da cobrança (ver "Regra de valor")	QRDN_AMOUNT_MISMATCH	payment.amount
   Chave Pix	payment.details.proxy deve ser igual à chave Pix da cobrança	QRDN_PROXY_MISMATCH	payment.details.proxy
   Recebedor	creditor.cpfCnpj deve ser igual ao CPF/CNPJ do recebedor da cobrança	QRDN_CREDITOR_MISMATCH	creditor.cpfCnpj
   Status	A cobrança deve estar ACTIVE ou ATIVA. Qualquer outro status é rejeitado	a definir	—
   Expiração	Quando a cobrança tiver expiração, ela não pode estar expirada	a definir	—
   Vencimento	Quando houver vencimento e validade após vencimento, o pagamento deve estar dentro do prazo	a definir	—

   Regra de valor – COB x COBV

   • COB (cobrança imediata): vale valor.original. Se valor.modalidadeAlteracao = 1, o pagador pode alterar o valor.
   • COBV (cobrança com vencimento): vale obrigatoriamente valor.final, sem alteração. Se valor.final não existir no payloadJWS, a requisição é rejeitada.

   As validações se aplicam somente a QRDN. As modalidades DICT, MANU, QRES, APDN, APES e INIC não mudam.

Implementação

Fluxo de Criação de Payment Initiation

A criação de payment initiation pode ocorrer de duas formas, dependendo do escopo de autenticação:

1. Fluxo com journey (Redirecionamento)

Quando o token possui o escopo journey:

1. O sistema cria uma sessão de jornada (journey-session)
2. Cria o registro de payment initiation
3. Cria o consentimento na detentora de conta
4. Retorna a URL de autorização para redirecionamento

Uso: Quando o usuário precisa ser redirecionado para autorizar o pagamento na detentora de conta.

2. Fluxo com app (API Direta)

Quando o token possui o escopo app:

1. O sistema valida o redirectUrl da aplicação
2. Cria uma sessão de jornada automaticamente
3. Cria o registro de payment initiation
4. Cria o consentimento na detentora de conta
5. Retorna a URL de autorização

Uso: Para integrações diretas via API sem necessidade de redirecionamento imediato.

Exemplo de Requisição (cURL)

curl -X POST \
  https://api.exemplo.com/open-keys/itp/api/v2/payments/v5/payment-initiation \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "brandId": "{enrollment_brand_id}",
    "redirectUrl": "{redirect_url}",
    "directoryCallback": false,
    "enrollment": {
        "rp": "{fido_rp}",
        "platform": "{fido_platform}",
        "enrollmentId": "{itp_enrollment_id}"
    },
    "data": {
        "loggedUser": {
            "document": {
                "identification": "{enrollment_cpf}",
                "rel": "CPF"
            }
        },
        "creditor": {
            "cpfCnpj": "{cpf_recebedor}",
            "personType": "{tipo_pessoa_recebedor}",
            "name": "{nome_recebedor}"
        },
        "payment": {
            "type": "PIX",
            "date": "{payment_date}",
            "currency": "BRL",
            "amount": "{valor}",
            "details": {
                "localInstrument": "{payment_local_instrument}",
                "proxy": "{payment_proxy}",
                "creditorAccount": {
                    "accountType": "{account_type}",
                    "ispb": "{ispb}",
                    "issuer": "{issuer}",
                    "number": "{account_number}"
                }
            }
        },
        "remittanceInformation": "{descricao}"
    }
}'

Resposta da API

Sucesso (200 OK)

A API retorna um objeto contendo:

{
    "id": "{payment_v5_id}",
    "brandId": "{enrollment_brand_id}",
    "redirectUrl": "{redirect_url}",
    "data": {
        // ... dados enviados na requisição
    },
    "journeySessionId": "...",
    "applicationId": "...",
    "paymentInitiationApi": "PAYMENTS_V5",
    "ofConsentId": "...",
    "authorizationUrl": "..."
}

Campos Importantes da Resposta

Erros Comuns

400 Bad Request

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

Causas comuns:

• Campos obrigatórios ausentes
• Formato de dados inválido (datas, valores monetários)
• Enrollment não autorizado ou inválido

401 Unauthorized

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

Solução: Verifique se o token de acesso é válido e possui as permissões necessárias (journey ou app).

403 Forbidden

{
    "error": "Forbidden",
    "message": "this redirectUrl is not allowed for this application"
}

Solução: Certifique-se de que o redirectUrl está cadastrado e autorizado para a aplicação.

404 Not Found

{
    "error": "Not Found",
    "message": "Brand não encontrada"
}

Solução: Verifique se o brandId informado existe no sistema.

422 Unprocessable Entity – dados do pagamento divergentes da cobrança do QR Code dinâmico (QRDN_*) ou payloadJWS inválido.

Boas Práticas

1. Validação de Dados: Valide todos os dados antes de enviar a requisição
2. Tratamento de Erros: Implemente tratamento adequado para todos os códigos de erro possíveis
3. Segurança: Nunca exponha tokens de acesso no frontend ou logs
4. URLs de Redirecionamento: Use HTTPS em produção para redirectUrl
5. Enrollment: Garanta que o vínculo está autorizado antes de usar
6. Valores Monetários: Valide o formato antes de enviar

Limites e Restrições

• Enrollment: Deve estar autorizado com FIDO
• Valores Monetários: Formato XXXXX.XX
• Redirect URL: Deve estar autorizada para a aplicação

Notas Adicionais

• O campo remittanceInformation é opcional e pode conter informações adicionais sobre o pagamento