Skip to content

Dinie API (2026-03-01)

Embedded credit API for Dinie partners. Enables customer registration, credit offer management, loan origination, and event delivery via webhooks.

Download OpenAPI description
Overview
Languages
Servers
Mock server
https://dinie.nexaedge.dev/_mock/apis/openapi
Production
https://api.dinie.com.br/v3
Sandbox
https://sandbox.api.dinie.com.br/v3

Authentication

OAuth2 Client Credentials authentication and API key management.

Each client_id / client_secret pair represents an access credential. Exchange the credentials for a JWT token via POST /auth/token and send the token as Bearer in all requests. The token expires in 1 hour.

You can create multiple credentials for different environments and revoke them individually.

Operations

Customers

The Customer resource (cust_) represents a credit borrower on the platform. The lifecycle follows: registration → KYC document submission → review → activation.

Two processes happen in parallel:

  • Credit analysis — starts automatically upon registration
  • KYC verification — the customer completes at their own pace
Operations
Webhooks

Credit Offers

The CreditOffer resource (co_) represents a pre-approved credit offer for a customer. Offers are automatically generated by Dinie when a Customer reaches the active status. You are notified via the credit_offer.available webhook.

Operations
Webhooks

Loans

The Loan resource (ln_) represents a loan originated from a CreditOffer and its Simulation. After creation, the loan goes through several automated steps until disbursement.

Operations
Webhooks

Lifecycle

processing → contract_generated → awaiting_signatures → signed → disbursing → active → finished
                                                                                     ↘ cancelled
                                                                                     ↘ error
StatusDescriptionRequired Action
processingLoan created, processingWait
contract_generatedCCB generatedWait
awaiting_signaturesContract ready for signingRedirect customer to signing_url
signedContract signedWait for disbursement
disbursingDisbursement in progressWait
activeDisbursement completed, installments generatedTrack payments
finishedAll installments paid
cancelledCancelled before disbursement
errorProcessing errorContact support

Example: Create and Track

# 1. Create the loan from the simulation
loan = client.loans.create(
  credit_offer_id: "co_550e8400...",
  simulation_id: "sim_550e8400...",
  installments: 6,
  installments_value: "4550.00",
  first_due_date: "2026-04-15"
)
# loan.id => "ln_550e8400..."
# loan.status => "processing"

# 2. After loan.awaiting_signatures webhook
loan = client.loans.retrieve(loan.id)
# loan.signing_url => ClickSign URL for signing
# Redirect the customer to this URL

# 3. After loan.active webhook — check installments
transactions = client.loans.list_transactions(loan.id)
transactions.data.each do |tx|
  puts "#{tx.due_date}: R$ #{tx.amount_due} (#{tx.status})"
end
# 2026-04-15: R$ 4550.00 (pending)
# 2026-05-15: R$ 4550.00 (pending)
# ...

Transactions (tx_)

Each active loan has transactions of type installment — one per installment. Track payments via queries or webhooks.

StatusDescription
pendingInstallment not yet due
paidInstallment fully paid
partially_paidPartial payment received
overdueInstallment overdue (days_overdue > 0)

Webhooks

EventWhen it fires
loan.createdLoan created, processing started
loan.contract_generatedCCB generated, ccb_number available
loan.awaiting_signaturessigning_url available for the customer
loan.signedContract signed by all parties
loan.disbursingDisbursement via Pix started
loan.activeDisbursement completed, installments created
loan.payment_receivedInstallment payment detected
loan.finishedAll installments paid
loan.cancelledLoan cancelled
loan.errorProcessing error

Simulate a loan

Request

Simulates a loan scenario for a specific credit offer. The customer can simulate multiple times with different amounts and terms before committing. The simulation is synchronous and returns installment amounts, fees, and total cost. The result is persisted and can be referenced when creating the loan via simulation_id. Only the latest simulation is valid for contracting (Last Write Record).

Security
bearerAuth
Path
credit_offer_idstring(CreditOfferId)^co_[0-9a-f]{32}$required
Example: co_550e8400e29b41d4a716446655440000
Headers
Idempotency-Keystring

Unique string for idempotent POST requests. Cached for 24 hours.

