Create Payment Initiation V4 API

Visão Geral

A API de Create Payment Initiation V4 permite a criação de consentimentos de pagamento que requerem redirecionamento para autorização na detentora de conta. Este tipo de consentimento permite que uma instituição iniciadora de pagamento realize pagamentos após o usuário ser redirecionado para a detentora, fazer login e aprovar o consentimento.

Características Principais

• Fluxo com Redirecionamento: O usuário é redirecionado para a detentora de conta para autorizar o pagamento
• Retorno de URL de Autorização: A API retorna uma URL para redirecionamento
• 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": "{brand_id}",
    "redirectUrl": "{redirect_url}",
    "directoryCallback": false,
    "data": {
        "loggedUser": {
            "document": {
                "identification": "{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 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. Redirect URL: Deve estar cadastrada e autorizada para a aplicação
2. Brand ID: Deve existir no sistema
3. Payment Date: Deve ser futura ou atual
4. 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": "{brand_id}",
    "redirectUrl": "{redirect_url}",
    "directoryCallback": false,
    "data": {
        "loggedUser": {
            "document": {
                "identification": "{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": "{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 'identification' é obrigatório"
}

Causas comuns:

• Campos obrigatórios ausentes
• Formato de dados inválido (datas, valores monetários)

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. Valores Monetários: Valide o formato antes de enviar

Limites e Restrições

• 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