v1

latestOpenAPI 3.0.12026-07-245303882.5 MB

Payment Initiation

Process OAuth2 authorization callback from account holder

Handles OAuth2 authorization callback responses from account holder institutions after user consent. Processes authorization codes, ID tokens, and state parameters to complete the consent flow for payment initiation (PAYMENTS_V4), automatic payments (AUTOMATIC_PAYMENTS_V2), or enrollment-based payments (ENROLLMENTS_V2). This endpoint is called by the account holder after the user authorizes or rejects the consent request.

post/open-keys/itp/api/v2/payment-initiation/callback

Request body

statestring required

OAuth2 state parameter used for security validation

id_tokenstring

JWT identity token containing authenticated user information

codestring

Temporary authorization code used to obtain access token

errorstring

OAuth2 error code in case of authorization failure

error_descriptionstring

Detailed description of OAuth2 authorization error

Response

Payment initiation callback processed successfully.

brandIdstring required

Unique identifier of the financial institution brand where the account enrollment will be created

journeySessionIdstring

ID is the unique identifier of journey

redirectUrlstring uri required

Authorized callback URL where the user will be redirected after completing the enrollment authorization process at the account holder institution

directoryCallbackboolean

Indicates whether the redirection comes directly from the Open Finance Brasil directory or from a payment initiation flow

authorizationDevicestring

Custom name for the device or authorization method used by the user during the enrollment process. This field allows for user-friendly identification of the specific device that will be used for FIDO2 authentication and payment authorization. [Restriction] Must be filled whenever the payer user enters any information about the authorization device name during the account linking flow.

tagsstring

Tags que podem ser usadas para classificar a sessão da jornada.

idstring required

ID is the unique identifier of ITP

paymentInitiationApi'ENROLLMENTS_V2' required

Identifies the type of payment initiation API used. ENROLLMENTS_V2 indicates that this enrollment uses version 2 of the enrollments API for PIX payment initiation.

createdAtstring required

Record creation date and time

updatedAtstring required

Record last update date and time

deletedAtstring required

Record deletion date and time (soft delete)

applicationIdstring required

The application ID. It is an exclusive number that identifies the application.

tokenIdstring required

Unique identifier of the authentication token generated for this enrollment. Used internally for access control and enrollment session validation between the initiating institution and account holder.

authorizationUrlstring uri required

Authorization URL generated by the account holder institution where the user should be redirected to complete the consent and enrollment authorization process. This URL is temporarily valid and allows access to the holder's environment for account linking.

ofEnrollmentIdstring required

Unique identifier of the enrollment in the Open Finance Brasil context. This ID is generated and managed by the account holder and represents the established link in the Open Finance ecosystem.

idempotencyKeystring

Unique idempotency key to ensure duplicate operations are not processed. This UUID helps prevent accidental double-processing of enrollment authorization requests and maintains data consistency across retries.

isFavoriteboolean required

Indicates if this enrollment is marked as favorite by the user. Allows the user to quickly identify their preferred account link among multiple available enrollments for payment initiation.

ofConsentIdstring

Internal identifier of the Open Finance Brasil consent linked to this enrollment. This ID references the consent object that manages authorization permissions and payment details for this account link.

Example response

