Payments Web SDK

Belvo's Payments Web SDK provides you with the essential methods to:

  • enroll a device for biometric payments.
  • collect biometric data.
  • authorize payments with biometric data.

Installation

In your node project, install the Payments Web SDK using the following command:

npm install @belvo/payments-atoms

Biometric Pix Methods

collectEnrollmentInformation

The collectEnrollmentInfromation(accountTenure) method extracts essential details about the user's device (called risk signals) that are required to enroll the device in the user's institution and for each subsequent payment request for that user.

BelvoPaymentsAtoms.biometricPix.collectEnrollmentInformation(accountTenure)
BelvoPaymentsAtoms.biometricPix.collectEnrollmentInformation("2023-06-23")
import { biometricPix } from '@belvo/payments-atoms'

const enrollmentInformation = await biometricPix.collectEnrollmentInformation('2023-06-23')
ParameterTypeDescriptionExample
accountTenurestringThe date when your user created an account with your application.2023-06-23

The method returns an enrollmentInformation object, which should be converted to a JSON-compliant object and sent to your backend in order to be used in the POST Create a new device enrollment API call.

{
  deviceId: 'visitorUniqueId',
  osVersion: 'Unix 7.1.0',
  userTimeZoneOffset: -03:00,
  language: 'pt-BR',
  screenDimensions: {
    height: 768,
    width: 1024
  },
  accountTenure: '2023-06-23'
}
{
    "deviceId": "visitorUniqueId",
    "osVersion": "Unix 7.1.0",
    "userTimeZoneOffset": "-03:00",
    "language": "pt-BR",
    "screenDimensions": {
        "height": 768,
        "width": 1024
    },
    "accountTenure": "2023-06-23"
}

requestEnrollmentConfirmation

The requestEnrollmentConfirmation(biometricRegistrationRequest) prompts your user to provide their biometric data to complete the enrollment process.

BelvoPaymentsAtoms.biometricPix.requestEnrollmentConfirmation(biometricRegistrationRequest)
BelvoPaymentsAtoms.biometricPix.requestEnrollmentConfirmation({
  rp: { id: 'belvo.com' },
  user:
  {
    id: 'Y2JhM2ZiMDQtNWIwZi00NGMwLTgzZDgtZmVkN2RiOThkOGQ5',
    name: 'Mock User',
    displayName: 'My First Biometric User'
  },
  challenge: 'R3JlZXRpbmdzIGZyb20gQmVsdm8h',
  pubKeyCredParams: [{ alg: -7, type: 'public-key' }],
  attestation: 'direct',
  accountTenure: '2023-06-23',
  timeout: 6000
})
import { biometricPix } from '@belvo/payments-atoms'

const biometricRegistrationRequest = { // Your backend provides this information from the fido_options you received in a webhook
    rp: { id: 'belvo.com' },
    user:
    {
        id: 'Y2JhM2ZiMDQtNWIwZi00NGMwLTgzZDgtZmVkN2RiOThkOGQ5',
        name: 'Mock User',
        displayName: 'My First Biometric User'
    },
    challenge: 'R3JlZXRpbmdzIGZyb20gQmVsdm8h',
    pubKeyCredParams: [{ alg: -7, type: 'public-key' }],
    attestation: 'direct',
    accountTenure: '2023-06-23',
    timeout: 6000
}

const enrollmentConfirmation = BelvoPaymentsAtoms.biometricPix.requestEnrollmentConfirmation(biometricRegistrationRequest)

ParameterTypeDescription
biometricRegistrationRequestobjectThe fido_options object you received in the ENROLLMENTS webhook.

The method returns an biometricRegistrationConfirmation object, which should be converted to a JSON-compliant object and sent to your backend in order to be used in the PATCH Complete device enrollment request.

{
    authenticatorAttachment: 'cross-platform',
    id: '447Q86f_XlFK0IBPVdf-giJUXs8pwmFCqqp0M3Q2PqM',
    rawId: 'base64',
    response: {
        attestationObject: 'YXR0ZXN0YXRpb25PYmplY3RFeGFtcGxlSGVyZQ==',
        clientDataJson: 'YXR0ZXN0YXRpb25PYmplY3RFeGFtcGxl',
        type: 'public-key'
    }
}
{
    "authenticatorAttachment": "cross-platform",
    "id": "447Q86f_XlFK0IBPVdf-giJUXs8pwmFCqqp0M3Q2PqM",
    "rawId": "base64",
    "response": {
        "attestationObject": "YXR0ZXN0YXRpb25PYmplY3RFeGFtcGxlSGVyZQ==",
        "clientDataJson": "YXR0ZXN0YXRpb25PYmplY3RFeGFtcGxl",
        "type": "public-key"
    }
}