Bodyapplication/jsonrequired
requested_amountstring^\d+\.\d{2}$required

Requested loan amount

Example: "25000.00"
installment_countinteger>= 1required

Number of installments for the simulation

Example: 12
curl -X POST https://api.dinie.com.br/v3/credit-offers/co_550e8400e29b41d4a716446655440000/simulations \
  -H "Authorization: Bearer $DINIE_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "requested_amount": "25000.00",
    "installment_count": 12
  }'

Responses

Simulation created

Bodyapplication/json
idstring(SimulationId)^sim_[0-9a-f]{32}$required
credit_offer_idstring(CreditOfferId)^co_[0-9a-f]{32}$required
requested_amountstring^\d+\.\d{2}$required

Amount requested by the partner

Example: "25000.00"
amountstring^\d+\.\d{2}$required

Net amount to be received by the customer

Example: "24250.00"
interest_amountstring^\d+\.\d{2}$required

Total interest amount

Example: "2750.00"
fees_amountstring^\d+\.\d{2}$required

Total fees amount

Example: "300.00"
iof_amountstring^\d+\.\d{2}$required

IOF tax amount

Example: "450.00"
total_loan_amountstring^\d+\.\d{2}$required

Total loan amount (principal + interest + fees + IOF)

Example: "27500.00"
interest_percentagenumberrequired

Monthly interest rate (percentage)

Example: 3.5
cet_percentagenumberrequired

Total effective cost (annual percentage)

Example: 4.12
number_of_installmentsintegerrequired

Number of installments

Example: 12
installments_valuestring^\d+\.\d{2}$required

Amount per installment

Example: "2291.67"
first_due_datestring(date)required

Due date of the first installment

Example: "2026-04-03"
created_atstring(date-time)required
Response
application/json
{ "id": "sim_550e8400e29b41d4a716446655440001", "credit_offer_id": "co_550e8400e29b41d4a716446655440000", "requested_amount": "25000.00", "amount": "24250.00", "interest_amount": "2750.00", "fees_amount": "300.00", "iof_amount": "450.00", "total_loan_amount": "27500.00", "interest_percentage": 3.5, "cet_percentage": 4.12, "number_of_installments": 12, "installments_value": "2291.67", "first_due_date": "2026-04-03", "created_at": "2026-03-04T10:30:00Z" }

Create a loan

Request

Creates a loan from a credit offer and a simulation accepted by the customer. The partner must include the simulation_id to link the agreed terms. The loan starts with status processing and automatically progresses through the cycle: contract_generatedawaiting_signaturessigneddisbursingactive. The signing_url for signing the CCB contract will be made available via webhook loan.contract_generated. Track the lifecycle via loan.* webhooks.

Security
bearerAuth
Headers
Idempotency-Keystring

Unique string for idempotent POST requests. Cached for 24 hours.

Bodyapplication/jsonrequired
credit_offer_idstring(CreditOfferId)^co_[0-9a-f]{32}$required
simulation_idstring(SimulationId)^sim_[0-9a-f]{32}$required
installmentsinteger>= 1required

Number of installments

Example: 12
installments_valuestring^\d+\.\d{2}$required

Amount per installment

Example: "2291.67"
first_due_datestring(date)required

Due date of the first installment

Example: "2026-04-03"
curl -X POST https://api.dinie.com.br/v3/loans \
  -H "Authorization: Bearer $DINIE_API_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: unique-request-id" \
  -d '{
    "credit_offer_id": "co_550e8400e29b41d4a716446655440000",
    "simulation_id": "sim_550e8400e29b41d4a716446655440001",
    "installments": 12,
    "installments_value": "2291.67",
    "first_due_date": "2026-04-03"
  }'

Responses

Loan created

Headers
Locationstring
Example: "/v3/loans/ln_550e8400e29b41d4a716446655440001"
Bodyapplication/json
idstring(LoanId)^ln_[0-9a-f]{32}$required
credit_offer_idstring(CreditOfferId)^co_[0-9a-f]{32}$required
simulation_idstring(SimulationId)^sim_[0-9a-f]{32}$required
customer_idstring(CustomerId)^cust_[0-9a-f]{32}$required
statusstringrequired
Enum ValueDescription
processing

