BIOMETRIC_VERIFICATION requirement, and it is the one item a person always does live, on their own phone or computer.
A verification belongs to your organization. Once approved, it serves every affiliation attempt with that provider, of every merchant of your organization where that person is the contact. The person does it once.
The flow
The onboarding link runs the same flow for you: it starts the verification when the person reaches the step, opens the same capture page in a new tab, and resumes when the person comes back.Start a verification
string
required
The provider that runs the capture:
CELCOIN.string
required
The CPF of the merchant’s contact; punctuation is ignored. Anyone else answers
400.string
Where the provider sends the person when the capture ends. The result never comes from this redirect: read it from the webhook or from
GET /v1/biometric-verifications/{id}.Hand the capture to the person
verification_url is the provider’s own capture page, returned as is. Open it on the person’s phone or send it to them, in a browser tab or window of its own: the provider’s page does not run inside a frame, which is why the onboarding link opens it in a new tab too. In an app, open it in the browser or in an in-app browser tab, not in a webview the app frames. It works until verification_url_expires_at; read that field rather than assuming a lifetime.
Status
APPROVED, REPROVED and EXPIRED are terminal. biometric-verification.status-changed fires when a verification leaves PENDING.
One pending verification per person
Only one verification per person and provider can be pending in your organization. A secondPOST answers 409 with details.pending_verification_id: follow that one instead. Every merchant the person is the contact of can read it, whichever merchant started it. Ten minutes after its verification_url_expires_at, a new one can be started.
Reuse before you start
Before asking the person for a capture, read the merchant’sBIOMETRIC_VERIFICATION requirement: SATISFIED means an approved verification already serves it. The list shows the person’s verifications across your organization:
cURL
APPROVED verification in the list does not settle the requirement on its own, since an approved one can have to be redone; go by the requirement’s status. An organization sees every verification it owns, for itself and for its merchants (company_id narrows the list to one merchant). A merchant using its own API key sees the verifications of its contact within its organization.
A biometric verification never crosses organizations. Documents may be shared, but a face capture is reused only inside the organization that collected it.
The evidence package
For the owner organization,GET /v1/biometric-verifications/{id} adds evidence_download_url and evidence_download_url_expires_at: a signed link, valid for one hour, to the provider’s evidence package, the PDF that records the liveness and face-match session. It is null until the package is stored, in the list, and for a merchant reading a verification of its contact.
When an approved verification has to be redone
Rinne keeps its own copy of every approved selfie: it fetches the file from the provider right after the approval and stores it as the verification’sSELFIE document, so the selfie is reused from Rinne’s store from then on. Rarely, the approval arrives but the file does not, and Rinne keeps retrying for a day. If the selfie is still not stored a day after approved_at, Rinne sets the BIOMETRIC_VERIFICATION requirement back to PENDING and fires affiliation.requirements-changed. Start a new verification, or let the onboarding link ask for it. A verification whose selfie is stored is never redone this way.