requestPaymentAuthorization

The requestPaymentAuthorization(biometricPaymentRequest) request prompts your user for their biometric data to complete a payment request.

BelvoPaymentsAtoms.biometricPix.requestPaymentAuthorization(biometricPaymentRequest)
BelvoPaymentsAtoms.biometricPix.requestPaymentAuthorization({
    challenge: 'Y2hhbGxlbmdl',
    timeout: 6000,
    rpId: 'belvo.com',
    allowCredentials: [
        {
            id: 'cmF3LWlk', // Base64
            type: 'public-key',
        }
    ],
    userVerification: 'required',

})
import { biometricPix } from '@belvo/payments-atoms'
ParameterTypeDescription
biometricPaymentRequestobjectThe fido_options object you in the 201 Response when creating a Biometric Pix Payment Intent.

The method returns an biometricAuthorization object, which should be converted to a JSON-compliant object and sent to your backend in order to be used in the POST Complete a Biometric Pix payment intent.

{
    id: 'clqMgwfufRpefli1rsHGlA07aD4OyKsQgOs0W-AGY2Y',
    rawId: 'clqMgwfufRpefli1rsHGlA07aD4OyKsQgOs0W+AGY2Y=',
    response: {
        authenticatorData: '5KApO/fUiPm1wr+26+0W4DGfCJIhocf+sRR4PEKSdIoFAAAAAA==',
        clientDataJSON: 'eyJ0eXBlIjoid2ViYXV0aG4uZ2V0IiwiY2hhbGxlbmdlIjoiWTJoaGJHeGxibWRsTWciLCJvcmlnaW4iOiJodHRwczovL2Jpby5sb2NhbGhvc3QiLCJjcm9zc09yaWdpbiI6ZmFsc2UsIm90aGVyX2tleXNfY2FuX2JlX2FkZGVkX2hlcmUiOiJkbyBub3QgY29tcGFyZSBjbGllbnREYXRhSlNPTiBhZ2FpbnN0IGEgdGVtcGxhdGUuIFNlZSBodHRwczovL2dvby5nbC95YWJQZXgifQ==',
        signature: 'MEUCIQDA/05vXnhaZtNK3a0LFK/MGhOKZzHhmuY0o4+k1K+bUAIgCQmZVK7pGJiHfNczwRfqR4IgnqrvqCVO7/+WfQ5YNjI=',
        userHandle: 'dXNlcmlk'
    },
    type: 'public-key'
}
{
  "id": "clqMgwfufRpefli1rsHGlA07aD4OyKsQgOs0W-AGY2Y",
  "rawId": "clqMgwfufRpefli1rsHGlA07aD4OyKsQgOs0W+AGY2Y=",
  "response": {
    "authenticatorData": "5KApO/fUiPm1wr+26+0W4DGfCJIhocf+sRR4PEKSdIoFAAAAAA==",
    "clientDataJSON": "eyJ0eXBlIjoid2ViYXV0aG4uZ2V0IiwiY2hhbGxlbmdlIjoiWTJoaGJHeGxibWRsTWciLCJvcmlnaW4iOiJodHRwczovL2Jpby5sb2NhbGhvc3QiLCJjcm9zc09yaWdpbiI6ZmFsc2UsIm90aGVyX2tleXNfY2FuX2JlX2FkZGVkX2hlcmUiOiJkbyBub3QgY29tcGFyZSBjbGllbnREYXRhSlNPTiBhZ2FpbnN0IGEgdGVtcGxhdGUuIFNlZSBodHRwczovL2dvby5nbC95YWJQZXgifQ==",
    "signature": "MEUCIQDA/05vXnhaZtNK3a0LFK/MGhOKZzHhmuY0o4+k1K+bUAIgCQmZVK7pGJiHfNczwRfqR4IgnqrvqCVO7/+WfQ5YNjI=",
    "userHandle": "dXNlcmlk"
  },
  "type": "public-key"
}