Loan request received, credit analysis in progress

contract_generated

CCB contract generated, ready for signatures

awaiting_signatures

Contract sent to customer for electronic signature

signed

Customer signed the contract, awaiting disbursement

disbursing

Funds are being transferred to the customer

active

Loan disbursed, installments are being collected

finished

All installments paid, loan completed

cancelled

Loan cancelled before disbursement

error

An error occurred during processing

requested_amountstring(Money)^\d+\.\d{2}$required

Decimal encoded as a string with exactly 2 decimal places (BRL).

net_amountstring or null^\d+\.\d{2}$required

Net amount after fees. Null until calculated.

iofstring or null^\d+\.\d{2}$required
service_feestring or null^\d+\.\d{2}$required
interest_ratenumber or nullrequired

Monthly interest rate (percentage)

cetnumber or nullrequired

Total effective cost (annual percentage)

total_amountstring(Money)^\d+\.\d{2}$required

Decimal encoded as a string with exactly 2 decimal places (BRL).

installments_valuestring^\d+\.\d{2}$required

Amount per installment

Example: "2291.67"
first_due_datestring(date)required

Due date of the first installment

Example: "2026-04-03"
number_of_installmentsintegerrequired
ccb_numberstring or nullrequired

CCB contract number. Null until the contract is generated.

disbursement_methodstring or nullrequired

Disbursement method (e.g., pix). Null until disbursement.

signing_urlstring or null(uri)required

ClickSign widget URL. Present only during contract_generated and awaiting_signatures.

created_atstring(date-time)required
updated_atstring(date-time)required
Response
application/json
{ "id": "ln_550e8400e29b41d4a716446655440001", "credit_offer_id": "co_550e8400e29b41d4a716446655440000", "simulation_id": "sim_550e8400e29b41d4a716446655440001", "customer_id": "cust_550e8400e29b41d4a716446655440000", "status": "processing", "requested_amount": "25000.00", "net_amount": null, "iof": null, "service_fee": null, "interest_rate": 3.5, "cet": 4.25, "total_amount": "30000.00", "installments_value": "2291.67", "first_due_date": "2026-04-03", "number_of_installments": 12, "ccb_number": null, "disbursement_method": null, "signing_url": null, "created_at": "2026-03-04T11:00:00Z", "updated_at": "2026-03-04T11:00:00Z" }

Retrieve a loan

Request

Returns the complete loan object with all lifecycle details. Important fields vary by status: signing_url is populated when awaiting_signatures, ccb_number when contract_generated, and net_amount after disbursement. Use together with loan.* webhooks to keep your system synchronized.

Security
bearerAuth
Path
loan_idstring(LoanId)^ln_[0-9a-f]{32}$required
Example: ln_550e8400e29b41d4a716446655440000
curl https://api.dinie.com.br/v3/loans/ln_550e8400e29b41d4a716446655440001 \
  -H "Authorization: Bearer $DINIE_API_TOKEN"

Responses

Loan details

Bodyapplication/json
idstring(LoanId)^ln_[0-9a-f]{32}$required
credit_offer_idstring(CreditOfferId)^co_[0-9a-f]{32}$required
simulation_idstring(SimulationId)^sim_[0-9a-f]{32}$required
customer_idstring(CustomerId)^cust_[0-9a-f]{32}$required
statusstringrequired
Enum ValueDescription
processing

Loan request received, credit analysis in progress

contract_generated

CCB contract generated, ready for signatures

awaiting_signatures

Contract sent to customer for electronic signature

signed

Customer signed the contract, awaiting disbursement

disbursing

Funds are being transferred to the customer

active

Loan disbursed, installments are being collected

finished

All installments paid, loan completed

cancelled

Loan cancelled before disbursement

error

An error occurred during processing

requested_amountstring(Money)^\d+\.\d{2}$required

Decimal encoded as a string with exactly 2 decimal places (BRL).

net_amountstring or null^\d+\.\d{2}$required

Net amount after fees. Null until calculated.

iofstring or null^\d+\.\d{2}$required
service_feestring or null^\d+\.\d{2}$required
interest_ratenumber or nullrequired