{
  "brandId": "66f4d9e296f18bc4606e1618",
  "journeySessionId": "f362a873-c127-4122-b711-a37b24a36914",
  "redirectUrl": "https://meuapp.exemplo.com/callback",
  "directoryCallback": true,
  "authorizationDevice": "Dispositivo de autorização",
  "data": {
    "enrollment": {
      "loggedUser": {
        "document": {
          "identification": "11122233344",
          "rel": "CPF"
        }
      },
      "businessEntity": {
        "document": {
          "identification": "00000000000191",
          "rel": "CNPJ"
        }
      },
      "debtorAccount": {
        "accountType": "CACC",
        "ispb": "00000000",
        "issuer": "0001",
        "number": "0001234567"
      },
      "enrollmentName": "Nome Dispositivo"
    },
    "riskSignals": {
      "deviceId": "00aa11bb22cc33dd",
      "osVersion": "14",
      "userTimeZoneOffset": "-03",
      "language": "pt",
      "accountTenure": "2023-08-20",
      "geolocation": {
        "type": "FINE"
      },
      "antennaInformation": "CellIdentityLte:{ mCi=2******60 mPci=274 mTac=5***1 mEarfcn=9510 mBands=[28] mBandwidth=2147483647 mMcc=724 mMnc=10 mAlphaLong=VIVO mAlphaShort=VIVO mAdditionalPlmns={} mCsgInfo=null}, CellIdentityLte:{ mCi=1*****01 mPci=361 mTac=3***6 mEarfcn=9410 mBands=[28] mBandwidth=2147483647 mMcc=724 mMnc=03 mAlphaLong=TIMBRASIL mAlphaShort=TIMBRASIL mAdditionalPlmns={} mCsgInfo=null}",
      "integrity": {
        "appRecognitionVerdict": "PLAY_RECOGNIZED",
        "deviceRecognitionVerdict": "['MEETS_DEVICE_INTEGRITY']"
      }
    }
  },
  "paymentInitiationApi": "ENROLLMENTS_V2",
  "createdAt": "2024-01-01T20:32:44.581Z",
  "updatedAt": "2024-01-01T20:32:44.581Z",
  "deletedAt": "2024-01-01T20:32:44.581Z",
  "journeySession": {
    "createdAt": "2024-01-01T20:32:44.581Z",
    "updatedAt": "2024-01-01T20:32:44.581Z",
    "deletedAt": "2024-01-01T20:32:44.581Z",
    "settings": [
      {
        "key": "JOURNEY_RULES"
      }
    ]
  },
  "authorizationUrl": "https://example.com",
  "ofEnrollment": {
    "authorization_url": "https://example.com",
    "redirect_uri": "https://example.com",
    "consentTerm": 0.123,
    "riskSignals": {
      "deviceId": "00aa11bb22cc33dd",
      "osVersion": "14",
      "userTimeZoneOffset": "-03",
      "language": "pt",
      "accountTenure": "2023-08-20",
      "geolocation": {
        "type": "FINE"
      },
      "antennaInformation": "CellIdentityLte:{ mCi=2******60 mPci=274 mTac=5***1 mEarfcn=9510 mBands=[28] mBandwidth=2147483647 mMcc=724 mMnc=10 mAlphaLong=VIVO mAlphaShort=VIVO mAdditionalPlmns={} mCsgInfo=null}, CellIdentityLte:{ mCi=1*****01 mPci=361 mTac=3***6 mEarfcn=9410 mBands=[28] mBandwidth=2147483647 mMcc=724 mMnc=03 mAlphaLong=TIMBRASIL mAlphaShort=TIMBRASIL mAdditionalPlmns={} mCsgInfo=null}"
    },
    "organizationLogo": "https://example.com",
    "status": "AWAITING_RISK_SIGNALS",
    "loggedUser": {
      "document": {
        "rel": "CPF"
      }
    }
  },
  "idempotencyKey": "783336ed-c1dd-40a8-b0b7-2e884b6221c2",
  "httpCalls": [
    {
      "response": {
        "status": "200",
        "statusText": "OK"
      },
      "createdAt": "2024-01-01T20:32:44.581Z",
      "updatedAt": "2024-01-01T20:32:44.581Z",
      "deletedAt": "2024-01-01T20:32:44.581Z"
    }
  ],
  "brand": {
    "createdAt": "2024-01-01T20:32:44.581Z",
    "updatedAt": "2024-01-01T20:32:44.581Z",
    "deletedAt": "2024-01-01T20:32:44.581Z",
    "settings": {
      "brandId": "66f4d9e296f18bc4606e1618",
      "sandboxUsersTests": [
        {
          "username": "usuario_teste",
          "password": "senha1234",
          "document": {
            "identification": "11122233344",
            "rel": "CPF"
          }
        }
      ],
      "updatedAt": "2024-09-26T03:51:03.642Z",
      "uptimeStatus": "OPERATIONAL",
      "id": "66f4da2796f18bc4606e2b87"
    }
  },
  "ofConsent": {
    "authorization_url": "https://example.com",
    "status": "AWAITING_AUTHORISATION",
    "organizationLogo": "https://example.com",
    "redirect_uri": "https://example.com",
    "consentTerm": 0.123,
    "creditor": {
      "cpfCnpj": "12345678000199",
      "personType": "PESSOA_JURIDICA",
      "name": "João da Silva Santos"
    },
    "loggedUser": {
      "document": {
        "identification": "11122233344",
        "rel": "CPF"
      }
    },
    "payment": {
      "type": "PIX",
      "date": "2025-08-05",
      "currency": "BRL",
      "amount": "10.00",
      "details": {
        "localInstrument": "DICT",
        "proxy": "usuario@ficticio.com",
        "creditorAccount": {
          "ispb": "00000000",
          "issuer": "0001",
          "number": "0001234567",
          "accountType": "CACC"
        }
      }
    },
    "rejectionReason": {
      "code": "TEMPO_EXPIRADO_AUTORIZACAO"
    }
  },
  "ofPayments": [
    {
      "localInstrument": "DICT",
      "payment": {
        "currency": "BRL",
        "amount": "1.00"
      },
      "creditorAccount": {
        "number": "1234567890",
        "accountType": "CACC",
        "ispb": "12345678",
        "issuer": "1774"
      },
      "cnpjInitiator": "13935893000109",
      "proxy": "cliente-a00001@pix.bcb.gov.br",
      "endToEndId": "E13935893202511021042TKe1h8bM2FO",
      "authorisationFlow": "FIDO_FLOW",
      "creationDateTime": "2025-11-13T21:41:49Z",
      "debtorAccount": {
        "ispb": "12345678",
        "issuer": "0001",
        "number": "969139",
        "accountType": "CACC"
      },
      "paymentId": "9917ab8f-e134-490b-b2b5-59ecd4e0abd0",
      "status": "ACSC",
      "statusUpdateDateTime": "2025-11-13T21:41:56Z",
      "id": "EXAMPLE-PAYMENT-ID-0002"
    }
  ],
  "ofConsentId": "EXAMPLE-CONSENT-ID-0001"
}