ITP - Criar Consentimento (Payment Initiation)

Visão Geral

A payment initiation é o objeto que representa a intenção de pagamento do usuário. Ela contém os dados do pagador, do recebedor e do valor a ser transferido. Após criada, retorna uma authorizationUrl para onde o usuário deve ser redirecionado para autenticar e aprovar o pagamento na sua instituição.

Cada payment initiation corresponde a um único pagamento Pix.

Criar Payment Initiation

POST /baas/v1/open/itp/payment-initiation

Autenticação: Bearer Token (application_token)

Request

POST {{base_url}}/baas/v1/open/itp/payment-initiation
Authorization: Bearer {{application_token}}
Content-Type: application/json

{
  "brandId": "6900de69dfdf118e980e10ec",
  "redirectUrl": "http://localhost:8080/callback",
  "data": {
    "loggedUser": {
      "document": {
        "identification": "12345678909",
        "rel": "CPF"
      }
    },
    "creditor": {
      "cpfCnpj": "58764789000137",
      "personType": "PESSOA_JURIDICA",
      "name": "Marco Antonio de Brito"
    },
    "payment": {
      "type": "PIX",
      "amount": "1.15",
      "currency": "BRL",
      "date": "2026-05-31",
      "details": {
        "localInstrument": "DICT",
        "proxy": "12345678901",
        "creditorAccount": {
          "accountType": "CACC",
          "ispb": "12345678",
          "issuer": "1774",
          "number": "1234567890"
        }
      }
    }
  }
}

Campos do Request

Nível raiz

data.loggedUser.document

data.creditor

data.payment

data.payment.details

data.payment.details.creditorAccount

data.debtorAccount (opcional)

Quando informado, pré-seleciona a conta devedora na detentora:

Modalidades de Iniciação (localInstrument)

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

Quando localInstrument = QRDN, a Celcoin lê o QR Code dinâmico e consulta a cobrança vinculada a ele. Os dados do pagamento são comparados com os dados da cobrança antes da criação do consentimento. Se alguma validação falhar, a requisição é rejeitada com HTTP 422 e o consentimento não é criado.

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 na cobrança, a requisição é rejeitada.

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

Response — HTTP 201

{
  "authorizationUrl": "https://openfinance.dev.fbank.opb.obm.engdev.fsapps.io/orgs/finansystech/auth?client_id=4f-BSI7qe1iD_5B82NfF3&scope=openid%20consent%3A...&response_type=code%20id_token&redirect_uri=...&request_uri=...",
  "id": "ZVjnvOXJSlgth9MVDS4HmdvyhBlHt_s1MPhMNMBhGSU"
}

Response — HTTP 422 (Erro de data)

{
  "errors": [
    {
      "code": "DATA_PAGAMENTO_INVALIDA",
      "title": "Data de pagamento inválida.",
      "detail": "Data de pagamento inválida para a forma de pagamento selecionada."
    }
  ]
}

{
  "message": "QRDN payment amount does not match charge amount",
  "code": 422,
  "type": "QRDN_AMOUNT_MISMATCH",
  "data": { "field": "payment.amount" }
}

Códigos de Retorno

Pontos de Atenção