Monthly interest rate (percentage)

cetnumber or nullrequired

Total effective cost (annual percentage)

total_amountstring(Money)^\d+\.\d{2}$required

Decimal encoded as a string with exactly 2 decimal places (BRL).

installments_valuestring^\d+\.\d{2}$required

Amount per installment

Example: "2291.67"
first_due_datestring(date)required

Due date of the first installment

Example: "2026-04-03"
number_of_installmentsintegerrequired
ccb_numberstring or nullrequired

CCB contract number. Null until the contract is generated.

disbursement_methodstring or nullrequired

Disbursement method (e.g., pix). Null until disbursement.

signing_urlstring or null(uri)required

ClickSign widget URL. Present only during contract_generated and awaiting_signatures.

created_atstring(date-time)required
updated_atstring(date-time)required
Response
application/json
{ "id": "ln_550e8400e29b41d4a716446655440001", "credit_offer_id": "co_550e8400e29b41d4a716446655440000", "simulation_id": "sim_550e8400e29b41d4a716446655440001", "customer_id": "cust_550e8400e29b41d4a716446655440000", "status": "active", "requested_amount": "25000.00", "net_amount": "24250.00", "iof": "450.00", "service_fee": "300.00", "interest_rate": 3.5, "cet": 4.25, "total_amount": "30000.00", "installments_value": "2291.67", "first_due_date": "2026-04-03", "number_of_installments": 12, "ccb_number": "CCB-2026-001234", "disbursement_method": "pix", "signing_url": null, "created_at": "2026-03-04T11:00:00Z", "updated_at": "2026-03-05T14:00:00Z" }

List loan transactions

Request

Lists the transactions (installments) of a loan. Each transaction represents an installment with due date (due_date), original amount, paid amount, and payment status (pending, paid, overdue). This is a read-only endpoint — payments are processed outside the API. Track payments in real time via webhook loan.payment_received.

Security
bearerAuth
Path
loan_idstring(LoanId)^ln_[0-9a-f]{32}$required
Example: ln_550e8400e29b41d4a716446655440000
Query
starting_afterstring

Prefixed ID of the last item from the previous page.

limitinteger[ 1 .. 100 ]

Number of items to return. Min: 1, Max: 100.

Default 25
curl "https://api.dinie.com.br/v3/loans/ln_550e8400e29b41d4a716446655440001/transactions?limit=25" \
  -H "Authorization: Bearer $DINIE_API_TOKEN"

Responses

List of transactions

Bodyapplication/json
dataArray of objects(Transaction)required
data[].​idstring(TransactionId)^tx_[0-9a-f]{32}$required
data[].​loan_idstring(LoanId)^ln_[0-9a-f]{32}$required
data[].​typestringrequired
Value"installment"
data[].​due_datestring(date)required
Example: "2026-04-03"
data[].​statusstringrequired
Enum ValueDescription
pending

Payment not yet due or awaiting payment

paid

Full payment received

overdue

Payment overdue without full settlement

partially_paid

Partial payment received

data[].​amount_duestring(Money)^\d+\.\d{2}$required

Decimal encoded as a string with exactly 2 decimal places (BRL).

data[].​amount_paidstring(Money)^\d+\.\d{2}$required

Decimal encoded as a string with exactly 2 decimal places (BRL).

data[].​amount_remainingstring(Money)^\d+\.\d{2}$required

Decimal encoded as a string with exactly 2 decimal places (BRL).

data[].​principalstring(Money)^\d+\.\d{2}$required

Decimal encoded as a string with exactly 2 decimal places (BRL).

data[].​intereststring(Money)^\d+\.\d{2}$required

Decimal encoded as a string with exactly 2 decimal places (BRL).

data[].​feesstring(Money)^\d+\.\d{2}$required

Decimal encoded as a string with exactly 2 decimal places (BRL).

