Criar Jornada de Pagamento

Características Principais

• Criação de Sessão: Cria uma nova sessão de jornada ITP para payments
• Seleção de Jornada: Suporta especificação de jornada customizada ou uso da jornada padrão configurada
• URL de Redirecionamento: Gera uma URL única contendo todos os parâmetros necessários para iniciar a jornada

Endpoint

POST /open-keys/itp/api/v2/payments/v4/journeys-sessions

Autenticação

A API requer autenticação OAuth2 utilizando o fluxo de Client Credentials

Permissões Requeridas

• app: Permissão para integrações diretas via API
• journey: Permissão para acessar jornadas

Headers Obrigatórios

Authorization: Bearer {access_token}
Content-Type: application/json

Estrutura da Requisição

Payload Completo

{
    "journeyId": "payments-fido",
    "paymentInitiationData": {
        "loggedUser": {
            "document": {
                "identification": "12345678909",
                "rel": "CPF"
            }
        },
        "creditor": {
            "cpfCnpj": "58764789000137",
            "personType": "PESSOA_JURIDICA",
            "name": "Marco Antonio de Brito"
        },
        "payment": {
            "type": "PIX",
            "date": "{current_date}",
            "currency": "BRL",
            "amount": "1.00",
            "details": {
                "localInstrument": "DICT",
                "proxy": "[email protected]",
                "creditorAccount": {
                    "accountType": "CACC",
                    "ispb": "12345678",
                    "issuer": "1774",
                    "number": "1234567890"
                }
            }
        },
        "remittanceInformation": ""
    },
    "redirectUrl": "http://localhost:8080/callback",
    "tags": {
        "tag1": "123456",
    },
    "settings": [
        {
            "key": "JOURNEY_RULES",
            "value": [
                {
                    "path": "paymentInitiationData.loggedUser.document.identification",
                    "optional": true,
                    "editable": true
                },
                {
                    "path": "brandId",
                    "optional": true,
                    "editable": true
                },
                {
                    "path": "paymentInitiationData.payment.amount",
                    "optional": false,
                    "editable": false
                },
                {
                    "path": "paymentInitiationData.remittanceInformation",
                    "optional": true,
                    "editable": false
                },
                {
                    "path": "paymentInitiationData.payment.date",
                    "optional": true,
                    "editable": true
                },
                {
                    "path": "paymentInitiationData.payment.schedule",
                    "optional": true,
                    "editable": false
                }
            ]
        }
    ]
}

Campos da Requisição

Nível Raiz

Objeto paymentInitiationData

Array settings

Array de objetos contendo configurações da jornada.

Fluxo de Implementação

Passo a Passo

1. Obtenção do Token OAuth2

   • Obtenha um token de acesso válido com permissões app e journey
   • O token deve conter o claim azp com o clientId da aplicação

2. Preparação da Requisição

   • Defina o journeyId
   • Configure paymentInitiationData com usuário, credor e detalhes do pagamento
   • Configure redirectUrl (se necessário)
   • Adicione settings e tags conforme necessário

3. Envio da Requisição

   • Envie a requisição POST para o endpoint
   • Inclua o token no header Authorization

4. Processamento da Resposta

   • A sessão será criada com status PENDING
   • A resposta contém a journeySessionUrl para redirecionamento
   • Armazene o id da sessão para consultas futuras

5. Redirecionamento do Usuário

   • Utilize a journeySessionUrl retornada para redirecionar o usuário
   • O usuário será direcionado para a jornada de autorização

6. Monitoramento da Sessão

   • Monitore o status da sessão através do endpoint GET /open-keys/itp/api/v2/payments/v4/journeys-sessions/{id}
   • A sessão será atualizada conforme o progresso do fluxo

Resposta da API

Sucesso (200 OK)

{
    "journeyId": "{journeyId}",
    "paymentInitiationApi": "PAYMENTS_V4",
    "applicationId": "{applicationId}",
    "tokenId": "{tokenId}",
    "journeySessionStageId": "{journeySessionStageId}",
    "journeySessionUrl": "{url}",
    "status": "PENDING",
    "id": "{id}",
    "..."
}

Campos Importantes da Resposta

Tratamento de Erros

400 Bad Request

Causa: Dados da requisição inválidos ou mal formatados.

{
    "error": "Validation Error",
    "message": "Campo obrigatório ausente"
}

Solução: Verifique o formato dos dados enviados e os requisitos de validação.

401 Unauthorized

Causa: Token de acesso inválido, expirado ou ausente.

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

Solução:

• Verifique se o token está presente no header Authorization
• Obtenha um novo token se o atual estiver expirado
• Verifique se o token possui as permissões necessárias

403 Forbidden

Causa: Aplicação não encontrada, jornada não encontrada ou redirectUrl não autorizada.

{
    "error": "Forbidden",
    "message": "application not found"
}

ou

{
    "error": "Forbidden",
    "message": "journey not found"
}

ou

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

Solução:

• Verifique se a aplicação existe e está ativa
• Verifique se o journeyId informado existe e está disponível
• Verifique se a redirectUrl está cadastrada nas URLs permitidas da aplicação

422 Unprocessable Entity

Causa: Validação de schema falhou.

{
    "error": "Unprocessable Entity",
    "message": "Validation failed"
}

Solução: Verifique os detalhes do erro e corrija os campos indicados.

500 Internal Server Error

Causa: Erro interno do servidor.

{
    "error": "Internal Server Error",
    "message": "An unexpected error occurred"
}

Solução: Tente novamente mais tarde. Se o problema persistir, entre em contato com o suporte.

Status da Sessão

• PENDING: Sessão criada, aguardando início do fluxo
• AWAITING_AUTHORISATION: Aguardando autorização do usuário na detentora
• AUTHORISED: Consentimento autorizado pelo usuário
• REJECTED: Consentimento rejeitado pelo usuário
• CANCELLED: Sessão cancelada
• EXPIRED: Sessão expirada
• FINISHED: Fluxo concluído com sucesso

Integração com Outros Endpoints

Após criar a sessão de jornada, você pode:

1. Consultar a Sessão: GET /open-keys/itp/api/v2/payments/v4/journeys-sessions/{id}
2. Listar Sessões: GET /open-keys/itp/api/v2/payments/v4/journeys-sessions