Pix on File Device Linking (Enrollment)

Pix on File (JSR) works by establishing a device linking using FIDO2/WebAuthn authentication.

1. Merchant initiates enrollment with customer to elect a bank from authorized banks
2. Customer elects the bank and authorize the enrollment
3. Customer returns to the merchant app and completes FIDO2 credential registration
4. Enrollment becomes active and ready for payments

Requirements

• EBANX Account
• API Credentials - Ensure you have your EBANX integration Key. If not, complete the Merchant Signup Form.

Device Linking Initiation (Enrollment)

Device Linking begins with an enrollment request towards customer's banking institution. A list of available banking institutions can be recovered using the Bank List request. The following parameters are used for Device Linking requests:

Parameter	Requirement	Description
integration_key	Required	Your integration key
payment_type_code	Required	Must be pix-jsr
operation	Required	Must be enrollment
notification_url	Required	URL to callback after customer authorizes the device linking
intent_url	Required	Deeplink URL that will be used to trigger user redirection after confirming the device linking in the banking application (return to merchant app)
enrollment.country	Required	Must be br
enrollment.merchant_enrollment_code	Required	Unique enrollment code
enrollment.email	Required	Customer e-mail
enrollment.identification_type	Required	Either cpf or cnpj
enrollment.identification	Required	Customer document
enrollment.account_details.bank_id	Required	A valid bank_id
enrollment.fidoOptions.platform	Required	Platform where the enrollment is being initiated (ANDROID, IOS, BROWSER, CROSS_PLATFORM).
enrollment.risk_signals	Required	Refer to the Risk Signals section.

Sample Request

curl -X POST \
  --location 'https://sandbox.ebanx.com/ws/userenrollment' \
  --header 'Content-Type: application/json' \
  --data '{
    "integration_key": "your_ebanx_integration_key",
    "payment_type_code": "pix-jsr",
    "operation": "enrollment",
    "notification_url": "{notification_url_backend}",
    "intent_url": "{intent_url_device}",
    "enrollment": {
        "country": "br",
        "merchant_enrollment_code": "{merchant_enrollment_code}",
        "email": "{user_email}",
        "identification_type": "{cpf/cnpj}",
        "identification": "{document_number}",
        "account_details": {
        "bank_id": "{bank_id}"
        },
        "fidoOptions": {
        "platform": "{ENUM}",
        "risk_signals": {}
        }
    }
}'

A successful request will return a JSON response like the one below, containing a redirect URL that will lead the customer to their banking application.

{
  "status": "SUCCESS",
  "redirect_url": "{redirect_url}",
  "enrollment": {
    "merchant_enrollment_code": "{merchant_enrollment_code}",
    "status": "pending"
  }
}

Callback

Once the customer authorizes the device linking in their banking application, the banking application will redirect the user to the {intent_url} informed in the original request and a status update will be sent to the {notification_url} informed in the initiation step with additional information that will be required to complete the FIDO2/WebAuthn authentication in the device.

{
  "enrollment": {
    "merchant_enrollment_code": "{merchant_enrollment_code}",
    "status": "pending",
    "registrationOptions": {
      "rp": {
        "id": "string",
        "name": "string"
      },
      "user": {
        "id": "string",
        "name": "string",
        "displayName": "string"
      },
      "challenge": "string",
      "pubKeyCredParams": [
        {
          "alg": -7,
          "type": "public-key"
        }
      ],
      "timeout": 0,
      "excludeCredentials": [
        {
          "id": "string",
          "type": "public-key"
        }
      ],
      "authenticatorSelection": {
        "authenticatorAttachment": "platform",
        "userVerification": "discouraged",
        "requireResidentKey": true,
        "residentKey": "string"
      },
      "attestation": "none",
      "attestationFormats": [
        "packed",
        "tpm",
        "android-key",
        "android-safetynet",
        "fido-u2f",
        "apple",
        "none"
      ],
      "extensions": {}
    }
  }
}

Device Linking Confirmation

The last stage for Device Linking is processing the results of the FIDO2/WebAuthn authentication performed by the customer after confirming the enrollment and returning to the merchant application. It requires the following parameters:

Parameter	Requirement	Description
integration_key	Required	Your integration key
payment_type_code	Required	Must be pix-jsr
operation	Required	Must be authentication
enrollment.merchant_enrollment_code	Required	Unique enrollment code
enrollment.authentication.id	Required	Credential ID (Base64 encoded)
enrollment.authentication.rawId	Required	Credential ID in ArrayBuffer format (Base64 encoded)
enrollment.authentication.type	Required	Must be public-key
enrollment.authentication.response.clientDataJSON	Required	Client data in JSON, encoded in Base64url
enrollment.authentication.response.attestationObject	Required	Authenticator attestation data, encoded in Base64url

Sample Request

curl -X POST \
  --location 'https://sandbox.ebanx.com/ws/userenrollment/authentication' \
  --header 'Content-Type: application/json' \
  --data '{
    "integration_key": "your_ebanx_integration_key",
    "payment_type_code": "pix-jsr",
    "operation": "authentication",
    "enrollment": {
        "merchant_enrollment_code": "{merchant_enrollment_code}",
        "authentication": {
            "id": "{fido_id}",
            "rawId": "{fido_raw_id}",
            "type": "public-key",
            "response": {
                "clientDataJSON": "{client_data_json}",
                "attestationObject": "{attestation_object}"
            }
        }
    }
}'

A successful request will return a JSON response like the one below, confirming that the enrollment is ready to be used for payment processing.

{
  "status": "SUCCESS",
  "enrollment": {
    "merchant_enrollment_code": "{merchant_enrollment_code}",
    "status": "confirmed"
  }
}