data[].​days_overdueinteger>= 0required
data[].​paid_atstring or null(date-time)required
data[].​created_atstring(date-time)required
data[].​updated_atstring(date-time)required
has_morebooleanrequired
Response
application/json
{ "data": [ { "id": "tx_550e8400e29b41d4a716446655440000", "loan_id": "ln_550e8400e29b41d4a716446655440001", "type": "installment", "due_date": "2026-04-03", "status": "paid", "amount_due": "2500.00", "amount_paid": "2500.00", "amount_remaining": "0.00", "principal": "2083.33", "interest": "375.00", "fees": "41.67", "days_overdue": 0, "paid_at": "2026-04-03T10:00:00Z", "created_at": "2026-03-04T11:00:00Z", "updated_at": "2026-04-03T10:00:00Z" }, { "id": "tx_660e8400e29b41d4a716446655440001", "loan_id": "ln_550e8400e29b41d4a716446655440001", "type": "installment", "due_date": "2026-05-03", "status": "pending", "amount_due": "2500.00", "amount_paid": "0.00", "amount_remaining": "2500.00", "principal": "2083.33", "interest": "375.00", "fees": "41.67", "days_overdue": 0, "paid_at": null, "created_at": "2026-03-04T11:00:00Z", "updated_at": "2026-03-04T11:00:00Z" } ], "has_more": true }

Loan createdWebhook

Request

Fires when the loan is created via POST /loans from an accepted offer. Includes the loan, offer, and customer IDs, as well as the requested amount and number of installments. The loan starts with processing status. Use it to register the loan in your system.

Security
bearerAuth
Bodyapplication/jsonrequired
typestringrequired

Event type identifier

Value"loan.created"
timestampstring(date-time)required

When the event occurred

dataobjectrequired
data.​idstring(LoanId)^ln_[0-9a-f]{32}$required
data.​credit_offer_idstring(CreditOfferId)^co_[0-9a-f]{32}$required
data.​customer_idstring(CustomerId)^cust_[0-9a-f]{32}$required
data.​statusstringrequired
Value"processing"
data.​requested_amountstring(Money)^\d+\.\d{2}$required

Decimal encoded as a string with exactly 2 decimal places (BRL).

data.​number_of_installmentsintegerrequired

Responses

Event received

Loan contract generatedWebhook

Request

Fires when the CCB (Cedula de Credito Bancario) contract is generated by Dinie. Includes the ClickSign signing_url for digital contract signing. Use it to present the signing link to the customer in your flow.

Security
bearerAuth
Bodyapplication/jsonrequired
typestringrequired

Event type identifier

Enum"loan.contract_generated""loan.awaiting_signatures"
timestampstring(date-time)required

When the event occurred

dataobjectrequired
data.​idstring(LoanId)^ln_[0-9a-f]{32}$required
data.​statusstringrequired
Enum"contract_generated""awaiting_signatures"
data.​signing_urlstring(uri)required

ClickSign widget URL for customer signing

Responses

Event received

Loan awaiting signaturesWebhook

Request

Fires when the CCB contract is sent to ClickSign and awaits the customer's signature. Includes the updated signing_url. Use it to resend the signing link to the customer or display a reminder if the signature has not yet been completed.

Security
bearerAuth
Bodyapplication/jsonrequired
typestringrequired

Event type identifier

Enum"loan.contract_generated""loan.awaiting_signatures"
timestampstring(date-time)required

When the event occurred

dataobjectrequired
data.​idstring(LoanId)^ln_[0-9a-f]{32}$required
data.​statusstringrequired
Enum"contract_generated""awaiting_signatures"
data.​signing_urlstring(uri)required

ClickSign widget URL for customer signing

Responses

Event received

Loan signedWebhook

Request

Fires when the CCB contract is fully signed by all signatories on ClickSign. Includes the registered contract ccb_number. The next step is automatic disbursement. Use it to confirm to the customer that the contract has been successfully signed.

Security
bearerAuth
Bodyapplication/jsonrequired
typestringrequired

Event type identifier

Value"loan.signed"
timestampstring(date-time)required

When the event occurred

dataobjectrequired
data.​idstring(LoanId)^ln_[0-9a-f]{32}$required
data.​statusstringrequired
Value"signed"
data.​ccb_numberstringrequired
Example: "CCB-2026-001234"

Responses

Event received

Loan disbursingWebhook

Request

Fires when Dinie initiates the fund transfer to the customer's account. Includes the disbursement method used (e.g., pix). The transfer may take a few minutes. Use it to inform the customer that the amount is being transferred.

