Registration and Offers

Flow Overview

Two processes happen in parallel: the credit analysis (starts automatically upon registration) and KYC verification (the customer completes at their own pace).

Customer lifecycle

Status	Description
`creating`	Registration received, co-owner enrichment in progress
`pending_kyc`	Ready to submit documentation and biometrics
`under_review`	Documents submitted, analysis in progress
`active`	Verified and eligible for credit offers
`denied`	Permanently blocked

Create a Customer

Register the business with Dinie. The external_id field is the internal reference from your system that you will use to identify the customer.

const customer = await client.customers.create({
  externalId: "partner-ref-123",      // Your internal ID
  cpf: "123.456.789-00",              // Business owner's CPF
  email: "joao@example.com",
  phone: "+5511999999999",
  cnpj: "12.345.678/0001-90",
});

console.log(customer.status); // "creating"
console.log(customer.kyc);    // Pending verification items

Info: If you create a customer with the same CPF/CNPJ and external_id, the API returns the existing customer (idempotent). A 409 error only occurs when the external_id differs for the same CPF/CNPJ.

Upload Documents

Upload the documents listed in the customer.kyc array right after registration to speed up the analysis:

import fs from "fs";

await client.customers.uploadKycAttachment(customer.id, {
  requirementId: "company_document",
  evidenceType: "ccmei",
  attachmentType: "file",
  file: fs.createReadStream("/path/to/ccmei.pdf"),
});

await client.customers.uploadKycAttachment(customer.id, {
  requirementId: "identity_12345678900",
  evidenceType: "cnh",
  attachmentType: "front",
  file: fs.createReadStream("/path/to/cnh-front.jpg"),
});

Supported formats: PDF, JPEG, PNG. Only upload the types listed in the kyc array -- unrecognized types return a 422 error.

Info: Selfies cannot be uploaded via the API. They are captured by the customer during the biometrics session. See the KYC Requirements guide for details on the full flow.

Receive the Credit Offer

The credit analysis starts automatically upon registration. When Dinie generates an offer, you receive the credit_offer.available webhook:

app.post("/webhooks/dinie", express.raw({ type: "application/json" }), (req, res) => {
  const event = client.webhooks.unwrap(req.body.toString(), req.headers);

  if (event.type === "credit_offer.available") {
    const externalId = event.data.external_id;
    const amount = event.data.approved_amount;
    notifyCustomer(externalId, `Credit offer of R$ ${amount} available`);
  }

  res.sendStatus(200);
});

Next Step

When the customer has active status and an available offer, they are ready to proceed. Continue to the Simulation and Loan Origination guide.