Sign in

v1

latestOpenAPI 3.0.22026-08-061464031.4 MB
Enrollments (Brazil)

Enroll a new user device

▶️ Usage

With the Enroll a new user device method, you can begin the enrollment process for a new device to allow for Biometric Pix payments.

🚧 Create a customer first

Before you can enroll a user device, you must first create a customer.

post/payments/br/enrollments/

Request body

type'open_finance_biometric_pix' required

The type of enrollment. For 🇧🇷 Brazil's OFPI, can be either:

  • open_finance_biometric_pix: For biometric payments using the PIX network.

Example request

{
  "type": "open_finance_biometric_pix",
  "details": {
    "customer": "c860809f-e96d-4d50-9588-f40ffab77302",
    "institution": "600f1b4a-1ef9-4f89-b341-1a35f0c32cc0",
    "name": "600f1b4a-Mobile",
    "callback_url": "https://example.com/enrollment-in-progress",
    "platform": "ANDROID"
  }
}

Response

OK (Created)

idstring uuid

Belvo's unique identifier of the enrollment.

created_bystring uuid

The Belvo ID of the merchant that created the enrollment.

created_atstring date-time

The ISO-8601 timestamp of when the data point was created in Belvo's database.

updated_atstring date-time

The ISO-8601 timestamp of when the enrollment was last updated.

external_idstring uuid

An additional unique identifier for the resource for internal purposes.

{% admonition type="success" name="Highly Recommended" %} We recommend using this field to store your own unique identifier for each resource (customer, bank account, payment intent, or enrollment). This can be useful for tracking the resource in your system and for debugging purposes. {% /admonition %}

type'open_finance_biometric_pix'

The type of enrollment. For 🇧🇷 Brazil's OFPI, can be either:

  • open_finance_biometric_pix: For biometric payments using the PIX network.
status'PENDING' | 'SUCCEEDED' | 'CANCELED' | 'FAILED'

The status of the device enrollment. Can be either:

  • PENDING: The enrollment is pending.
  • SUCCEEDED: The enrollment was successful.
  • CANCELED: The enrollment was canceled.
  • FAILED: The enrollment failed.
status_reason_codestring nullable

A machine-readable code providing the reason for a failed enrollment. Only present when status is FAILED.

Possible values:

  • send_risk_signals_failed: Enrollment rejected due to timeout while sending risk signals.
  • redirection_to_institution_failed: Enrollment rejected because the redirection to the institution was not successfully completed.
  • biometric_registration_failed: Enrollment rejected because the biometric registration was not completed successfully within the allowed time.
  • too_many_device_registration_attempts: Enrollment rejected due to too many failed device registration attempts.
  • rejected_by_user: Enrollment was manually cancelled by the user.
  • device_not_supports_biometric_authentication: Enrollment rejected because the device is not compatible with biometric authentication.
  • institution_infra_failed: Enrollment rejected due to infrastructure issues at the institution.
  • blocked_by_institution_security_policy: Enrollment rejected due to the institution security policy decisions based on risk evaluation.
  • redirection_back_from_institution_failed: Enrollment rejected because the redirection back from the institution was not successfully completed.
  • biometric_validation_error: Enrollment failed due to biometric validation or public key registration issues.
  • rejected_other: Enrollment rejected for an unspecified reason.
  • canceled_due_to_expiration: Enrollment canceled due to expiration of validity period.
status_reason_messagestring nullable

A human-readable message providing more details about the reason for a failed enrollment. Only present when status is FAILED. Please see status_reason_code for example messages for each reason code.

metadataobject

Optional and customizable object where you can provide any additional key-value pairs for your internal purposes. For example, an internal reference number for the enrollment.

⚠️ Note: You can only provide up to 50 keys (keys can have up to 50 characters each and each value can be up to 500 characters). We do not support nested objects, only ASCII values.

Example response

{
  "id": "600f1b4a-1ef9-4f89-b341-1a35f0c32cc0",
  "created_by": "dbdce1e9-d089-4b7d-804b-51dd07748202",
  "created_at": "2024-11-26T11:20:57.389056Z",
  "updated_at": "2024-11-26T11:20:57.389058Z",
  "external_id": "4b8a81a0-e33c-45a6-8567-479efb105f73",
  "type": "open_finance_biometric_pix",
  "status": "PENDING",
  "status_reason_code": "biometric_registration_failed",
  "status_reason_message": "Enrollment rejected because the biometric registration was not completed successfully within the allowed time.",
  "details": {
    "status": "AWAITING_ACCOUNT_HOLDER_VALIDATION",
    "customer": "c860809f-e96d-4d50-9588-f40ffab77302",
    "institution": "600f1b4a-1ef9-4f89-b341-1a35f0c32cc0",
    "platform": "ANDROID",
    "name": "600f1b4a-Mobile",
    "callback_url": "https://example.com/enrollment-in-progress",
    "redirect_url": "https://www.acmecorp.com/checkout/3487321",
    "risk_signals": "******",
    "expires_at": "2026-12-26T11:20:57.389056Z"
  },
  "metadata": {
    "internal_reference_id": "GGq73487w2"
  }
}