Security
bearerAuth
Bodyapplication/jsonrequired
typestringrequired

Event type identifier

Value"loan.disbursing"
timestampstring(date-time)required

When the event occurred

dataobjectrequired
data.​idstring(LoanId)^ln_[0-9a-f]{32}$required
data.​statusstringrequired
Value"disbursing"
data.​disbursement_methodstringrequired
Example: "pix"

Responses

Event received

Loan activeWebhook

Request

Fires when the disbursement is confirmed and the loan enters the repayment phase. Includes the requested amount (requested_amount) and the net amount received (net_amount). Use it to confirm to the customer that the funds have been credited and present the installment schedule.

Security
bearerAuth
Bodyapplication/jsonrequired
typestringrequired

Event type identifier

Value"loan.active"
timestampstring(date-time)required

When the event occurred

dataobjectrequired
data.​idstring(LoanId)^ln_[0-9a-f]{32}$required
data.​statusstringrequired
Value"active"
data.​requested_amountstring(Money)^\d+\.\d{2}$required

Decimal encoded as a string with exactly 2 decimal places (BRL).

data.​net_amountstring(Money)^\d+\.\d{2}$required

Decimal encoded as a string with exactly 2 decimal places (BRL).

Responses

Event received

Loan payment receivedWebhook

Request

Fires when an installment payment is recorded for the loan. Includes the amount paid, payment date, and corresponding installment number. Use it to update the outstanding balance in your system and notify the customer about the payment confirmation.

Security
bearerAuth
Bodyapplication/jsonrequired
typestringrequired

Event type identifier

Value"loan.payment_received"
timestampstring(date-time)required

When the event occurred

dataobjectrequired
data.​idstring(LoanId)^ln_[0-9a-f]{32}$required
data.​statusstringrequired
Value"active"
data.​paymentobjectrequired
data.​payment.​amountstring(Money)^\d+\.\d{2}$required

Decimal encoded as a string with exactly 2 decimal places (BRL).

data.​payment.​paid_atstring(date-time)required
data.​payment.​installment_numberintegerrequired

Responses

Event received

Loan finishedWebhook

Request

Fires when all loan installments are paid off and the contract is closed. Includes the loan ID and finished status. Use it to mark the loan as completed in your system and check if new credit offers are available.

Security
bearerAuth
Bodyapplication/jsonrequired
typestringrequired

Event type identifier

Enum"loan.finished""loan.cancelled""loan.error"
timestampstring(date-time)required

When the event occurred

dataobjectrequired
data.​idstring(LoanId)^ln_[0-9a-f]{32}$required
data.​statusstringrequired
Enum"finished""cancelled""error"

Responses

Event received

Loan cancelledWebhook

Request

Fires when the loan is cancelled before disbursement is completed. Includes the loan ID and cancelled status. Use it to update the status in your system and inform the customer. The original credit offer may still be available for a new request.

Security
bearerAuth
Bodyapplication/jsonrequired
typestringrequired

Event type identifier

Enum"loan.finished""loan.cancelled""loan.error"
timestampstring(date-time)required

When the event occurred

dataobjectrequired
data.​idstring(LoanId)^ln_[0-9a-f]{32}$required
data.​statusstringrequired
Enum"finished""cancelled""error"

Responses

Event received

Loan errorWebhook

Request

Fires when an unrecoverable error occurs in the loan, such as a disbursement failure or contract generation error. Includes the error code and message in the error field. Use it to alert your team, log the issue, and inform the customer about the situation.

Security
bearerAuth
Bodyapplication/jsonrequired
typestringrequired

Event type identifier

Enum"loan.finished""loan.cancelled""loan.error"
timestampstring(date-time)required

When the event occurred

dataobjectrequired
data.​idstring(LoanId)^ln_[0-9a-f]{32}$required
data.​statusstringrequired
Enum"finished""cancelled""error"

Responses

Event received

Webhooks

Manage the endpoints that receive event notifications (we_). Dinie follows the Standard Webhooks specification.

Events for each resource are documented in the Customers, Credit Offers, and Loans sections. This section covers only endpoint management.

Operations