Create Payment Initiation V4 API

Visão Geral

A API de Create Payment Initiation V4 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/v4/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}",
            "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

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/v4/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_v4_id}",
    "brandId": "{enrollment_brand_id}",
    "redirectUrl": "{redirect_url}",
    "data": {
        // ... dados enviados na requisição
    },
    "journeySessionId": "...",
    "applicationId": "...",
    "paymentInitiationApi": "PAYMENTS_V4",
    "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.

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