{
"openapi": "3.1.1",
"info": {
"title": "Dinie API",
"version": "2026-03-01",
"description": "Embedded credit API for Dinie partners. Enables customer registration,\ncredit offer management, loan origination, and event delivery\nvia webhooks.\n",
"contact": {
"name": "Dinie API Support",
"url": "https://docs.dinie.com",
"email": "api@dinie.com.br"
},
"license": {
"name": "Proprietary"
},
"x-logo": {
"url": "/img/dinie-logo.svg"
},
"x-dark-logo": {
"url": "/img/dinie-logo-dark.svg"
}
},
"servers": [
{
"url": "https://api.dinie.com/api/v3",
"description": "Production"
},
{
"url": "https://api-dev.dinietech.io/api/v3",
"description": "Sandbox"
}
],
"security": [
{
"bearerAuth": []
}
],
"tags": [
{
"name": "Authentication",
"description": "OAuth2 Client Credentials authentication and API key management.\nExchange your credentials for a JWT token via `POST /auth/token` and send it as Bearer in all requests.\n",
"x-displayName": "Authentication"
},
{
"name": "Customers",
"description": "Register customers, submit KYC documents, and track verification status.\nSee the [Registration & Offers](/guides/customer-registration) guide for the complete flow.\n",
"x-displayName": "Customers"
},
{
"name": "Credit Offers",
"description": "Pre-approved credit offers and loan simulations for eligible customers.\nSee the [Simulation & Contracting](/guides/credit-workflow) guide for the complete flow.\n",
"x-displayName": "Credit Offers"
},
{
"name": "Loans",
"description": "Create loans from credit offers, track contract signing, disbursement, and installment payments.\nSee the [Simulation & Contracting](/guides/credit-workflow) guide for the complete flow.\n",
"x-displayName": "Loans"
},
{
"name": "Webhooks",
"description": "Manage the endpoints that receive event notifications.\nDinie follows the [Standard Webhooks](https://www.standardwebhooks.com/) specification.\n",
"x-displayName": "Webhooks"
}
],
"paths": {
"/auth/token": {
"post": {
"operationId": "createToken",
"summary": "Get an access token",
"description": "POST /auth/token
\n\nExchange partner credentials for an access token via OAuth2 Client Credentials",
"tags": [
"Authentication"
],
"security": [
{
"oauth2": []
}
],
"requestBody": {
"required": true,
"content": {
"application/x-www-form-urlencoded": {
"schema": {
"type": "object",
"required": [
"grant_type"
],
"properties": {
"grant_type": {
"type": "string",
"const": "client_credentials"
}
}
},
"example": {
"grant_type": "client_credentials"
}
}
}
},
"responses": {
"200": {
"description": "Token issued successfully",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/TokenResponse"
},
"example": {
"access_token": "dinie_at_eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJkaW5pZV9jaV81NTBlODQwMGUyOWI0MWQ0YTcxNjQ0NjY1NTQ0MDAwMCIsImV4cCI6MTcwOTU1NTYwMH0.abc123",
"token_type": "bearer",
"expires_in": 3600
}
}
}
},
"400": {
"description": "Bad request",
"content": {
"application/problem+json": {
"schema": {
"type": "object",
"required": [
"type",
"title",
"status",
"detail",
"code"
],
"properties": {
"type": {
"type": "string",
"const": "https://docs.dinie.com/errors/invalid-request"
},
"title": {
"type": "string",
"const": "Invalid Request"
},
"status": {
"type": "integer",
"const": 400
},
"detail": {
"type": "string"
},
"code": {
"type": "string",
"enum": [
"missing_grant_type",
"unsupported_grant_type",
"invalid_content_type"
],
"x-enumDescriptions": {
"missing_grant_type": "`grant_type` parameter is missing",
"unsupported_grant_type": "`grant_type` is not `client_credentials`",
"invalid_content_type": "`Content-Type` is not `application/x-www-form-urlencoded`"
}
}
}
},
"examples": {
"missing_grant_type": {
"summary": "`grant_type` parameter is missing",
"value": {
"type": "https://docs.dinie.com/errors/invalid-request",
"title": "Invalid Request",
"status": 400,
"detail": "`grant_type` parameter is missing",
"code": "missing_grant_type"
}
},
"unsupported_grant_type": {
"summary": "`grant_type` is not `client_credentials`",
"value": {
"type": "https://docs.dinie.com/errors/invalid-request",
"title": "Invalid Request",
"status": 400,
"detail": "`grant_type` is not `client_credentials`",
"code": "unsupported_grant_type"
}
},
"invalid_content_type": {
"summary": "`Content-Type` is not `application/x-www-form-urlencoded`",
"value": {
"type": "https://docs.dinie.com/errors/invalid-request",
"title": "Invalid Request",
"status": 400,
"detail": "`Content-Type` is not `application/x-www-form-urlencoded`",
"code": "invalid_content_type"
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/ClientCredentialUnauthorized",
"description": "Authentication failed"
},
"429": {
"$ref": "#/components/responses/RateLimited",
"description": "Rate limit exceeded"
},
"500": {
"$ref": "#/components/responses/InternalError",
"description": "Internal server error"
}
},
"x-codeSamples": [
{
"lang": "curl",
"source": "curl -X POST https://api.dinie.com/api/v3/auth/token \\\n -u \"$DINIE_CLIENT_ID:$DINIE_CLIENT_SECRET\" \\\n -H \"Content-Type: application/x-www-form-urlencoded\" \\\n -d \"grant_type=client_credentials\"\n"
},
{
"lang": "Python",
"source": "from dinie import Dinie\n\n# The SDK handles token exchange automatically.\n# Just initialize with your credentials:\nclient = Dinie(\n client_id=\"dinie_ci_abc123\",\n client_secret=\"dinie_cs_live_xyz789\"\n)\n\n# To obtain a token manually (rarely needed):\ntoken = client.auth.create_token()\n\nprint(token.access_token) # \"dinie_at_eyJhbG...\"\nprint(token.expires_in) # 3600\n"
},
{
"lang": "Node.js",
"source": "const { Dinie } = require(\"dinie\");\n\n// The SDK handles token exchange automatically.\n// Just initialize with your credentials:\nconst client = new Dinie({\n clientId: \"dinie_ci_abc123\",\n clientSecret: \"dinie_cs_live_xyz789\",\n});\n\n// To obtain a token manually (rarely needed):\nconst token = await client.auth.createToken();\n\nconsole.log(token.accessToken); // \"dinie_at_eyJhbG...\"\nconsole.log(token.expiresIn); // 3600\n"
},
{
"lang": "Ruby",
"source": "require \"dinie\"\n\n# The SDK handles token exchange automatically.\n# Just initialize with your credentials:\nclient = Dinie::Client.new(\n client_id: \"dinie_ci_abc123\",\n client_secret: \"dinie_cs_live_xyz789\"\n)\n\n# To obtain a token manually (rarely needed):\ntoken = client.auth.create_token\n\nputs token.access_token # \"dinie_at_eyJhbG...\"\nputs token.expires_in # 3600\n"
}
]
}
},
"/auth/credentials": {
"post": {
"operationId": "createCredential",
"summary": "Create an API key",
"description": "POST /auth/credentials
\n\nCreate a new API credential pair",
"tags": [
"Authentication"
],
"parameters": [
{
"$ref": "#/components/parameters/IdempotencyKey"
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CreateCredentialRequest"
},
"example": {
"name": "Chave de Produção",
"expires_at": 1803945600
}
}
}
},
"responses": {
"201": {
"description": "Credential created",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CredentialWithSecret"
},
"example": {
"id": "dinie_ci_live_550e8400e29b41d4a71644",
"client_id": "dinie_ci_live_550e8400e29b41d4a71644",
"name": "Chave de Produção",
"status": "active",
"client_secret": "dinie_cs_live_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6",
"expires_at": 1803945600,
"created_at": 1772791200,
"updated_at": 1772877600,
"last_used_at": null
}
}
}
},
"400": {
"description": "Bad request",
"content": {
"application/problem+json": {
"schema": {
"type": "object",
"required": [
"type",
"title",
"status",
"detail",
"code"
],
"properties": {
"type": {
"type": "string",
"const": "https://docs.dinie.com/errors/invalid-request"
},
"title": {
"type": "string",
"const": "Invalid Request"
},
"status": {
"type": "integer",
"const": 400
},
"detail": {
"type": "string"
},
"code": {
"type": "string",
"enum": [
"invalid_content_type",
"malformed_body"
],
"x-enumDescriptions": {
"invalid_content_type": "`Content-Type` is not `application/json`",
"malformed_body": "Request body is not valid JSON"
}
}
}
},
"examples": {
"invalid_content_type": {
"summary": "`Content-Type` is not `application/json`",
"value": {
"type": "https://docs.dinie.com/errors/invalid-request",
"title": "Invalid Request",
"status": 400,
"detail": "`Content-Type` is not `application/json`",
"code": "invalid_content_type"
}
},
"malformed_body": {
"summary": "Request body is not valid JSON",
"value": {
"type": "https://docs.dinie.com/errors/invalid-request",
"title": "Invalid Request",
"status": 400,
"detail": "Request body is not valid JSON",
"code": "malformed_body"
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/BearerTokenUnauthorized",
"description": "Authentication failed"
},
"422": {
"description": "Validation failed",
"content": {
"application/problem+json": {
"schema": {
"type": "object",
"required": [
"type",
"title",
"status",
"detail",
"code"
],
"properties": {
"type": {
"type": "string",
"const": "https://docs.dinie.com/errors/validation-failed"
},
"title": {
"type": "string",
"const": "Validation Failed"
},
"status": {
"type": "integer",
"const": 422
},
"detail": {
"type": "string"
},
"code": {
"type": "string",
"const": "missing_required_field",
"x-enumDescriptions": {
"missing_required_field": "`name` is missing"
}
}
}
},
"examples": {
"missing_required_field": {
"summary": "`name` is missing",
"value": {
"type": "https://docs.dinie.com/errors/validation-failed",
"title": "Validation Failed",
"status": 422,
"detail": "`name` is missing",
"code": "missing_required_field"
}
}
}
}
}
},
"429": {
"$ref": "#/components/responses/RateLimited",
"description": "Rate limit exceeded"
},
"500": {
"$ref": "#/components/responses/InternalError",
"description": "Internal server error"
}
},
"x-codeSamples": [
{
"lang": "curl",
"source": "curl -X POST https://api.dinie.com/api/v3/auth/credentials \\\n -H \"Authorization: Bearer $DINIE_API_TOKEN\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"name\": \"Chave de Produção\",\n \"expires_at\": 1803945600\n }'\n"
},
{
"lang": "Python",
"source": "from dinie import Dinie\n\nclient = Dinie(\n client_id=\"dinie_ci_abc123\",\n client_secret=\"dinie_cs_live_xyz789\"\n)\n\n# Create a new API credential\ncredential = client.auth.create_credential(\n name=\"Chave de Produção\",\n expires_at=1803945600\n)\n\nprint(credential.client_id) # \"dinie_ci_550e8400...\"\nprint(credential.client_secret) # \"dinie_cs_live_a1b2c3...\"\n# ⚠️ Store the client_secret securely -- shown only once!\n"
},
{
"lang": "Node.js",
"source": "const { Dinie } = require(\"dinie\");\n\nconst client = new Dinie({\n clientId: \"dinie_ci_abc123\",\n clientSecret: \"dinie_cs_live_xyz789\",\n});\n\n// Create a new API credential\nconst credential = await client.auth.createCredential({\n name: \"Chave de Produção\",\n expiresAt: 1803945600,\n});\n\nconsole.log(credential.clientId); // \"dinie_ci_550e8400...\"\nconsole.log(credential.clientSecret); // \"dinie_cs_live_a1b2c3...\"\n// Store the clientSecret securely -- shown only once!\n"
},
{
"lang": "Ruby",
"source": "require \"dinie\"\n\nclient = Dinie::Client.new(\n client_id: \"dinie_ci_abc123\",\n client_secret: \"dinie_cs_live_xyz789\"\n)\n\n# Create a new API credential\ncredential = client.auth.create_credential(\n name: \"Chave de Produção\",\n expires_at: 1803945600\n)\n\nputs credential.client_id # \"dinie_ci_550e8400...\"\nputs credential.client_secret # \"dinie_cs_live_a1b2c3...\"\n# Store the client_secret securely -- shown only once!\n"
}
]
},
"get": {
"operationId": "listCredentials",
"summary": "List API keys",
"description": "GET /auth/credentials
\n\nList all API keys",
"tags": [
"Authentication"
],
"responses": {
"200": {
"description": "List of credentials",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"data",
"has_more"
],
"properties": {
"data": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Credential"
}
},
"has_more": {
"type": "boolean"
}
}
},
"example": {
"data": [
{
"id": "dinie_ci_live_550e8400e29b41d4a71644",
"client_id": "dinie_ci_live_550e8400e29b41d4a71644",
"name": "Chave de Produção",
"status": "active",
"expires_at": 1803945600,
"created_at": 1772791200,
"updated_at": 1772877600,
"last_used_at": 1772877600
}
],
"has_more": false
}
}
}
},
"401": {
"$ref": "#/components/responses/BearerTokenUnauthorized",
"description": "Authentication failed"
},
"429": {
"$ref": "#/components/responses/RateLimited",
"description": "Rate limit exceeded"
},
"500": {
"$ref": "#/components/responses/InternalError",
"description": "Internal server error"
}
},
"x-codeSamples": [
{
"lang": "curl",
"source": "curl https://api.dinie.com/api/v3/auth/credentials \\\n -H \"Authorization: Bearer $DINIE_API_TOKEN\"\n"
},
{
"lang": "Python",
"source": "from dinie import Dinie\n\nclient = Dinie(\n client_id=\"dinie_ci_abc123\",\n client_secret=\"dinie_cs_live_xyz789\"\n)\n\n# List all API credentials\ncredentials = client.auth.list_credentials()\n\nfor cred in credentials.data:\n print(f\"{cred.name}: {cred.status}\")\n # \"Chave de Produção: active\"\n"
},
{
"lang": "Node.js",
"source": "const { Dinie } = require(\"dinie\");\n\nconst client = new Dinie({\n clientId: \"dinie_ci_abc123\",\n clientSecret: \"dinie_cs_live_xyz789\",\n});\n\n// List all API credentials\nconst credentials = await client.auth.listCredentials();\n\nfor (const cred of credentials.data) {\n console.log(`${cred.name}: ${cred.status}`);\n // \"Chave de Produção: active\"\n}\n"
},
{
"lang": "Ruby",
"source": "require \"dinie\"\n\nclient = Dinie::Client.new(\n client_id: \"dinie_ci_abc123\",\n client_secret: \"dinie_cs_live_xyz789\"\n)\n\n# List all API credentials\ncredentials = client.auth.list_credentials\n\ncredentials.data.each do |cred|\n puts \"#{cred.name}: #{cred.status}\"\n # \"Chave de Produção: active\"\nend\n"
}
]
}
},
"/auth/credentials/{client_id}": {
"delete": {
"operationId": "revokeCredential",
"summary": "Revoke an API key",
"description": "DELETE /auth/credentials/{client_id}
\n\nRevoke an API key immediately and permanently",
"tags": [
"Authentication"
],
"parameters": [
{
"name": "client_id",
"in": "path",
"required": true,
"schema": {
"$ref": "#/components/schemas/ApiClientId"
},
"description": "ID of the credential to revoke"
}
],
"responses": {
"204": {
"description": "Credential revoked (empty body)"
},
"401": {
"$ref": "#/components/responses/BearerTokenUnauthorized",
"description": "Authentication failed"
},
"404": {
"description": "Resource not found",
"content": {
"application/problem+json": {
"schema": {
"type": "object",
"required": [
"type",
"title",
"status",
"detail",
"code"
],
"properties": {
"type": {
"type": "string",
"const": "https://docs.dinie.com/errors/not-found"
},
"title": {
"type": "string",
"const": "Not Found"
},
"status": {
"type": "integer",
"const": 404
},
"detail": {
"type": "string"
},
"code": {
"type": "string",
"const": "credential_not_found",
"x-enumDescriptions": {
"credential_not_found": "`client_id` does not exist or does not belong to this partner"
}
}
}
},
"examples": {
"credential_not_found": {
"summary": "`client_id` does not exist or does not belong to this partner",
"value": {
"type": "https://docs.dinie.com/errors/not-found",
"title": "Not Found",
"status": 404,
"detail": "`client_id` does not exist or does not belong to this partner",
"code": "credential_not_found"
}
}
}
}
}
},
"409": {
"description": "Conflict",
"content": {
"application/problem+json": {
"schema": {
"type": "object",
"required": [
"type",
"title",
"status",
"detail",
"code"
],
"properties": {
"type": {
"type": "string",
"const": "https://docs.dinie.com/errors/conflict"
},
"title": {
"type": "string",
"const": "Conflict"
},
"status": {
"type": "integer",
"const": 409
},
"detail": {
"type": "string"
},
"code": {
"type": "string",
"const": "last_active_credential",
"x-enumDescriptions": {
"last_active_credential": "Cannot revoke the last active credential"
}
}
}
},
"examples": {
"last_active_credential": {
"summary": "Cannot revoke the last active credential",
"value": {
"type": "https://docs.dinie.com/errors/conflict",
"title": "Conflict",
"status": 409,
"detail": "Cannot revoke the last active credential",
"code": "last_active_credential"
}
}
}
}
}
},
"429": {
"$ref": "#/components/responses/RateLimited",
"description": "Rate limit exceeded"
},
"500": {
"$ref": "#/components/responses/InternalError",
"description": "Internal server error"
}
},
"x-codeSamples": [
{
"lang": "curl",
"source": "curl -X DELETE https://api.dinie.com/api/v3/auth/credentials/dinie_ci_live_550e8400e29b41d4a71644 \\\n -H \"Authorization: Bearer $DINIE_API_TOKEN\"\n"
},
{
"lang": "Python",
"source": "from dinie import Dinie\n\nclient = Dinie(\n client_id=\"dinie_ci_abc123\",\n client_secret=\"dinie_cs_live_xyz789\"\n)\n\n# Revoke a compromised credential\nclient.auth.revoke_credential(\"dinie_ci_live_550e8400e29b41d4a71644\")\n# 204 No Content -- credential revoked immediately\n"
},
{
"lang": "Node.js",
"source": "const { Dinie } = require(\"dinie\");\n\nconst client = new Dinie({\n clientId: \"dinie_ci_abc123\",\n clientSecret: \"dinie_cs_live_xyz789\",\n});\n\n// Revoke a compromised credential\nawait client.auth.revokeCredential(\"dinie_ci_live_550e8400e29b41d4a71644\");\n// 204 No Content -- credential revoked immediately\n"
},
{
"lang": "Ruby",
"source": "require \"dinie\"\n\nclient = Dinie::Client.new(\n client_id: \"dinie_ci_abc123\",\n client_secret: \"dinie_cs_live_xyz789\"\n)\n\n# Revoke a compromised credential\nclient.auth.revoke_credential(\"dinie_ci_live_550e8400e29b41d4a71644\")\n# 204 No Content -- credential revoked immediately\n"
}
]
}
},
"/customers": {
"post": {
"operationId": "createCustomer",
"summary": "Register a customer",
"description": "POST /customers
\n\nRegister a new customer",
"tags": [
"Customers"
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CreateCustomerRequest"
},
"example": {
"cpf": "123.456.789-00",
"cnpj": "12.345.678/0001-90",
"email": "joao@example.com",
"phone": "+5511999999999",
"external_id": "partner-ref-123"
}
}
}
},
"responses": {
"201": {
"description": "Customer created",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Customer"
},
"example": {
"id": "cust_550e8400e29b41d4a716446655440000",
"status": "creating",
"cpf": "123.456.789-00",
"cnpj": "12.345.678/0001-90",
"name": null,
"email": "joao@example.com",
"phone": "+5511999999999",
"trading_name": null,
"external_id": "partner-ref-123",
"created_at": 1709546400,
"updated_at": 1709632800
}
}
}
},
"400": {
"description": "Bad request",
"content": {
"application/problem+json": {
"schema": {
"type": "object",
"required": [
"type",
"title",
"status",
"detail",
"code"
],
"properties": {
"type": {
"type": "string",
"const": "https://docs.dinie.com/errors/invalid-request"
},
"title": {
"type": "string",
"const": "Invalid Request"
},
"status": {
"type": "integer",
"const": 400
},
"detail": {
"type": "string"
},
"code": {
"type": "string",
"enum": [
"invalid_content_type",
"malformed_body"
],
"x-enumDescriptions": {
"invalid_content_type": "`Content-Type` is not `application/json`",
"malformed_body": "Request body is not valid JSON"
}
}
}
},
"examples": {
"invalid_content_type": {
"summary": "`Content-Type` is not `application/json`",
"value": {
"type": "https://docs.dinie.com/errors/invalid-request",
"title": "Invalid Request",
"status": 400,
"detail": "`Content-Type` is not `application/json`",
"code": "invalid_content_type"
}
},
"malformed_body": {
"summary": "Request body is not valid JSON",
"value": {
"type": "https://docs.dinie.com/errors/invalid-request",
"title": "Invalid Request",
"status": 400,
"detail": "Request body is not valid JSON",
"code": "malformed_body"
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/BearerTokenUnauthorized",
"description": "Authentication failed"
},
"409": {
"description": "Conflict",
"content": {
"application/problem+json": {
"schema": {
"type": "object",
"required": [
"type",
"title",
"status",
"detail",
"code"
],
"properties": {
"type": {
"type": "string",
"const": "https://docs.dinie.com/errors/conflict"
},
"title": {
"type": "string",
"const": "Conflict"
},
"status": {
"type": "integer",
"const": 409
},
"detail": {
"type": "string"
},
"code": {
"type": "string",
"const": "customer_already_exists",
"x-enumDescriptions": {
"customer_already_exists": "Same CPF/CNPJ already registered under this partner with a different `external_id`"
}
}
}
},
"examples": {
"customer_already_exists": {
"summary": "Same CPF/CNPJ already registered under this partner with a different `external_id`",
"value": {
"type": "https://docs.dinie.com/errors/conflict",
"title": "Conflict",
"status": 409,
"detail": "Same CPF/CNPJ already registered under this partner with a different `external_id`",
"code": "customer_already_exists"
}
}
}
}
}
},
"422": {
"description": "Validation failed",
"content": {
"application/problem+json": {
"schema": {
"type": "object",
"required": [
"type",
"title",
"status",
"detail",
"code"
],
"properties": {
"type": {
"type": "string",
"const": "https://docs.dinie.com/errors/validation-failed"
},
"title": {
"type": "string",
"const": "Validation Failed"
},
"status": {
"type": "integer",
"const": 422
},
"detail": {
"type": "string"
},
"code": {
"type": "string",
"enum": [
"missing_required_field",
"invalid_cpf",
"invalid_cnpj",
"invalid_email",
"invalid_phone"
],
"x-enumDescriptions": {
"missing_required_field": "`cpf` is missing (required for all customers)",
"invalid_cpf": "CPF fails check-digit validation",
"invalid_cnpj": "CNPJ fails check-digit validation",
"invalid_email": "Email format is invalid",
"invalid_phone": "Phone format is invalid (expected E.164 with +55 country code)"
}
}
}
},
"examples": {
"missing_required_field": {
"summary": "`cpf` is missing (required for all customers)",
"value": {
"type": "https://docs.dinie.com/errors/validation-failed",
"title": "Validation Failed",
"status": 422,
"detail": "`cpf` is missing (required for all customers)",
"code": "missing_required_field"
}
},
"invalid_cpf": {
"summary": "CPF fails check-digit validation",
"value": {
"type": "https://docs.dinie.com/errors/validation-failed",
"title": "Validation Failed",
"status": 422,
"detail": "CPF fails check-digit validation",
"code": "invalid_cpf"
}
},
"invalid_cnpj": {
"summary": "CNPJ fails check-digit validation",
"value": {
"type": "https://docs.dinie.com/errors/validation-failed",
"title": "Validation Failed",
"status": 422,
"detail": "CNPJ fails check-digit validation",
"code": "invalid_cnpj"
}
},
"invalid_email": {
"summary": "Email format is invalid",
"value": {
"type": "https://docs.dinie.com/errors/validation-failed",
"title": "Validation Failed",
"status": 422,
"detail": "Email format is invalid",
"code": "invalid_email"
}
},
"invalid_phone": {
"summary": "Phone format is invalid (expected E.164 with +55 country code)",
"value": {
"type": "https://docs.dinie.com/errors/validation-failed",
"title": "Validation Failed",
"status": 422,
"detail": "Phone format is invalid (expected E.164 with +55 country code)",
"code": "invalid_phone"
}
}
}
}
}
},
"429": {
"$ref": "#/components/responses/RateLimited",
"description": "Rate limit exceeded"
},
"500": {
"$ref": "#/components/responses/InternalError",
"description": "Internal server error"
}
},
"x-codeSamples": [
{
"lang": "curl",
"source": "curl -X POST https://api.dinie.com/api/v3/customers \\\n -H \"Authorization: Bearer $DINIE_API_TOKEN\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"cpf\": \"123.456.789-00\",\n \"email\": \"joao@example.com\",\n \"phone\": \"+5511999999999\",\n \"external_id\": \"partner-ref-123\"\n }'\n"
},
{
"lang": "Python",
"source": "from dinie import Dinie\n\nclient = Dinie(\n client_id=\"dinie_ci_abc123\",\n client_secret=\"dinie_cs_live_xyz789\"\n)\n\n# Create a new customer\ncustomer = client.customers.create(\n cpf=\"123.456.789-00\",\n email=\"joao@example.com\",\n phone=\"+5511999999999\",\n external_id=\"partner-ref-123\"\n)\n\nprint(customer.id) # \"cust_550e8400...\"\nprint(customer.status) # \"creating\"\n"
},
{
"lang": "Node.js",
"source": "const { Dinie } = require(\"dinie\");\n\nconst client = new Dinie({\n clientId: \"dinie_ci_abc123\",\n clientSecret: \"dinie_cs_live_xyz789\",\n});\n\n// Create a new customer\nconst customer = await client.customers.create({\n cpf: \"123.456.789-00\",\n email: \"joao@example.com\",\n phone: \"+5511999999999\",\n externalId: \"partner-ref-123\",\n});\n\nconsole.log(customer.id); // \"cust_550e8400...\"\nconsole.log(customer.status); // \"creating\"\n"
},
{
"lang": "Ruby",
"source": "require \"dinie\"\n\nclient = Dinie::Client.new(\n client_id: \"dinie_ci_abc123\",\n client_secret: \"dinie_cs_live_xyz789\"\n)\n\n# Create a new customer\ncustomer = client.customers.create(\n cpf: \"123.456.789-00\",\n email: \"joao@example.com\",\n phone: \"+5511999999999\",\n external_id: \"partner-ref-123\"\n)\n\nputs customer.id # \"cust_550e8400...\"\nputs customer.status # \"creating\"\n"
}
]
},
"get": {
"operationId": "listCustomers",
"summary": "List customers",
"description": "GET /customers
\n\nList customers",
"tags": [
"Customers"
],
"parameters": [
{
"name": "external_id",
"in": "query",
"schema": {
"type": "string"
},
"description": "Filter by partner external reference"
},
{
"name": "cpf",
"in": "query",
"schema": {
"type": "string"
},
"description": "Filter by CPF"
},
{
"name": "status",
"in": "query",
"schema": {
"type": "string",
"enum": [
"creating",
"pending_kyc",
"under_review",
"active",
"denied"
]
},
"description": "Filter by customer status"
},
{
"name": "sort",
"in": "query",
"schema": {
"type": "string",
"enum": [
"created_at",
"updated_at"
],
"default": "created_at"
},
"description": "Field to sort results by"
},
{
"name": "order",
"in": "query",
"schema": {
"type": "string",
"enum": [
"asc",
"desc"
],
"default": "desc"
},
"description": "Sort direction for results"
},
{
"$ref": "#/components/parameters/StartingAfter"
},
{
"$ref": "#/components/parameters/Limit"
}
],
"responses": {
"200": {
"description": "List of customers",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"data",
"has_more"
],
"properties": {
"data": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Customer"
}
},
"has_more": {
"type": "boolean"
}
}
},
"example": {
"data": [
{
"id": "cust_550e8400e29b41d4a716446655440000",
"status": "active",
"cpf": "123.456.789-00",
"cnpj": "12.345.678/0001-90",
"name": "João Silva",
"email": "joao@example.com",
"phone": "+5511999999999",
"trading_name": "Loja do João",
"external_id": "partner-ref-123",
"kyc": [],
"created_at": 1709546400,
"updated_at": 1709632800
},
{
"id": "cust_660e8400e29b41d4a716446655440001",
"status": "pending_kyc",
"cpf": "987.654.321-00",
"cnpj": null,
"name": "Maria Santos",
"email": "maria@example.com",
"phone": "+5511988888888",
"trading_name": null,
"external_id": "partner-ref-456",
"kyc": [],
"created_at": 1709625600,
"updated_at": 1709625600
}
],
"has_more": true
}
}
}
},
"400": {
"description": "Bad request",
"content": {
"application/problem+json": {
"schema": {
"type": "object",
"required": [
"type",
"title",
"status",
"detail",
"code"
],
"properties": {
"type": {
"type": "string",
"const": "https://docs.dinie.com/errors/invalid-request"
},
"title": {
"type": "string",
"const": "Invalid Request"
},
"status": {
"type": "integer",
"const": 400
},
"detail": {
"type": "string"
},
"code": {
"type": "string",
"enum": [
"invalid_limit",
"invalid_sort",
"invalid_order",
"invalid_cursor"
],
"x-enumDescriptions": {
"invalid_limit": "`limit` is not a valid integer or is outside 1–100 range",
"invalid_sort": "`sort` value is not one of the supported fields",
"invalid_order": "`order` value is not `asc` or `desc`",
"invalid_cursor": "`starting_after` references a non-existent or inaccessible customer"
}
}
}
},
"examples": {
"invalid_limit": {
"summary": "`limit` is not a valid integer or is outside 1–100 range",
"value": {
"type": "https://docs.dinie.com/errors/invalid-request",
"title": "Invalid Request",
"status": 400,
"detail": "`limit` is not a valid integer or is outside 1–100 range",
"code": "invalid_limit"
}
},
"invalid_sort": {
"summary": "`sort` value is not one of the supported fields",
"value": {
"type": "https://docs.dinie.com/errors/invalid-request",
"title": "Invalid Request",
"status": 400,
"detail": "`sort` value is not one of the supported fields",
"code": "invalid_sort"
}
},
"invalid_order": {
"summary": "`order` value is not `asc` or `desc`",
"value": {
"type": "https://docs.dinie.com/errors/invalid-request",
"title": "Invalid Request",
"status": 400,
"detail": "`order` value is not `asc` or `desc`",
"code": "invalid_order"
}
},
"invalid_cursor": {
"summary": "`starting_after` references a non-existent or inaccessible customer",
"value": {
"type": "https://docs.dinie.com/errors/invalid-request",
"title": "Invalid Request",
"status": 400,
"detail": "`starting_after` references a non-existent or inaccessible customer",
"code": "invalid_cursor"
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/BearerTokenUnauthorized",
"description": "Authentication failed"
},
"429": {
"$ref": "#/components/responses/RateLimited",
"description": "Rate limit exceeded"
},
"500": {
"$ref": "#/components/responses/InternalError",
"description": "Internal server error"
}
},
"x-codeSamples": [
{
"lang": "curl",
"source": "# List customers filtered by CPF\ncurl \"https://api.dinie.com/api/v3/customers?cpf=123.456.789-00&limit=10\" \\\n -H \"Authorization: Bearer $DINIE_API_TOKEN\"\n"
},
{
"lang": "Python",
"source": "from dinie import Dinie\n\nclient = Dinie(\n client_id=\"dinie_ci_abc123\",\n client_secret=\"dinie_cs_live_xyz789\"\n)\n\n# List customers filtered by CPF\ncustomers = client.customers.list(\n cpf=\"123.456.789-00\",\n limit=10\n)\n\nfor cust in customers.data:\n print(f\"{cust.name}: {cust.status}\")\n\n# Paginate with starting_after\nif customers.has_more:\n next_page = client.customers.list(\n starting_after=customers.data[-1].id,\n limit=10\n )\n"
},
{
"lang": "Node.js",
"source": "const { Dinie } = require(\"dinie\");\n\nconst client = new Dinie({\n clientId: \"dinie_ci_abc123\",\n clientSecret: \"dinie_cs_live_xyz789\",\n});\n\n// List customers filtered by CPF\nconst customers = await client.customers.list({\n cpf: \"123.456.789-00\",\n limit: 10,\n});\n\nfor (const cust of customers.data) {\n console.log(`${cust.name}: ${cust.status}`);\n}\n\n// Paginate with startingAfter\nif (customers.hasMore) {\n const nextPage = await client.customers.list({\n startingAfter: customers.data.at(-1).id,\n limit: 10,\n });\n}\n"
},
{
"lang": "Ruby",
"source": "require \"dinie\"\n\nclient = Dinie::Client.new(\n client_id: \"dinie_ci_abc123\",\n client_secret: \"dinie_cs_live_xyz789\"\n)\n\n# List customers filtered by CPF\ncustomers = client.customers.list(\n cpf: \"123.456.789-00\",\n limit: 10\n)\n\ncustomers.data.each do |cust|\n puts \"#{cust.name}: #{cust.status}\"\nend\n\n# Paginate with starting_after\nif customers.has_more\n next_page = client.customers.list(\n starting_after: customers.data.last.id,\n limit: 10\n )\nend\n"
}
]
}
},
"/customers/{customer_id}": {
"get": {
"operationId": "getCustomer",
"summary": "Get a customer",
"description": "GET /customers/{customer_id}
\n\nGet a customer",
"tags": [
"Customers"
],
"security": [
{
"oauth2": [
"kyc:read"
]
}
],
"parameters": [
{
"$ref": "#/components/parameters/CustomerId"
}
],
"responses": {
"200": {
"description": "Customer details",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Customer"
},
"example": {
"id": "cust_550e8400e29b41d4a716446655440000",
"status": "active",
"cpf": "123.456.789-00",
"cnpj": "12.345.678/0001-90",
"name": "João Silva",
"email": "joao@example.com",
"phone": "+5511999999999",
"trading_name": "Loja do João",
"external_id": "partner-ref-123",
"kyc": [
{
"requirement_id": "identity_003XXXXXXXXXXXXXXX",
"requirement_type": "identity",
"label": "Documento de identidade",
"mandatory": true,
"subject": {
"id": "003XXXXXXXXXXXXXXX",
"name": "Joao Silva",
"subject_type": "applicant"
},
"submitted": {
"evidence_type": "cnh",
"attachments": [
{
"attachment_type": "front",
"submitted": true
},
{
"attachment_type": "back",
"submitted": true
}
],
"review_status": "accepted",
"review_reason": null
}
},
{
"requirement_id": "company_document_001XXXXXXXXXXXXXXX",
"requirement_type": "company_document",
"label": "Documento da empresa",
"mandatory": true,
"submitted": {
"evidence_type": "ccmei",
"attachments": [
{
"attachment_type": "file",
"submitted": true
}
],
"review_status": "accepted",
"review_reason": null
}
},
{
"requirement_id": "email_003YYYYYYYYYYYYYYY",
"requirement_type": "email",
"label": "Email do co-titular para assinatura da CCB",
"mandatory": true,
"subject": {
"id": "003YYYYYYYYYYYYYYY",
"name": "Maria Co-owner",
"subject_type": "co_owner"
},
"submitted": {
"evidence_type": "email",
"attachments": [
{
"attachment_type": "email",
"submitted": true
}
],
"review_status": "pending",
"review_reason": null
}
}
],
"created_at": 1772791200,
"updated_at": 1772805600
}
}
}
},
"401": {
"$ref": "#/components/responses/BearerTokenUnauthorized",
"description": "Authentication failed"
},
"403": {
"$ref": "#/components/responses/Forbidden",
"description": "Credential lacks the `kyc:read` scope, or the session token is bound to a different customer"
},
"404": {
"description": "Resource not found",
"content": {
"application/problem+json": {
"schema": {
"type": "object",
"required": [
"type",
"title",
"status",
"detail",
"code"
],
"properties": {
"type": {
"type": "string",
"const": "https://docs.dinie.com/errors/not-found"
},
"title": {
"type": "string",
"const": "Not Found"
},
"status": {
"type": "integer",
"const": 404
},
"detail": {
"type": "string"
},
"code": {
"type": "string",
"const": "customer_not_found",
"x-enumDescriptions": {
"customer_not_found": "Customer ID does not exist or does not belong to this partner"
}
}
}
},
"examples": {
"customer_not_found": {
"summary": "Customer ID does not exist or does not belong to this partner",
"value": {
"type": "https://docs.dinie.com/errors/not-found",
"title": "Not Found",
"status": 404,
"detail": "Customer ID does not exist or does not belong to this partner",
"code": "customer_not_found"
}
}
}
}
}
},
"429": {
"$ref": "#/components/responses/RateLimited",
"description": "Rate limit exceeded"
},
"500": {
"$ref": "#/components/responses/InternalError",
"description": "Internal server error"
}
},
"x-codeSamples": [
{
"lang": "curl",
"source": "curl https://api.dinie.com/api/v3/customers/cust_550e8400e29b41d4a716446655440000 \\\n -H \"Authorization: Bearer $DINIE_API_TOKEN\"\n"
},
{
"lang": "Python",
"source": "from dinie import Dinie\n\nclient = Dinie(\n client_id=\"dinie_ci_abc123\",\n client_secret=\"dinie_cs_live_xyz789\"\n)\n\n# Retrieve a customer\ncustomer = client.customers.retrieve(\"cust_550e8400e29b41d4a716446655440000\")\n\nprint(customer.status) # \"active\"\nprint(customer.name) # \"João Silva\"\nprint(customer.external_id) # \"partner-ref-123\"\n"
},
{
"lang": "Node.js",
"source": "const { Dinie } = require(\"dinie\");\n\nconst client = new Dinie({\n clientId: \"dinie_ci_abc123\",\n clientSecret: \"dinie_cs_live_xyz789\",\n});\n\n// Retrieve a customer\nconst customer = await client.customers.retrieve(\n \"cust_550e8400e29b41d4a716446655440000\"\n);\n\nconsole.log(customer.status); // \"active\"\nconsole.log(customer.name); // \"João Silva\"\nconsole.log(customer.externalId); // \"partner-ref-123\"\n"
},
{
"lang": "Ruby",
"source": "require \"dinie\"\n\nclient = Dinie::Client.new(\n client_id: \"dinie_ci_abc123\",\n client_secret: \"dinie_cs_live_xyz789\"\n)\n\n# Retrieve a customer\ncustomer = client.customers.retrieve(\"cust_550e8400e29b41d4a716446655440000\")\n\nputs customer.status # \"active\"\nputs customer.name # \"João Silva\"\nputs customer.external_id # \"partner-ref-123\"\n"
}
]
},
"patch": {
"operationId": "updateCustomer",
"summary": "Update customer data",
"description": "PATCH /customers/{customer_id}
\n\nUpdate customer data",
"tags": [
"Customers"
],
"parameters": [
{
"$ref": "#/components/parameters/CustomerId"
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/UpdateCustomerRequest"
},
"example": {
"email": "joao.novo@example.com",
"phone": "+5511988887777"
}
}
}
},
"responses": {
"200": {
"description": "Customer updated",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Customer"
},
"example": {
"id": "cust_550e8400e29b41d4a716446655440000",
"status": "active",
"cpf": "123.456.789-00",
"cnpj": "12.345.678/0001-90",
"name": "João Silva",
"email": "joao.novo@example.com",
"phone": "+5511988887777",
"trading_name": "Loja do João",
"external_id": "partner-ref-123",
"kyc": [],
"created_at": 1709546400,
"updated_at": 1709632800
}
}
}
},
"400": {
"description": "Bad request",
"content": {
"application/problem+json": {
"schema": {
"type": "object",
"required": [
"type",
"title",
"status",
"detail",
"code"
],
"properties": {
"type": {
"type": "string",
"const": "https://docs.dinie.com/errors/invalid-request"
},
"title": {
"type": "string",
"const": "Invalid Request"
},
"status": {
"type": "integer",
"const": 400
},
"detail": {
"type": "string"
},
"code": {
"type": "string",
"enum": [
"invalid_content_type",
"malformed_body",
"empty_update"
],
"x-enumDescriptions": {
"invalid_content_type": "`Content-Type` is not `application/json`",
"malformed_body": "Request body is not valid JSON",
"empty_update": "Request body contains no updatable fields"
}
}
}
},
"examples": {
"invalid_content_type": {
"summary": "`Content-Type` is not `application/json`",
"value": {
"type": "https://docs.dinie.com/errors/invalid-request",
"title": "Invalid Request",
"status": 400,
"detail": "`Content-Type` is not `application/json`",
"code": "invalid_content_type"
}
},
"malformed_body": {
"summary": "Request body is not valid JSON",
"value": {
"type": "https://docs.dinie.com/errors/invalid-request",
"title": "Invalid Request",
"status": 400,
"detail": "Request body is not valid JSON",
"code": "malformed_body"
}
},
"empty_update": {
"summary": "Request body contains no updatable fields",
"value": {
"type": "https://docs.dinie.com/errors/invalid-request",
"title": "Invalid Request",
"status": 400,
"detail": "Request body contains no updatable fields",
"code": "empty_update"
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/BearerTokenUnauthorized",
"description": "Authentication failed"
},
"404": {
"description": "Resource not found",
"content": {
"application/problem+json": {
"schema": {
"type": "object",
"required": [
"type",
"title",
"status",
"detail",
"code"
],
"properties": {
"type": {
"type": "string",
"const": "https://docs.dinie.com/errors/not-found"
},
"title": {
"type": "string",
"const": "Not Found"
},
"status": {
"type": "integer",
"const": 404
},
"detail": {
"type": "string"
},
"code": {
"type": "string",
"const": "customer_not_found",
"x-enumDescriptions": {
"customer_not_found": "Customer ID does not exist or does not belong to this partner"
}
}
}
},
"examples": {
"customer_not_found": {
"summary": "Customer ID does not exist or does not belong to this partner",
"value": {
"type": "https://docs.dinie.com/errors/not-found",
"title": "Not Found",
"status": 404,
"detail": "Customer ID does not exist or does not belong to this partner",
"code": "customer_not_found"
}
}
}
}
}
},
"422": {
"description": "Validation failed",
"content": {
"application/problem+json": {
"schema": {
"type": "object",
"required": [
"type",
"title",
"status",
"detail",
"code"
],
"properties": {
"type": {
"type": "string",
"const": "https://docs.dinie.com/errors/validation-failed"
},
"title": {
"type": "string",
"const": "Validation Failed"
},
"status": {
"type": "integer",
"const": 422
},
"detail": {
"type": "string"
},
"code": {
"type": "string",
"enum": [
"invalid_email",
"invalid_phone"
],
"x-enumDescriptions": {
"invalid_email": "Email format is invalid",
"invalid_phone": "Phone format is invalid (expected E.164 with +55 country code)"
}
}
}
},
"examples": {
"invalid_email": {
"summary": "Email format is invalid",
"value": {
"type": "https://docs.dinie.com/errors/validation-failed",
"title": "Validation Failed",
"status": 422,
"detail": "Email format is invalid",
"code": "invalid_email"
}
},
"invalid_phone": {
"summary": "Phone format is invalid (expected E.164 with +55 country code)",
"value": {
"type": "https://docs.dinie.com/errors/validation-failed",
"title": "Validation Failed",
"status": 422,
"detail": "Phone format is invalid (expected E.164 with +55 country code)",
"code": "invalid_phone"
}
}
}
}
}
},
"429": {
"$ref": "#/components/responses/RateLimited",
"description": "Rate limit exceeded"
},
"500": {
"$ref": "#/components/responses/InternalError",
"description": "Internal server error"
}
},
"x-codeSamples": [
{
"lang": "curl",
"source": "curl -X PATCH https://api.dinie.com/api/v3/customers/cust_550e8400e29b41d4a716446655440000 \\\n -H \"Authorization: Bearer $DINIE_API_TOKEN\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"email\": \"joao.novo@example.com\",\n \"phone\": \"+5511988887777\"\n }'\n"
},
{
"lang": "Python",
"source": "from dinie import Dinie\n\nclient = Dinie(\n client_id=\"dinie_ci_abc123\",\n client_secret=\"dinie_cs_live_xyz789\"\n)\n\n# Update customer data (e.g., fix rejected KYC fields)\ncustomer = client.customers.update(\n \"cust_550e8400e29b41d4a716446655440000\",\n email=\"joao.novo@example.com\",\n phone=\"+5511988887777\"\n)\n\nprint(customer.email) # \"joao.novo@example.com\"\nprint(customer.phone) # \"+5511988887777\"\n"
},
{
"lang": "Node.js",
"source": "const { Dinie } = require(\"dinie\");\n\nconst client = new Dinie({\n clientId: \"dinie_ci_abc123\",\n clientSecret: \"dinie_cs_live_xyz789\",\n});\n\n// Update customer data (e.g., fix rejected KYC fields)\nconst customer = await client.customers.update(\n \"cust_550e8400e29b41d4a716446655440000\",\n {\n email: \"joao.novo@example.com\",\n phone: \"+5511988887777\",\n }\n);\n\nconsole.log(customer.email); // \"joao.novo@example.com\"\nconsole.log(customer.phone); // \"+5511988887777\"\n"
},
{
"lang": "Ruby",
"source": "require \"dinie\"\n\nclient = Dinie::Client.new(\n client_id: \"dinie_ci_abc123\",\n client_secret: \"dinie_cs_live_xyz789\"\n)\n\n# Update customer data (e.g., fix rejected KYC fields)\ncustomer = client.customers.update(\n \"cust_550e8400e29b41d4a716446655440000\",\n email: \"joao.novo@example.com\",\n phone: \"+5511988887777\"\n)\n\nputs customer.email # \"joao.novo@example.com\"\nputs customer.phone # \"+5511988887777\"\n"
}
]
}
},
"/customers/{customer_id}/kyc-attachments": {
"post": {
"operationId": "uploadKycAttachment",
"summary": "Upload a KYC attachment",
"description": "POST /customers/{customer_id}/kyc-attachments
\n\nUpload a file for a KYC requirement",
"tags": [
"Customers"
],
"security": [
{
"oauth2": [
"kyc:upload"
]
}
],
"parameters": [
{
"$ref": "#/components/parameters/CustomerId"
},
{
"$ref": "#/components/parameters/IdempotencyKey"
}
],
"requestBody": {
"required": true,
"content": {
"multipart/form-data": {
"schema": {
"oneOf": [
{
"$ref": "#/components/schemas/KycUploadCnh"
},
{
"$ref": "#/components/schemas/KycUploadRg"
},
{
"$ref": "#/components/schemas/KycUploadSelfie"
},
{
"$ref": "#/components/schemas/KycUploadProofOfAddress"
},
{
"$ref": "#/components/schemas/KycUploadCcmei"
},
{
"$ref": "#/components/schemas/KycUploadEiMei"
},
{
"$ref": "#/components/schemas/KycUploadIncomeStatement"
},
{
"$ref": "#/components/schemas/KycUploadArticlesOfAssociation"
},
{
"$ref": "#/components/schemas/KycUploadEireliIncorporation"
},
{
"$ref": "#/components/schemas/KycUploadEmail"
}
],
"discriminator": {
"propertyName": "evidence_type",
"mapping": {
"cnh": "#/components/schemas/KycUploadCnh",
"rg": "#/components/schemas/KycUploadRg",
"selfie": "#/components/schemas/KycUploadSelfie",
"proof_of_address": "#/components/schemas/KycUploadProofOfAddress",
"ccmei": "#/components/schemas/KycUploadCcmei",
"ei_mei": "#/components/schemas/KycUploadEiMei",
"income_statement": "#/components/schemas/KycUploadIncomeStatement",
"articles_of_association": "#/components/schemas/KycUploadArticlesOfAssociation",
"eireli_incorporation_statement": "#/components/schemas/KycUploadEireliIncorporation",
"email": "#/components/schemas/KycUploadEmail"
}
}
}
}
}
},
"responses": {
"201": {
"description": "Attachment uploaded",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/KycAttachmentResponse"
},
"example": {
"attachment_type": "front",
"submitted": true
}
}
}
},
"400": {
"description": "Bad request",
"content": {
"application/problem+json": {
"schema": {
"type": "object",
"required": [
"type",
"title",
"status",
"detail",
"code"
],
"properties": {
"type": {
"type": "string",
"const": "https://docs.dinie.com/errors/invalid-request"
},
"title": {
"type": "string",
"const": "Invalid Request"
},
"status": {
"type": "integer",
"const": 400
},
"detail": {
"type": "string"
},
"code": {
"type": "string",
"enum": [
"invalid_content_type",
"missing_file",
"missing_type",
"file_too_large"
],
"x-enumDescriptions": {
"invalid_content_type": "`Content-Type` is not `multipart/form-data`",
"missing_file": "`file` part is missing from the multipart request",
"missing_type": "`requirement_id`, `evidence_type`, or `attachment_type` field is missing",
"file_too_large": "File exceeds the maximum allowed size"
}
}
}
},
"examples": {
"invalid_content_type": {
"summary": "`Content-Type` is not `multipart/form-data`",
"value": {
"type": "https://docs.dinie.com/errors/invalid-request",
"title": "Invalid Request",
"status": 400,
"detail": "`Content-Type` is not `multipart/form-data`",
"code": "invalid_content_type"
}
},
"missing_file": {
"summary": "`file` part is missing from the multipart request",
"value": {
"type": "https://docs.dinie.com/errors/invalid-request",
"title": "Invalid Request",
"status": 400,
"detail": "`file` part is missing from the multipart request",
"code": "missing_file"
}
},
"missing_type": {
"summary": "`requirement_id`, `evidence_type`, or `attachment_type` field is missing",
"value": {
"type": "https://docs.dinie.com/errors/invalid-request",
"title": "Invalid Request",
"status": 400,
"detail": "`requirement_id`, `evidence_type`, or `attachment_type` field is missing",
"code": "missing_type"
}
},
"file_too_large": {
"summary": "File exceeds the maximum allowed size",
"value": {
"type": "https://docs.dinie.com/errors/invalid-request",
"title": "Invalid Request",
"status": 400,
"detail": "File exceeds the maximum allowed size",
"code": "file_too_large"
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/BearerTokenUnauthorized",
"description": "Authentication failed"
},
"403": {
"$ref": "#/components/responses/Forbidden",
"description": "Credential lacks the `kyc:upload` scope, or the session token is bound to a different customer"
},
"404": {
"description": "Resource not found",
"content": {
"application/problem+json": {
"schema": {
"type": "object",
"required": [
"type",
"title",
"status",
"detail",
"code"
],
"properties": {
"type": {
"type": "string",
"const": "https://docs.dinie.com/errors/not-found"
},
"title": {
"type": "string",
"const": "Not Found"
},
"status": {
"type": "integer",
"const": 404
},
"detail": {
"type": "string"
},
"code": {
"type": "string",
"const": "customer_not_found",
"x-enumDescriptions": {
"customer_not_found": "Customer ID does not exist or does not belong to this partner"
}
}
}
},
"examples": {
"customer_not_found": {
"summary": "Customer ID does not exist or does not belong to this partner",
"value": {
"type": "https://docs.dinie.com/errors/not-found",
"title": "Not Found",
"status": 404,
"detail": "Customer ID does not exist or does not belong to this partner",
"code": "customer_not_found"
}
}
}
}
}
},
"409": {
"description": "Conflict",
"content": {
"application/problem+json": {
"schema": {
"type": "object",
"required": [
"type",
"title",
"status",
"detail",
"code"
],
"properties": {
"type": {
"type": "string",
"const": "https://docs.dinie.com/errors/conflict"
},
"title": {
"type": "string",
"const": "Conflict"
},
"status": {
"type": "integer",
"const": 409
},
"detail": {
"type": "string"
},
"code": {
"type": "string",
"const": "email_already_exists",
"x-enumDescriptions": {
"email_already_exists": "Director email is already set and cannot be overwritten"
}
}
}
},
"examples": {
"email_already_exists": {
"summary": "Director email is already set",
"value": {
"type": "https://docs.dinie.com/errors/conflict",
"title": "Conflict",
"status": 409,
"detail": "Director email already set",
"code": "email_already_exists"
}
}
}
}
}
},
"422": {
"description": "Validation failed",
"content": {
"application/problem+json": {
"schema": {
"type": "object",
"required": [
"type",
"title",
"status",
"detail",
"code"
],
"properties": {
"type": {
"type": "string",
"const": "https://docs.dinie.com/errors/validation-failed"
},
"title": {
"type": "string",
"const": "Validation Failed"
},
"status": {
"type": "integer",
"const": 422
},
"detail": {
"type": "string"
},
"code": {
"type": "string",
"enum": [
"invalid_requirement",
"invalid_file_format"
],
"x-enumDescriptions": {
"invalid_requirement": "`requirement_id`/`evidence_type`/`attachment_type` combination is not a valid KYC requirement for this customer",
"invalid_file_format": "File format is not supported (expected PDF, JPEG, or PNG)"
}
}
}
},
"examples": {
"invalid_requirement": {
"summary": "`requirement_id`/`evidence_type`/`attachment_type` combination is not a valid KYC requirement for this customer",
"value": {
"type": "https://docs.dinie.com/errors/validation-failed",
"title": "Validation Failed",
"status": 422,
"detail": "`requirement_id`/`evidence_type`/`attachment_type` combination is not a valid KYC requirement for this customer",
"code": "invalid_requirement"
}
},
"invalid_file_format": {
"summary": "File format is not supported (expected PDF, JPEG, or PNG)",
"value": {
"type": "https://docs.dinie.com/errors/validation-failed",
"title": "Validation Failed",
"status": 422,
"detail": "File format is not supported (expected PDF, JPEG, or PNG)",
"code": "invalid_file_format"
}
}
}
}
}
},
"429": {
"$ref": "#/components/responses/RateLimited",
"description": "Rate limit exceeded"
},
"500": {
"$ref": "#/components/responses/InternalError",
"description": "Internal server error"
}
},
"x-codeSamples": [
{
"lang": "curl",
"source": "curl -X POST https://api.dinie.com/api/v3/customers/cust_550e8400e29b41d4a716446655440000/kyc-attachments \\\n -H \"Authorization: Bearer $DINIE_API_TOKEN\" \\\n -F \"requirement_id=identity_003XXXXXXXXXXXXXXX\" \\\n -F \"evidence_type=cnh\" \\\n -F \"attachment_type=front\" \\\n -F \"file=@cnh-front.jpg\"\n"
},
{
"lang": "Python",
"source": "from dinie import Dinie\n\nclient = Dinie(\n client_id=\"dinie_ci_abc123\",\n client_secret=\"dinie_cs_live_xyz789\"\n)\n\n# Upload a KYC attachment\nattachment = client.customers.upload_kyc_attachment(\n \"cust_550e8400e29b41d4a716446655440000\",\n requirement_id=\"identity_003XXXXXXXXXXXXXXX\",\n evidence_type=\"cnh\",\n attachment_type=\"front\",\n file=open(\"cnh-front.jpg\", \"rb\")\n)\n\nprint(attachment.submitted) # True\n"
},
{
"lang": "Node.js",
"source": "const fs = require(\"fs\");\nconst { Dinie } = require(\"dinie\");\n\nconst client = new Dinie({\n clientId: \"dinie_ci_abc123\",\n clientSecret: \"dinie_cs_live_xyz789\",\n});\n\n// Upload a KYC attachment\nconst attachment = await client.customers.uploadKycAttachment(\n \"cust_550e8400e29b41d4a716446655440000\",\n {\n requirementId: \"identity_003XXXXXXXXXXXXXXX\",\n evidenceType: \"cnh\",\n attachmentType: \"front\",\n file: fs.createReadStream(\"cnh-front.jpg\"),\n }\n);\n\nconsole.log(attachment.submitted); // true\n"
},
{
"lang": "Ruby",
"source": "require \"dinie\"\n\nclient = Dinie::Client.new(\n client_id: \"dinie_ci_abc123\",\n client_secret: \"dinie_cs_live_xyz789\"\n)\n\n# Upload a KYC attachment\nattachment = client.customers.upload_kyc_attachment(\n \"cust_550e8400e29b41d4a716446655440000\",\n requirement_id: \"identity_003XXXXXXXXXXXXXXX\",\n evidence_type: \"cnh\",\n attachment_type: \"front\",\n file: File.open(\"cnh-front.jpg\")\n)\n\nputs attachment.submitted # true\n"
}
]
}
},
"/customers/{customer_id}/bank-account": {
"get": {
"operationId": "getCustomerBankAccount",
"summary": "Get customer bank account",
"description": "GET /customers/{customer_id}/bank-account
\n\nReturn the bank account linked to this customer, if any",
"tags": [
"Customers"
],
"security": [
{
"oauth2": [
"kyc:read"
]
}
],
"parameters": [
{
"$ref": "#/components/parameters/CustomerId"
}
],
"responses": {
"200": {
"description": "Bank account",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CustomerBankAccount"
}
}
}
},
"401": {
"$ref": "#/components/responses/BearerTokenUnauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden",
"description": "Credential lacks the `kyc:read` scope, or the session token is bound to a different customer"
},
"404": {
"description": "Bank account not found"
},
"429": {
"$ref": "#/components/responses/RateLimited"
},
"500": {
"$ref": "#/components/responses/InternalError"
}
}
},
"post": {
"operationId": "upsertCustomerBankAccount",
"summary": "Create or update customer bank account",
"description": "POST /customers/{customer_id}/bank-account
\n\nCreate or update the bank account linked to this customer; available to biometrics session tokens so the kyc-app can collect disbursement bank data",
"tags": [
"Customers"
],
"security": [
{
"oauth2": [
"kyc:upload"
]
}
],
"parameters": [
{
"$ref": "#/components/parameters/CustomerId"
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"bank_account"
],
"properties": {
"bank_account": {
"$ref": "#/components/schemas/CustomerBankAccountRequest"
}
}
}
}
}
},
"responses": {
"200": {
"description": "Bank account saved",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CustomerBankAccount"
}
}
}
},
"401": {
"$ref": "#/components/responses/BearerTokenUnauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden",
"description": "Credential lacks the `kyc:upload` scope, or the session token is bound to a different customer"
},
"422": {
"description": "Validation failed",
"content": {
"application/problem+json": {
"schema": {
"type": "object",
"required": [
"type",
"title",
"status",
"detail",
"code"
],
"properties": {
"type": {
"type": "string",
"const": "https://docs.dinie.com/errors/validation-failed"
},
"title": {
"type": "string",
"const": "Validation Failed"
},
"status": {
"type": "integer",
"const": 422
},
"detail": {
"type": "string"
},
"code": {
"type": "string",
"enum": [
"validation_failed",
"no_user"
],
"x-enumDescriptions": {
"validation_failed": "One or more bank account fields are invalid",
"no_user": "The customer has no confirmed user account"
}
}
}
},
"examples": {
"validation_failed": {
"summary": "One or more bank account fields are invalid",
"value": {
"type": "https://docs.dinie.com/errors/validation-failed",
"title": "Validation Failed",
"status": 422,
"detail": "Bank must exist",
"code": "validation_failed"
}
},
"no_user": {
"summary": "The customer has no confirmed user account",
"value": {
"type": "https://docs.dinie.com/errors/validation-failed",
"title": "Validation Failed",
"status": 422,
"detail": "Customer has no confirmed user account",
"code": "no_user"
}
}
}
}
}
},
"429": {
"$ref": "#/components/responses/RateLimited"
},
"500": {
"$ref": "#/components/responses/InternalError"
}
}
}
},
"/banks": {
"get": {
"operationId": "listBanks",
"summary": "List banks",
"description": "GET /banks
\n\nList banks available for customer bank account submission",
"tags": [
"Customers"
],
"security": [
{
"oauth2": [
"kyc:read"
]
}
],
"responses": {
"200": {
"description": "Banks",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"data"
],
"properties": {
"data": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Bank"
}
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/BearerTokenUnauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden",
"description": "Credential lacks the `kyc:read` scope"
},
"429": {
"$ref": "#/components/responses/RateLimited"
},
"500": {
"$ref": "#/components/responses/InternalError"
}
}
}
},
"/customers/{customer_id}/biometrics": {
"post": {
"operationId": "createBiometricsSession",
"summary": "Start biometrics",
"description": "POST /customers/{customer_id}/biometrics
\n\nCreate a biometrics capture session",
"tags": [
"Customers"
],
"security": [
{
"oauth2": [
"biometrics:create"
]
}
],
"parameters": [
{
"$ref": "#/components/parameters/CustomerId"
}
],
"requestBody": {
"required": false,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"return_url": {
"type": "string",
"format": "uri",
"description": "URL the customer-facing app returns the user to when the flow finishes"
}
}
}
}
}
},
"responses": {
"201": {
"description": "Biometrics session created",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/BiometricsSession"
},
"example": {
"session_url": "https://kyc-app.dinie.com.br/session/dinie_bsc_test_abc123def456",
"expires_at": 1741082400
}
}
}
},
"401": {
"$ref": "#/components/responses/BearerTokenUnauthorized",
"description": "Authentication failed"
},
"403": {
"$ref": "#/components/responses/Forbidden",
"description": "Credential lacks the `biometrics:create` scope, or the session token is bound to a different customer"
},
"404": {
"description": "Resource not found",
"content": {
"application/problem+json": {
"schema": {
"type": "object",
"required": [
"type",
"title",
"status",
"detail",
"code"
],
"properties": {
"type": {
"type": "string",
"const": "https://docs.dinie.com/errors/not-found"
},
"title": {
"type": "string",
"const": "Not Found"
},
"status": {
"type": "integer",
"const": 404
},
"detail": {
"type": "string"
},
"code": {
"type": "string",
"const": "customer_not_found",
"x-enumDescriptions": {
"customer_not_found": "Customer ID does not exist or does not belong to this partner"
}
}
}
},
"examples": {
"customer_not_found": {
"summary": "Customer ID does not exist or does not belong to this partner",
"value": {
"type": "https://docs.dinie.com/errors/not-found",
"title": "Not Found",
"status": 404,
"detail": "Customer ID does not exist or does not belong to this partner",
"code": "customer_not_found"
}
}
}
}
}
},
"409": {
"description": "Conflict",
"content": {
"application/problem+json": {
"schema": {
"type": "object",
"required": [
"type",
"title",
"status",
"detail",
"code"
],
"properties": {
"type": {
"type": "string",
"const": "https://docs.dinie.com/errors/conflict"
},
"title": {
"type": "string",
"const": "Conflict"
},
"status": {
"type": "integer",
"const": 409
},
"detail": {
"type": "string"
},
"code": {
"type": "string",
"const": "session_already_active",
"x-enumDescriptions": {
"session_already_active": "A biometrics session is already active for this customer"
}
}
}
},
"examples": {
"session_already_active": {
"summary": "A biometrics session is already active for this customer",
"value": {
"type": "https://docs.dinie.com/errors/conflict",
"title": "Conflict",
"status": 409,
"detail": "A biometrics session is already active for this customer",
"code": "session_already_active"
}
}
}
}
}
},
"422": {
"description": "Validation failed",
"content": {
"application/problem+json": {
"schema": {
"type": "object",
"required": [
"type",
"title",
"status",
"detail",
"code"
],
"properties": {
"type": {
"type": "string",
"const": "https://docs.dinie.com/errors/validation-failed"
},
"title": {
"type": "string",
"const": "Validation Failed"
},
"status": {
"type": "integer",
"const": 422
},
"detail": {
"type": "string"
},
"code": {
"type": "string",
"const": "biometrics_not_required",
"x-enumDescriptions": {
"biometrics_not_required": "Customer does not have pending biometrics KYC requirements"
}
}
}
},
"examples": {
"biometrics_not_required": {
"summary": "Customer does not have pending biometrics KYC requirements",
"value": {
"type": "https://docs.dinie.com/errors/validation-failed",
"title": "Validation Failed",
"status": 422,
"detail": "Customer does not have pending biometrics KYC requirements",
"code": "biometrics_not_required"
}
}
}
}
}
},
"429": {
"$ref": "#/components/responses/RateLimited",
"description": "Rate limit exceeded"
},
"500": {
"$ref": "#/components/responses/InternalError",
"description": "Internal server error"
}
},
"x-codeSamples": [
{
"lang": "curl",
"source": "curl -X POST https://api.dinie.com/api/v3/customers/cust_550e8400e29b41d4a716446655440000/biometrics \\\n -H \"Authorization: Bearer $DINIE_API_TOKEN\"\n"
},
{
"lang": "Python",
"source": "from dinie import Dinie\n\nclient = Dinie(\n client_id=\"dinie_ci_abc123\",\n client_secret=\"dinie_cs_live_xyz789\"\n)\n\n# Generate a biometrics capture session\nsession = client.customers.create_biometrics_session(\n \"cust_550e8400e29b41d4a716446655440000\"\n)\n\nprint(session.session_url) # \"https://biometrics.dinie.com.br/session/abc123def456\"\nprint(session.expires_at) # 1741082400\n# Redirect the customer to session.session_url\n"
},
{
"lang": "Node.js",
"source": "const { Dinie } = require(\"dinie\");\n\nconst client = new Dinie({\n clientId: \"dinie_ci_abc123\",\n clientSecret: \"dinie_cs_live_xyz789\",\n});\n\n// Generate a biometrics capture session\nconst session = await client.customers.createBiometricsSession(\n \"cust_550e8400e29b41d4a716446655440000\"\n);\n\nconsole.log(session.sessionUrl); // \"https://biometrics.dinie.com.br/session/abc123def456\"\nconsole.log(session.expiresAt); // 1741082400\n// Redirect the customer to session.sessionUrl\n"
},
{
"lang": "Ruby",
"source": "require \"dinie\"\n\nclient = Dinie::Client.new(\n client_id: \"dinie_ci_abc123\",\n client_secret: \"dinie_cs_live_xyz789\"\n)\n\n# Generate a biometrics capture session\nsession = client.customers.create_biometrics_session(\n \"cust_550e8400e29b41d4a716446655440000\"\n)\n\nputs session.session_url # \"https://biometrics.dinie.com.br/session/abc123def456\"\nputs session.expires_at # 1741082400\n# Redirect the customer to session.session_url\n"
}
]
}
},
"/customers/{customer_id}/credit-offers": {
"get": {
"operationId": "listCustomerCreditOffers",
"summary": "List customer credit offers",
"description": "GET /customers/{customer_id}/credit-offers
\n\nList a customer's credit offers",
"tags": [
"Credit Offers"
],
"parameters": [
{
"$ref": "#/components/parameters/CustomerId"
},
{
"name": "status",
"in": "query",
"schema": {
"type": "string",
"enum": [
"available",
"accepted",
"expired"
]
},
"description": "Filter by offer status"
},
{
"$ref": "#/components/parameters/StartingAfter"
},
{
"$ref": "#/components/parameters/Limit"
}
],
"responses": {
"200": {
"description": "List of credit offers",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"data",
"has_more"
],
"properties": {
"data": {
"type": "array",
"items": {
"$ref": "#/components/schemas/CreditOffer"
}
},
"has_more": {
"type": "boolean"
}
}
},
"example": {
"data": [
{
"id": "co_550e8400e29b41d4a716446655440000",
"customer_id": "cust_550e8400e29b41d4a716446655440000",
"status": "available",
"approved_amount": 50000,
"min_amount": 200,
"monthly_interest_rate": 3.5,
"installments": 12,
"due_date_rule": null,
"valid_until": 1775253599,
"created_at": 1772791200,
"updated_at": 1772877600
}
],
"has_more": false
}
}
}
},
"400": {
"description": "Bad request",
"content": {
"application/problem+json": {
"schema": {
"type": "object",
"required": [
"type",
"title",
"status",
"detail",
"code"
],
"properties": {
"type": {
"type": "string",
"const": "https://docs.dinie.com/errors/invalid-request"
},
"title": {
"type": "string",
"const": "Invalid Request"
},
"status": {
"type": "integer",
"const": 400
},
"detail": {
"type": "string"
},
"code": {
"type": "string",
"enum": [
"invalid_limit",
"invalid_cursor"
],
"x-enumDescriptions": {
"invalid_limit": "`limit` is not a valid integer or is outside 1–100 range",
"invalid_cursor": "`starting_after` references a non-existent or inaccessible credit offer"
}
}
}
},
"examples": {
"invalid_limit": {
"summary": "`limit` is not a valid integer or is outside 1–100 range",
"value": {
"type": "https://docs.dinie.com/errors/invalid-request",
"title": "Invalid Request",
"status": 400,
"detail": "`limit` is not a valid integer or is outside 1–100 range",
"code": "invalid_limit"
}
},
"invalid_cursor": {
"summary": "`starting_after` references a non-existent or inaccessible credit offer",
"value": {
"type": "https://docs.dinie.com/errors/invalid-request",
"title": "Invalid Request",
"status": 400,
"detail": "`starting_after` references a non-existent or inaccessible credit offer",
"code": "invalid_cursor"
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/BearerTokenUnauthorized",
"description": "Authentication failed"
},
"404": {
"description": "Resource not found",
"content": {
"application/problem+json": {
"schema": {
"type": "object",
"required": [
"type",
"title",
"status",
"detail",
"code"
],
"properties": {
"type": {
"type": "string",
"const": "https://docs.dinie.com/errors/not-found"
},
"title": {
"type": "string",
"const": "Not Found"
},
"status": {
"type": "integer",
"const": 404
},
"detail": {
"type": "string"
},
"code": {
"type": "string",
"const": "customer_not_found",
"x-enumDescriptions": {
"customer_not_found": "Customer ID does not exist or does not belong to this partner"
}
}
}
},
"examples": {
"customer_not_found": {
"summary": "Customer ID does not exist or does not belong to this partner",
"value": {
"type": "https://docs.dinie.com/errors/not-found",
"title": "Not Found",
"status": 404,
"detail": "Customer ID does not exist or does not belong to this partner",
"code": "customer_not_found"
}
}
}
}
}
},
"429": {
"$ref": "#/components/responses/RateLimited",
"description": "Rate limit exceeded"
},
"500": {
"$ref": "#/components/responses/InternalError",
"description": "Internal server error"
}
},
"x-codeSamples": [
{
"lang": "curl",
"source": "curl \"https://api.dinie.com/api/v3/customers/cust_550e8400e29b41d4a716446655440000/credit-offers?status=available\" \\\n -H \"Authorization: Bearer $DINIE_API_TOKEN\"\n"
},
{
"lang": "Python",
"source": "from dinie import Dinie\n\nclient = Dinie(\n client_id=\"dinie_ci_abc123\",\n client_secret=\"dinie_cs_live_xyz789\"\n)\n\n# List available credit offers for a customer\noffers = client.customers.list_credit_offers(\n \"cust_550e8400e29b41d4a716446655440000\",\n status=\"available\"\n)\n\nfor offer in offers.data:\n print(f\"{offer.id}: R$ {offer.approved_amount} ({offer.monthly_interest_rate}% a.m.)\")\n # \"co_550e8400...: R$ 50000.00 (3.5% a.m.)\"\n"
},
{
"lang": "Node.js",
"source": "const { Dinie } = require(\"dinie\");\n\nconst client = new Dinie({\n clientId: \"dinie_ci_abc123\",\n clientSecret: \"dinie_cs_live_xyz789\",\n});\n\n// List available credit offers for a customer\nconst offers = await client.customers.listCreditOffers(\n \"cust_550e8400e29b41d4a716446655440000\",\n { status: \"available\" }\n);\n\nfor (const offer of offers.data) {\n console.log(`${offer.id}: R$ ${offer.approvedAmount} (${offer.interestRate}% a.m.)`);\n // \"co_550e8400...: R$ 50000.00 (3.5% a.m.)\"\n}\n"
},
{
"lang": "Ruby",
"source": "require \"dinie\"\n\nclient = Dinie::Client.new(\n client_id: \"dinie_ci_abc123\",\n client_secret: \"dinie_cs_live_xyz789\"\n)\n\n# List available credit offers for a customer\noffers = client.customers.list_credit_offers(\n \"cust_550e8400e29b41d4a716446655440000\",\n status: \"available\"\n)\n\noffers.data.each do |offer|\n puts \"#{offer.id}: R$ #{offer.approved_amount} (#{offer.monthly_interest_rate}% a.m.)\"\n # \"co_550e8400...: R$ 50000.00 (3.5% a.m.)\"\nend\n"
}
]
}
},
"/credit-offers": {
"get": {
"operationId": "listCreditOffers",
"summary": "List credit offers",
"description": "GET /credit-offers
\n\nList credit offers across all customers",
"tags": [
"Credit Offers"
],
"parameters": [
{
"name": "customer_id",
"in": "query",
"schema": {
"$ref": "#/components/schemas/CustomerId"
},
"description": "Filter by customer"
},
{
"name": "status",
"in": "query",
"schema": {
"type": "string",
"enum": [
"available",
"accepted",
"expired"
]
},
"description": "Filter by offer status"
},
{
"$ref": "#/components/parameters/StartingAfter"
},
{
"$ref": "#/components/parameters/Limit"
}
],
"responses": {
"200": {
"description": "List of credit offers",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"data",
"has_more"
],
"properties": {
"data": {
"type": "array",
"items": {
"$ref": "#/components/schemas/CreditOffer"
}
},
"has_more": {
"type": "boolean"
}
}
},
"example": {
"data": [
{
"id": "co_550e8400e29b41d4a716446655440000",
"customer_id": "cust_550e8400e29b41d4a716446655440000",
"status": "available",
"approved_amount": 50000,
"min_amount": 200,
"monthly_interest_rate": 3.5,
"installments": 12,
"due_date_rule": null,
"valid_until": 1775253599,
"created_at": 1772791200,
"updated_at": 1772877600
}
],
"has_more": false
}
}
}
},
"400": {
"description": "Bad request",
"content": {
"application/problem+json": {
"schema": {
"type": "object",
"required": [
"type",
"title",
"status",
"detail",
"code"
],
"properties": {
"type": {
"type": "string",
"const": "https://docs.dinie.com/errors/invalid-request"
},
"title": {
"type": "string",
"const": "Invalid Request"
},
"status": {
"type": "integer",
"const": 400
},
"detail": {
"type": "string"
},
"code": {
"type": "string",
"enum": [
"invalid_limit",
"invalid_cursor"
],
"x-enumDescriptions": {
"invalid_limit": "`limit` is not a valid integer or is outside 1–100 range",
"invalid_cursor": "`starting_after` references a non-existent or inaccessible credit offer"
}
}
}
},
"examples": {
"invalid_limit": {
"summary": "`limit` is not a valid integer or is outside 1–100 range",
"value": {
"type": "https://docs.dinie.com/errors/invalid-request",
"title": "Invalid Request",
"status": 400,
"detail": "`limit` is not a valid integer or is outside 1–100 range",
"code": "invalid_limit"
}
},
"invalid_cursor": {
"summary": "`starting_after` references a non-existent or inaccessible credit offer",
"value": {
"type": "https://docs.dinie.com/errors/invalid-request",
"title": "Invalid Request",
"status": 400,
"detail": "`starting_after` references a non-existent or inaccessible credit offer",
"code": "invalid_cursor"
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/BearerTokenUnauthorized",
"description": "Authentication failed"
},
"404": {
"description": "Resource not found",
"content": {
"application/problem+json": {
"schema": {
"type": "object",
"required": [
"type",
"title",
"status",
"detail",
"code"
],
"properties": {
"type": {
"type": "string",
"const": "https://docs.dinie.com/errors/not-found"
},
"title": {
"type": "string",
"const": "Not Found"
},
"status": {
"type": "integer",
"const": 404
},
"detail": {
"type": "string"
},
"code": {
"type": "string",
"const": "customer_not_found",
"x-enumDescriptions": {
"customer_not_found": "`customer_id` filter references a non-existent or inaccessible customer"
}
}
}
},
"examples": {
"customer_not_found": {
"summary": "`customer_id` filter references a non-existent or inaccessible customer",
"value": {
"type": "https://docs.dinie.com/errors/not-found",
"title": "Not Found",
"status": 404,
"detail": "`customer_id` filter references a non-existent or inaccessible customer",
"code": "customer_not_found"
}
}
}
}
}
},
"429": {
"$ref": "#/components/responses/RateLimited",
"description": "Rate limit exceeded"
},
"500": {
"$ref": "#/components/responses/InternalError",
"description": "Internal server error"
}
},
"x-codeSamples": [
{
"lang": "curl",
"source": "# List all available credit offers\ncurl \"https://api.dinie.com/api/v3/credit-offers?status=available&limit=10\" \\\n -H \"Authorization: Bearer $DINIE_API_TOKEN\"\n"
},
{
"lang": "Python",
"source": "from dinie import Dinie\n\nclient = Dinie(\n client_id=\"dinie_ci_abc123\",\n client_secret=\"dinie_cs_live_xyz789\"\n)\n\n# List all available credit offers across customers\noffers = client.credit_offers.list(\n status=\"available\",\n limit=10\n)\n\nfor offer in offers.data:\n print(f\"Customer {offer.customer_id}: R$ {offer.approved_amount}\")\n\n# Filter by specific customer\noffers = client.credit_offers.list(\n customer_id=\"cust_550e8400e29b41d4a716446655440000\",\n status=\"available\"\n)\n"
},
{
"lang": "Node.js",
"source": "const { Dinie } = require(\"dinie\");\n\nconst client = new Dinie({\n clientId: \"dinie_ci_abc123\",\n clientSecret: \"dinie_cs_live_xyz789\",\n});\n\n// List all available credit offers across customers\nconst offers = await client.creditOffers.list({\n status: \"available\",\n limit: 10,\n});\n\nfor (const offer of offers.data) {\n console.log(`Customer ${offer.customerId}: R$ ${offer.approvedAmount}`);\n}\n\n// Filter by specific customer\nconst filtered = await client.creditOffers.list({\n customerId: \"cust_550e8400e29b41d4a716446655440000\",\n status: \"available\",\n});\n"
},
{
"lang": "Ruby",
"source": "require \"dinie\"\n\nclient = Dinie::Client.new(\n client_id: \"dinie_ci_abc123\",\n client_secret: \"dinie_cs_live_xyz789\"\n)\n\n# List all available credit offers across customers\noffers = client.credit_offers.list(\n status: \"available\",\n limit: 10\n)\n\noffers.data.each do |offer|\n puts \"Customer #{offer.customer_id}: R$ #{offer.approved_amount}\"\nend\n\n# Filter by specific customer\noffers = client.credit_offers.list(\n customer_id: \"cust_550e8400e29b41d4a716446655440000\",\n status: \"available\"\n)\n"
}
]
}
},
"/credit-offers/{credit_offer_id}": {
"get": {
"operationId": "getCreditOffer",
"summary": "Get a credit offer",
"description": "GET /credit-offers/{credit_offer_id}
\n\nGet a credit offer",
"tags": [
"Credit Offers"
],
"parameters": [
{
"$ref": "#/components/parameters/CreditOfferId"
}
],
"responses": {
"200": {
"description": "Credit offer details",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CreditOffer"
},
"example": {
"id": "co_550e8400e29b41d4a716446655440000",
"customer_id": "cust_550e8400e29b41d4a716446655440000",
"external_id": "partner-ref-123",
"status": "available",
"approved_amount": 50000,
"min_amount": 200,
"monthly_interest_rate": 3.5,
"installments": 12,
"due_date_rule": null,
"valid_until": 1775253599,
"created_at": 1772791200,
"updated_at": 1772877600
}
}
}
},
"401": {
"$ref": "#/components/responses/BearerTokenUnauthorized",
"description": "Authentication failed"
},
"404": {
"description": "Resource not found",
"content": {
"application/problem+json": {
"schema": {
"type": "object",
"required": [
"type",
"title",
"status",
"detail",
"code"
],
"properties": {
"type": {
"type": "string",
"const": "https://docs.dinie.com/errors/not-found"
},
"title": {
"type": "string",
"const": "Not Found"
},
"status": {
"type": "integer",
"const": 404
},
"detail": {
"type": "string"
},
"code": {
"type": "string",
"const": "credit_offer_not_found",
"x-enumDescriptions": {
"credit_offer_not_found": "Credit offer ID does not exist or does not belong to this partner"
}
}
}
},
"examples": {
"credit_offer_not_found": {
"summary": "Credit offer ID does not exist or does not belong to this partner",
"value": {
"type": "https://docs.dinie.com/errors/not-found",
"title": "Not Found",
"status": 404,
"detail": "Credit offer ID does not exist or does not belong to this partner",
"code": "credit_offer_not_found"
}
}
}
}
}
},
"429": {
"$ref": "#/components/responses/RateLimited",
"description": "Rate limit exceeded"
},
"500": {
"$ref": "#/components/responses/InternalError",
"description": "Internal server error"
}
},
"x-codeSamples": [
{
"lang": "curl",
"source": "curl https://api.dinie.com/api/v3/credit-offers/co_550e8400e29b41d4a716446655440000 \\\n -H \"Authorization: Bearer $DINIE_API_TOKEN\"\n"
},
{
"lang": "Python",
"source": "from dinie import Dinie\n\nclient = Dinie(\n client_id=\"dinie_ci_abc123\",\n client_secret=\"dinie_cs_live_xyz789\"\n)\n\n# Retrieve a credit offer\noffer = client.credit_offers.retrieve(\"co_550e8400e29b41d4a716446655440000\")\n\nprint(offer.approved_amount) # 50000.00\nprint(offer.min_amount) # 200.00\nprint(offer.monthly_interest_rate) # 3.50\nprint(offer.valid_until) # 1775253599\n"
},
{
"lang": "Node.js",
"source": "const { Dinie } = require(\"dinie\");\n\nconst client = new Dinie({\n clientId: \"dinie_ci_abc123\",\n clientSecret: \"dinie_cs_live_xyz789\",\n});\n\n// Retrieve a credit offer\nconst offer = await client.creditOffers.retrieve(\n \"co_550e8400e29b41d4a716446655440000\"\n);\n\nconsole.log(offer.approvedAmount); // 50000.00\nconsole.log(offer.minAmount); // 200.00\nconsole.log(offer.interestRate); // 3.50\nconsole.log(offer.validUntil); // 1775253599\n"
},
{
"lang": "Ruby",
"source": "require \"dinie\"\n\nclient = Dinie::Client.new(\n client_id: \"dinie_ci_abc123\",\n client_secret: \"dinie_cs_live_xyz789\"\n)\n\n# Retrieve a credit offer\noffer = client.credit_offers.retrieve(\"co_550e8400e29b41d4a716446655440000\")\n\nputs offer.approved_amount # 50000.00\nputs offer.min_amount # 200.00\nputs offer.monthly_interest_rate # 3.50\nputs offer.valid_until # 1775253599\n"
}
]
}
},
"/credit-offers/{credit_offer_id}/simulations": {
"post": {
"operationId": "createSimulation",
"summary": "Simulate a loan",
"description": "POST /credit-offers/{credit_offer_id}/simulations
\n\nSimulate loan terms for a credit offer",
"tags": [
"Loans"
],
"parameters": [
{
"$ref": "#/components/parameters/CreditOfferId"
},
{
"$ref": "#/components/parameters/IdempotencyKey"
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CreateSimulationRequest"
},
"example": {
"requested_amount": 25000,
"installment_count": 4
}
}
}
},
"responses": {
"201": {
"description": "Simulation created",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Simulation"
},
"example": {
"id": "sim_550e8400e29b41d4a716446655440001",
"credit_offer_id": "co_550e8400e29b41d4a716446655440000",
"requested_amount": 25000,
"principal_amount": 29375,
"interest_amount": 2614.36,
"iof_amount": 1875,
"fee_amount": 2500,
"total_amount": 31989.36,
"monthly_interest_rate": 3.5,
"annual_interest_rate": 51.11,
"monthly_cet_rate": 2,
"annual_cet_rate": 233.18,
"installment_count": 4,
"installment_amount": 7997.34,
"first_due_date": "2026-04-03",
"created_at": 1709548200
}
}
}
},
"400": {
"description": "Bad request",
"content": {
"application/problem+json": {
"schema": {
"type": "object",
"required": [
"type",
"title",
"status",
"detail",
"code"
],
"properties": {
"type": {
"type": "string",
"const": "https://docs.dinie.com/errors/invalid-request"
},
"title": {
"type": "string",
"const": "Invalid Request"
},
"status": {
"type": "integer",
"const": 400
},
"detail": {
"type": "string"
},
"code": {
"type": "string",
"enum": [
"invalid_content_type",
"malformed_body"
],
"x-enumDescriptions": {
"invalid_content_type": "`Content-Type` is not `application/json`",
"malformed_body": "Request body is not valid JSON"
}
}
}
},
"examples": {
"invalid_content_type": {
"summary": "`Content-Type` is not `application/json`",
"value": {
"type": "https://docs.dinie.com/errors/invalid-request",
"title": "Invalid Request",
"status": 400,
"detail": "`Content-Type` is not `application/json`",
"code": "invalid_content_type"
}
},
"malformed_body": {
"summary": "Request body is not valid JSON",
"value": {
"type": "https://docs.dinie.com/errors/invalid-request",
"title": "Invalid Request",
"status": 400,
"detail": "Request body is not valid JSON",
"code": "malformed_body"
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/BearerTokenUnauthorized",
"description": "Authentication failed"
},
"404": {
"description": "Resource not found",
"content": {
"application/problem+json": {
"schema": {
"type": "object",
"required": [
"type",
"title",
"status",
"detail",
"code"
],
"properties": {
"type": {
"type": "string",
"const": "https://docs.dinie.com/errors/not-found"
},
"title": {
"type": "string",
"const": "Not Found"
},
"status": {
"type": "integer",
"const": 404
},
"detail": {
"type": "string"
},
"code": {
"type": "string",
"const": "credit_offer_not_found",
"x-enumDescriptions": {
"credit_offer_not_found": "Credit offer ID does not exist or does not belong to this partner"
}
}
}
},
"examples": {
"credit_offer_not_found": {
"summary": "Credit offer ID does not exist or does not belong to this partner",
"value": {
"type": "https://docs.dinie.com/errors/not-found",
"title": "Not Found",
"status": 404,
"detail": "Credit offer ID does not exist or does not belong to this partner",
"code": "credit_offer_not_found"
}
}
}
}
}
},
"422": {
"description": "Validation failed",
"content": {
"application/problem+json": {
"schema": {
"type": "object",
"required": [
"type",
"title",
"status",
"detail",
"code"
],
"properties": {
"type": {
"type": "string",
"const": "https://docs.dinie.com/errors/validation-failed"
},
"title": {
"type": "string",
"const": "Validation Failed"
},
"status": {
"type": "integer",
"const": 422
},
"detail": {
"type": "string"
},
"code": {
"type": "string",
"enum": [
"offer_expired",
"offer_already_accepted",
"invalid_amount",
"invalid_installments"
],
"x-enumDescriptions": {
"offer_expired": "Credit offer status is `expired`",
"offer_already_accepted": "Credit offer status is `accepted`",
"invalid_amount": "`requested_amount` exceeds `approved_amount`, is below `min_amount`, or is not a valid monetary value",
"invalid_installments": "`installment_count` is outside the allowed range"
}
}
}
},
"examples": {
"offer_expired": {
"summary": "Credit offer status is `expired`",
"value": {
"type": "https://docs.dinie.com/errors/validation-failed",
"title": "Validation Failed",
"status": 422,
"detail": "Credit offer status is `expired`",
"code": "offer_expired"
}
},
"offer_already_accepted": {
"summary": "Credit offer status is `accepted`",
"value": {
"type": "https://docs.dinie.com/errors/validation-failed",
"title": "Validation Failed",
"status": 422,
"detail": "Credit offer status is `accepted`",
"code": "offer_already_accepted"
}
},
"invalid_amount": {
"summary": "`requested_amount` exceeds `approved_amount`, is below `min_amount`, or is not a valid monetary value",
"value": {
"type": "https://docs.dinie.com/errors/validation-failed",
"title": "Validation Failed",
"status": 422,
"detail": "`requested_amount` exceeds `approved_amount`, is below `min_amount`, or is not a valid monetary value",
"code": "invalid_amount"
}
},
"invalid_installments": {
"summary": "`installment_count` is outside the allowed range",
"value": {
"type": "https://docs.dinie.com/errors/validation-failed",
"title": "Validation Failed",
"status": 422,
"detail": "`installment_count` is outside the allowed range",
"code": "invalid_installments"
}
}
}
}
}
},
"429": {
"$ref": "#/components/responses/RateLimited",
"description": "Rate limit exceeded"
},
"500": {
"$ref": "#/components/responses/InternalError",
"description": "Internal server error"
}
},
"x-codeSamples": [
{
"lang": "curl",
"source": "curl -X POST https://api.dinie.com/api/v3/credit-offers/co_550e8400e29b41d4a716446655440000/simulations \\\n -H \"Authorization: Bearer $DINIE_API_TOKEN\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"requested_amount\": 25000.00,\n \"installment_count\": 12\n }'\n"
},
{
"lang": "Python",
"source": "from dinie import Dinie\n\nclient = Dinie(\n client_id=\"dinie_ci_abc123\",\n client_secret=\"dinie_cs_live_xyz789\"\n)\n\n# Simulate a loan scenario\nsimulation = client.credit_offers.simulate(\n \"co_550e8400e29b41d4a716446655440000\",\n requested_amount=25000.00,\n installment_count=4\n)\n\nprint(simulation.id) # \"sim_550e8400...\"\nprint(simulation.installment_amount) # 7997.34\nprint(simulation.annual_cet_rate) # 233.18\nprint(simulation.total_amount) # 31989.36\nprint(simulation.first_due_date) # \"2026-04-03\"\n"
},
{
"lang": "Node.js",
"source": "const { Dinie } = require(\"dinie\");\n\nconst client = new Dinie({\n clientId: \"dinie_ci_abc123\",\n clientSecret: \"dinie_cs_live_xyz789\",\n});\n\n// Simulate a loan scenario\nconst simulation = await client.creditOffers.simulate(\n \"co_550e8400e29b41d4a716446655440000\",\n {\n requestedAmount: 25000.00,\n installmentCount: 4,\n }\n);\n\nconsole.log(simulation.id); // \"sim_550e8400...\"\nconsole.log(simulation.installmentAmount); // 7997.34\nconsole.log(simulation.cetRate); // 233.18\nconsole.log(simulation.totalAmount); // 31989.36\nconsole.log(simulation.firstDueDate); // \"2026-04-03\"\n"
},
{
"lang": "Ruby",
"source": "require \"dinie\"\n\nclient = Dinie::Client.new(\n client_id: \"dinie_ci_abc123\",\n client_secret: \"dinie_cs_live_xyz789\"\n)\n\n# Simulate a loan scenario\nsimulation = client.credit_offers.simulate(\n \"co_550e8400e29b41d4a716446655440000\",\n requested_amount: 25000.00,\n installment_count: 4\n)\n\nputs simulation.id # \"sim_550e8400...\"\nputs simulation.installment_amount # 7997.34\nputs simulation.annual_cet_rate # 233.18\nputs simulation.total_amount # 31989.36\nputs simulation.first_due_date # \"2026-04-03\"\n"
}
]
}
},
"/loans": {
"post": {
"operationId": "createLoan",
"summary": "Create a loan",
"description": "POST /loans
\n\nAccept a credit offer and create a loan",
"tags": [
"Loans"
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CreateLoanRequest"
},
"example": {
"credit_offer_id": "co_550e8400e29b41d4a716446655440000",
"simulation_id": "sim_550e8400e29b41d4a716446655440001",
"installment_count": 4,
"installment_amount": 7997.34,
"first_due_date": "2026-04-03"
}
}
}
},
"responses": {
"201": {
"description": "Loan created",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Loan"
},
"example": {
"id": "ln_550e8400e29b41d4a716446655440001",
"credit_offer_id": "co_550e8400e29b41d4a716446655440000",
"customer_id": "cust_550e8400e29b41d4a716446655440000",
"simulation_id": "sim_550e8400e29b41d4a716446655440001",
"status": "awaiting_signatures",
"requested_amount": 25000,
"principal_amount": 29375,
"iof_amount": 1875,
"monthly_interest_rate": 3.5,
"annual_interest_rate": 51.11,
"monthly_cet_rate": 2,
"annual_cet_rate": 233.18,
"total_amount": 31989.36,
"installment_amount": 7997.34,
"first_due_date": "2026-04-03",
"installment_count": 4,
"ccb_number": "CCB-2026-001234",
"disbursement_method": "pix",
"signing_url": "https://clicksign.com/widget/...",
"created_at": 1709550000,
"updated_at": 1709550000
}
}
}
},
"400": {
"description": "Bad request",
"content": {
"application/problem+json": {
"schema": {
"type": "object",
"required": [
"type",
"title",
"status",
"detail",
"code"
],
"properties": {
"type": {
"type": "string",
"const": "https://docs.dinie.com/errors/invalid-request"
},
"title": {
"type": "string",
"const": "Invalid Request"
},
"status": {
"type": "integer",
"const": 400
},
"detail": {
"type": "string"
},
"code": {
"type": "string",
"enum": [
"invalid_content_type",
"malformed_body"
],
"x-enumDescriptions": {
"invalid_content_type": "`Content-Type` is not `application/json`",
"malformed_body": "Request body is not valid JSON"
}
}
}
},
"examples": {
"invalid_content_type": {
"summary": "`Content-Type` is not `application/json`",
"value": {
"type": "https://docs.dinie.com/errors/invalid-request",
"title": "Invalid Request",
"status": 400,
"detail": "`Content-Type` is not `application/json`",
"code": "invalid_content_type"
}
},
"malformed_body": {
"summary": "Request body is not valid JSON",
"value": {
"type": "https://docs.dinie.com/errors/invalid-request",
"title": "Invalid Request",
"status": 400,
"detail": "Request body is not valid JSON",
"code": "malformed_body"
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/BearerTokenUnauthorized",
"description": "Authentication failed"
},
"404": {
"description": "Resource not found",
"content": {
"application/problem+json": {
"schema": {
"type": "object",
"required": [
"type",
"title",
"status",
"detail",
"code"
],
"properties": {
"type": {
"type": "string",
"const": "https://docs.dinie.com/errors/not-found"
},
"title": {
"type": "string",
"const": "Not Found"
},
"status": {
"type": "integer",
"const": 404
},
"detail": {
"type": "string"
},
"code": {
"type": "string",
"const": "credit_offer_not_found",
"x-enumDescriptions": {
"credit_offer_not_found": "`credit_offer_id` does not exist or does not belong to this partner"
}
}
}
},
"examples": {
"credit_offer_not_found": {
"summary": "`credit_offer_id` does not exist or does not belong to this partner",
"value": {
"type": "https://docs.dinie.com/errors/not-found",
"title": "Not Found",
"status": 404,
"detail": "`credit_offer_id` does not exist or does not belong to this partner",
"code": "credit_offer_not_found"
}
}
}
}
}
},
"409": {
"description": "Conflict",
"content": {
"application/problem+json": {
"schema": {
"type": "object",
"required": [
"type",
"title",
"status",
"detail",
"code"
],
"properties": {
"type": {
"type": "string",
"const": "https://docs.dinie.com/errors/conflict"
},
"title": {
"type": "string",
"const": "Conflict"
},
"status": {
"type": "integer",
"const": 409
},
"detail": {
"type": "string"
},
"code": {
"type": "string",
"enum": [
"offer_already_accepted",
"withdrawal_locked"
],
"x-enumDescriptions": {
"offer_already_accepted": "A loan already exists for this credit offer",
"withdrawal_locked": "Another withdrawal is being processed for this customer (concurrent lock)"
}
}
}
},
"examples": {
"offer_already_accepted": {
"summary": "A loan already exists for this credit offer",
"value": {
"type": "https://docs.dinie.com/errors/conflict",
"title": "Conflict",
"status": 409,
"detail": "A loan already exists for this credit offer",
"code": "offer_already_accepted"
}
},
"withdrawal_locked": {
"summary": "Another withdrawal is being processed for this customer (concurrent lock)",
"value": {
"type": "https://docs.dinie.com/errors/conflict",
"title": "Conflict",
"status": 409,
"detail": "Another withdrawal is being processed for this customer (concurrent lock)",
"code": "withdrawal_locked"
}
}
}
}
}
},
"422": {
"description": "Validation failed",
"content": {
"application/problem+json": {
"schema": {
"type": "object",
"required": [
"type",
"title",
"status",
"detail",
"code"
],
"properties": {
"type": {
"type": "string",
"const": "https://docs.dinie.com/errors/validation-failed"
},
"title": {
"type": "string",
"const": "Validation Failed"
},
"status": {
"type": "integer",
"const": 422
},
"detail": {
"type": "string"
},
"code": {
"type": "string",
"enum": [
"missing_required_field",
"offer_expired",
"kyc_incomplete",
"invalid_amount",
"invalid_installments",
"simulation_mismatch"
],
"x-enumDescriptions": {
"missing_required_field": "Required field is missing (`credit_offer_id`, `simulation_id`, `installment_count`, `installment_amount`, `first_due_date`)",
"offer_expired": "Credit offer has expired (`valid_until` has passed or superseded)",
"kyc_incomplete": "Customer has pending or rejected KYC requirements",
"invalid_amount": "`amount` exceeds `approved_amount` or is not a valid monetary value",
"invalid_installments": "`installment_count` is outside the allowed range",
"simulation_mismatch": "`installment_count`, `installment_amount`, or `first_due_date` do not match the referenced simulation"
}
}
}
},
"examples": {
"missing_required_field": {
"summary": "Required field is missing (`credit_offer_id`, `simulation_id`, `installment_count`, `installment_amount`, `first_due_date`)",
"value": {
"type": "https://docs.dinie.com/errors/validation-failed",
"title": "Validation Failed",
"status": 422,
"detail": "Required field is missing (`credit_offer_id`, `simulation_id`, `installment_count`, `installment_amount`, `first_due_date`)",
"code": "missing_required_field"
}
},
"offer_expired": {
"summary": "Credit offer has expired (`valid_until` has passed or superseded)",
"value": {
"type": "https://docs.dinie.com/errors/validation-failed",
"title": "Validation Failed",
"status": 422,
"detail": "Credit offer has expired (`valid_until` has passed or superseded)",
"code": "offer_expired"
}
},
"kyc_incomplete": {
"summary": "Customer has pending or rejected KYC requirements",
"value": {
"type": "https://docs.dinie.com/errors/validation-failed",
"title": "Validation Failed",
"status": 422,
"detail": "Customer has pending or rejected KYC requirements",
"code": "kyc_incomplete"
}
},
"invalid_amount": {
"summary": "`amount` exceeds `approved_amount` or is not a valid monetary value",
"value": {
"type": "https://docs.dinie.com/errors/validation-failed",
"title": "Validation Failed",
"status": 422,
"detail": "`amount` exceeds `approved_amount` or is not a valid monetary value",
"code": "invalid_amount"
}
},
"invalid_installments": {
"summary": "`installment_count` is outside the allowed range",
"value": {
"type": "https://docs.dinie.com/errors/validation-failed",
"title": "Validation Failed",
"status": 422,
"detail": "`installment_count` is outside the allowed range",
"code": "invalid_installments"
}
},
"simulation_mismatch": {
"summary": "`installment_count`, `installment_amount`, or `first_due_date` do not match the referenced simulation",
"value": {
"type": "https://docs.dinie.com/errors/validation-failed",
"title": "Validation Failed",
"status": 422,
"detail": "`installment_count`, `installment_amount`, or `first_due_date` do not match the referenced simulation",
"code": "simulation_mismatch"
}
}
}
}
}
},
"429": {
"$ref": "#/components/responses/RateLimited",
"description": "Rate limit exceeded"
},
"500": {
"$ref": "#/components/responses/InternalError",
"description": "Internal server error"
}
},
"x-codeSamples": [
{
"lang": "curl",
"source": "curl -X POST https://api.dinie.com/api/v3/loans \\\n -H \"Authorization: Bearer $DINIE_API_TOKEN\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"credit_offer_id\": \"co_550e8400e29b41d4a716446655440000\",\n \"simulation_id\": \"sim_550e8400e29b41d4a716446655440001\",\n \"installment_count\": 4,\n \"installment_amount\": 7997.34,\n \"first_due_date\": \"2026-04-03\"\n }'\n"
},
{
"lang": "Python",
"source": "from dinie import Dinie\n\nclient = Dinie(\n client_id=\"dinie_ci_abc123\",\n client_secret=\"dinie_cs_live_xyz789\"\n)\n\n# Create a loan from a simulation\nloan = client.loans.create(\n credit_offer_id=\"co_550e8400e29b41d4a716446655440000\",\n simulation_id=\"sim_550e8400e29b41d4a716446655440001\",\n installment_count=4,\n installment_amount=7997.34,\n first_due_date=\"2026-04-03\"\n)\n\nprint(loan.id) # \"ln_550e8400...\"\nprint(loan.status) # \"awaiting_signatures\"\n"
},
{
"lang": "Node.js",
"source": "const { Dinie } = require(\"dinie\");\n\nconst client = new Dinie({\n clientId: \"dinie_ci_abc123\",\n clientSecret: \"dinie_cs_live_xyz789\",\n});\n\n// Create a loan from a simulation\nconst loan = await client.loans.create({\n creditOfferId: \"co_550e8400e29b41d4a716446655440000\",\n simulationId: \"sim_550e8400e29b41d4a716446655440001\",\n installmentCount: 4,\n installmentAmount: 7997.34,\n firstDueDate: \"2026-04-03\",\n});\n\nconsole.log(loan.id); // \"ln_550e8400...\"\nconsole.log(loan.status); // \"awaiting_signatures\"\n"
},
{
"lang": "Ruby",
"source": "require \"dinie\"\n\nclient = Dinie::Client.new(\n client_id: \"dinie_ci_abc123\",\n client_secret: \"dinie_cs_live_xyz789\"\n)\n\n# Create a loan from a simulation\nloan = client.loans.create(\n credit_offer_id: \"co_550e8400e29b41d4a716446655440000\",\n simulation_id: \"sim_550e8400e29b41d4a716446655440001\",\n installment_count: 4,\n installment_amount: 7997.34,\n first_due_date: \"2026-04-03\"\n)\n\nputs loan.id # \"ln_550e8400...\"\nputs loan.status # \"awaiting_signatures\"\n"
}
]
}
},
"/loans/{loan_id}": {
"get": {
"operationId": "getLoan",
"summary": "Get a loan",
"description": "GET /loans/{loan_id}
\n\nGet a loan",
"tags": [
"Loans"
],
"parameters": [
{
"$ref": "#/components/parameters/LoanId"
}
],
"responses": {
"200": {
"description": "Loan details",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Loan"
},
"example": {
"id": "ln_550e8400e29b41d4a716446655440001",
"credit_offer_id": "co_550e8400e29b41d4a716446655440000",
"customer_id": "cust_550e8400e29b41d4a716446655440000",
"simulation_id": "sim_550e8400e29b41d4a716446655440001",
"status": "active",
"requested_amount": 25000,
"principal_amount": 29375,
"iof_amount": 1875,
"monthly_interest_rate": 3.5,
"annual_interest_rate": 51.11,
"monthly_cet_rate": 2,
"annual_cet_rate": 233.18,
"total_amount": 31989.36,
"installment_amount": 7997.34,
"first_due_date": "2026-04-03",
"installment_count": 4,
"ccb_number": "CCB-2026-001234",
"disbursement_method": "pix",
"signing_url": null,
"created_at": 1709550000,
"updated_at": 1709647200
}
}
}
},
"401": {
"$ref": "#/components/responses/BearerTokenUnauthorized",
"description": "Authentication failed"
},
"404": {
"description": "Resource not found",
"content": {
"application/problem+json": {
"schema": {
"type": "object",
"required": [
"type",
"title",
"status",
"detail",
"code"
],
"properties": {
"type": {
"type": "string",
"const": "https://docs.dinie.com/errors/not-found"
},
"title": {
"type": "string",
"const": "Not Found"
},
"status": {
"type": "integer",
"const": 404
},
"detail": {
"type": "string"
},
"code": {
"type": "string",
"const": "loan_not_found",
"x-enumDescriptions": {
"loan_not_found": "Loan ID does not exist or does not belong to this partner"
}
}
}
},
"examples": {
"loan_not_found": {
"summary": "Loan ID does not exist or does not belong to this partner",
"value": {
"type": "https://docs.dinie.com/errors/not-found",
"title": "Not Found",
"status": 404,
"detail": "Loan ID does not exist or does not belong to this partner",
"code": "loan_not_found"
}
}
}
}
}
},
"429": {
"$ref": "#/components/responses/RateLimited",
"description": "Rate limit exceeded"
},
"500": {
"$ref": "#/components/responses/InternalError",
"description": "Internal server error"
}
},
"x-codeSamples": [
{
"lang": "curl",
"source": "curl https://api.dinie.com/api/v3/loans/ln_550e8400e29b41d4a716446655440001 \\\n -H \"Authorization: Bearer $DINIE_API_TOKEN\"\n"
},
{
"lang": "Python",
"source": "from dinie import Dinie\n\nclient = Dinie(\n client_id=\"dinie_ci_abc123\",\n client_secret=\"dinie_cs_live_xyz789\"\n)\n\n# Retrieve a loan\nloan = client.loans.retrieve(\"ln_550e8400e29b41d4a716446655440001\")\n\nprint(loan.status) # \"active\"\nprint(loan.requested_amount) # 25000.00\nprint(loan.principal_amount) # 29375.00\nprint(loan.ccb_number) # \"CCB-2026-001234\"\nprint(loan.signing_url) # None (already signed)\n"
},
{
"lang": "Node.js",
"source": "const { Dinie } = require(\"dinie\");\n\nconst client = new Dinie({\n clientId: \"dinie_ci_abc123\",\n clientSecret: \"dinie_cs_live_xyz789\",\n});\n\n// Retrieve a loan\nconst loan = await client.loans.retrieve(\n \"ln_550e8400e29b41d4a716446655440001\"\n);\n\nconsole.log(loan.status); // \"active\"\nconsole.log(loan.requestedAmount); // 25000.00\nconsole.log(loan.principalAmount); // 29375.00\nconsole.log(loan.ccbNumber); // \"CCB-2026-001234\"\nconsole.log(loan.signingUrl); // null (already signed)\n"
},
{
"lang": "Ruby",
"source": "require \"dinie\"\n\nclient = Dinie::Client.new(\n client_id: \"dinie_ci_abc123\",\n client_secret: \"dinie_cs_live_xyz789\"\n)\n\n# Retrieve a loan\nloan = client.loans.retrieve(\"ln_550e8400e29b41d4a716446655440001\")\n\nputs loan.status # \"active\"\nputs loan.requested_amount # 25000.00\nputs loan.principal_amount # 29375.00\nputs loan.ccb_number # \"CCB-2026-001234\"\nputs loan.signing_url # nil (already signed)\n"
}
]
}
},
"/loans/{loan_id}/transactions": {
"get": {
"operationId": "listTransactions",
"summary": "List transactions",
"description": "GET /loans/{loan_id}/transactions
\n\nList a loan's transactions",
"tags": [
"Loans"
],
"parameters": [
{
"$ref": "#/components/parameters/LoanId"
},
{
"$ref": "#/components/parameters/StartingAfter"
},
{
"$ref": "#/components/parameters/Limit"
}
],
"responses": {
"200": {
"description": "List of transactions",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"data",
"has_more"
],
"properties": {
"data": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Transaction"
}
},
"has_more": {
"type": "boolean"
}
}
},
"example": {
"data": [
{
"id": "tx_550e8400e29b41d4a716446655440000",
"loan_id": "ln_550e8400e29b41d4a716446655440001",
"type": "installment",
"due_date": "2026-04-03",
"status": "paid",
"amount_due": 2500,
"amount_paid": 2500,
"amount_remaining": 0,
"principal": 2083.33,
"interest": 375,
"fees": 41.67,
"days_overdue": 0,
"paid_at": 1775383200,
"created_at": 1709550000,
"updated_at": 1775383200
},
{
"id": "tx_660e8400e29b41d4a716446655440001",
"loan_id": "ln_550e8400e29b41d4a716446655440001",
"type": "installment",
"due_date": "2026-05-03",
"status": "pending",
"amount_due": 2500,
"amount_paid": 0,
"amount_remaining": 2500,
"principal": 2083.33,
"interest": 375,
"fees": 41.67,
"days_overdue": 0,
"paid_at": null,
"created_at": 1709550000,
"updated_at": 1709550000
}
],
"has_more": true
}
}
}
},
"400": {
"description": "Bad request",
"content": {
"application/problem+json": {
"schema": {
"type": "object",
"required": [
"type",
"title",
"status",
"detail",
"code"
],
"properties": {
"type": {
"type": "string",
"const": "https://docs.dinie.com/errors/invalid-request"
},
"title": {
"type": "string",
"const": "Invalid Request"
},
"status": {
"type": "integer",
"const": 400
},
"detail": {
"type": "string"
},
"code": {
"type": "string",
"enum": [
"invalid_limit",
"invalid_cursor"
],
"x-enumDescriptions": {
"invalid_limit": "`limit` is not a valid integer or is outside 1–100 range",
"invalid_cursor": "`starting_after` references a non-existent transaction"
}
}
}
},
"examples": {
"invalid_limit": {
"summary": "`limit` is not a valid integer or is outside 1–100 range",
"value": {
"type": "https://docs.dinie.com/errors/invalid-request",
"title": "Invalid Request",
"status": 400,
"detail": "`limit` is not a valid integer or is outside 1–100 range",
"code": "invalid_limit"
}
},
"invalid_cursor": {
"summary": "`starting_after` references a non-existent transaction",
"value": {
"type": "https://docs.dinie.com/errors/invalid-request",
"title": "Invalid Request",
"status": 400,
"detail": "`starting_after` references a non-existent transaction",
"code": "invalid_cursor"
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/BearerTokenUnauthorized",
"description": "Authentication failed"
},
"404": {
"description": "Resource not found",
"content": {
"application/problem+json": {
"schema": {
"type": "object",
"required": [
"type",
"title",
"status",
"detail",
"code"
],
"properties": {
"type": {
"type": "string",
"const": "https://docs.dinie.com/errors/not-found"
},
"title": {
"type": "string",
"const": "Not Found"
},
"status": {
"type": "integer",
"const": 404
},
"detail": {
"type": "string"
},
"code": {
"type": "string",
"const": "loan_not_found",
"x-enumDescriptions": {
"loan_not_found": "Loan ID does not exist or does not belong to this partner"
}
}
}
},
"examples": {
"loan_not_found": {
"summary": "Loan ID does not exist or does not belong to this partner",
"value": {
"type": "https://docs.dinie.com/errors/not-found",
"title": "Not Found",
"status": 404,
"detail": "Loan ID does not exist or does not belong to this partner",
"code": "loan_not_found"
}
}
}
}
}
},
"429": {
"$ref": "#/components/responses/RateLimited",
"description": "Rate limit exceeded"
},
"500": {
"$ref": "#/components/responses/InternalError",
"description": "Internal server error"
}
},
"x-codeSamples": [
{
"lang": "curl",
"source": "curl \"https://api.dinie.com/api/v3/loans/ln_550e8400e29b41d4a716446655440001/transactions?limit=25\" \\\n -H \"Authorization: Bearer $DINIE_API_TOKEN\"\n"
},
{
"lang": "Python",
"source": "from dinie import Dinie\n\nclient = Dinie(\n client_id=\"dinie_ci_abc123\",\n client_secret=\"dinie_cs_live_xyz789\"\n)\n\n# List installments for a loan\ntransactions = client.loans.list_transactions(\n \"ln_550e8400e29b41d4a716446655440001\",\n limit=25\n)\n\nfor tx in transactions.data:\n print(f\"{tx.due_date}: R$ {tx.amount_due} ({tx.status})\")\n # \"2026-04-03: R$ 2500.00 (paid)\"\n # \"2026-05-03: R$ 2500.00 (pending)\"\n"
},
{
"lang": "Node.js",
"source": "const { Dinie } = require(\"dinie\");\n\nconst client = new Dinie({\n clientId: \"dinie_ci_abc123\",\n clientSecret: \"dinie_cs_live_xyz789\",\n});\n\n// List installments for a loan\nconst transactions = await client.loans.listTransactions(\n \"ln_550e8400e29b41d4a716446655440001\",\n { limit: 25 }\n);\n\nfor (const tx of transactions.data) {\n console.log(`${tx.dueDate}: R$ ${tx.amountDue} (${tx.status})`);\n // \"2026-04-03: R$ 2500.00 (paid)\"\n // \"2026-05-03: R$ 2500.00 (pending)\"\n}\n"
},
{
"lang": "Ruby",
"source": "require \"dinie\"\n\nclient = Dinie::Client.new(\n client_id: \"dinie_ci_abc123\",\n client_secret: \"dinie_cs_live_xyz789\"\n)\n\n# List installments for a loan\ntransactions = client.loans.list_transactions(\n \"ln_550e8400e29b41d4a716446655440001\",\n limit: 25\n)\n\ntransactions.data.each do |tx|\n puts \"#{tx.due_date}: R$ #{tx.amount_due} (#{tx.status})\"\n # \"2026-04-03: R$ 2500.00 (paid)\"\n # \"2026-05-03: R$ 2500.00 (pending)\"\nend\n"
}
]
}
},
"/webhooks/endpoints": {
"post": {
"operationId": "createWebhookEndpoint",
"summary": "Create a webhook",
"description": "POST /webhooks/endpoints
\n\nRegister a webhook endpoint",
"tags": [
"Webhooks"
],
"parameters": [
{
"$ref": "#/components/parameters/IdempotencyKey"
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CreateWebhookEndpointRequest"
},
"example": {
"url": "https://parceiro.example.com/webhooks/dinie",
"events": [
"customer.active",
"credit_offer.available",
"loan.*"
],
"description": "Webhook de produção"
}
}
}
},
"responses": {
"201": {
"description": "Webhook endpoint created",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/WebhookEndpointWithSecret"
},
"example": {
"id": "we_550e8400e29b41d4a716446655440000",
"url": "https://parceiro.example.com/webhooks/dinie",
"events": [
"customer.active",
"credit_offer.available",
"loan.*"
],
"description": "Webhook de produção",
"status": "active",
"secret": "whsec_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0",
"created_at": 1772791200,
"updated_at": 1772877600
}
}
}
},
"400": {
"description": "Bad request",
"content": {
"application/problem+json": {
"schema": {
"type": "object",
"required": [
"type",
"title",
"status",
"detail",
"code"
],
"properties": {
"type": {
"type": "string",
"const": "https://docs.dinie.com/errors/invalid-request"
},
"title": {
"type": "string",
"const": "Invalid Request"
},
"status": {
"type": "integer",
"const": 400
},
"detail": {
"type": "string"
},
"code": {
"type": "string",
"enum": [
"invalid_content_type",
"malformed_body"
],
"x-enumDescriptions": {
"invalid_content_type": "`Content-Type` is not `application/json`",
"malformed_body": "Request body is not valid JSON"
}
}
}
},
"examples": {
"invalid_content_type": {
"summary": "`Content-Type` is not `application/json`",
"value": {
"type": "https://docs.dinie.com/errors/invalid-request",
"title": "Invalid Request",
"status": 400,
"detail": "`Content-Type` is not `application/json`",
"code": "invalid_content_type"
}
},
"malformed_body": {
"summary": "Request body is not valid JSON",
"value": {
"type": "https://docs.dinie.com/errors/invalid-request",
"title": "Invalid Request",
"status": 400,
"detail": "Request body is not valid JSON",
"code": "malformed_body"
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/BearerTokenUnauthorized",
"description": "Authentication failed"
},
"422": {
"description": "Validation failed",
"content": {
"application/problem+json": {
"schema": {
"type": "object",
"required": [
"type",
"title",
"status",
"detail",
"code"
],
"properties": {
"type": {
"type": "string",
"const": "https://docs.dinie.com/errors/validation-failed"
},
"title": {
"type": "string",
"const": "Validation Failed"
},
"status": {
"type": "integer",
"const": 422
},
"detail": {
"type": "string"
},
"code": {
"type": "string",
"enum": [
"missing_required_field",
"invalid_url",
"invalid_events"
],
"x-enumDescriptions": {
"missing_required_field": "`url` is missing",
"invalid_url": "`url` is not a valid HTTPS URL",
"invalid_events": "`events` contains unrecognized event types"
}
}
}
},
"examples": {
"missing_required_field": {
"summary": "`url` is missing",
"value": {
"type": "https://docs.dinie.com/errors/validation-failed",
"title": "Validation Failed",
"status": 422,
"detail": "`url` is missing",
"code": "missing_required_field"
}
},
"invalid_url": {
"summary": "`url` is not a valid HTTPS URL",
"value": {
"type": "https://docs.dinie.com/errors/validation-failed",
"title": "Validation Failed",
"status": 422,
"detail": "`url` is not a valid HTTPS URL",
"code": "invalid_url"
}
},
"invalid_events": {
"summary": "`events` contains unrecognized event types",
"value": {
"type": "https://docs.dinie.com/errors/validation-failed",
"title": "Validation Failed",
"status": 422,
"detail": "`events` contains unrecognized event types",
"code": "invalid_events"
}
}
}
}
}
},
"429": {
"$ref": "#/components/responses/RateLimited",
"description": "Rate limit exceeded"
},
"500": {
"$ref": "#/components/responses/InternalError",
"description": "Internal server error"
}
},
"x-codeSamples": [
{
"lang": "curl",
"source": "curl -X POST https://api.dinie.com/api/v3/webhooks/endpoints \\\n -H \"Authorization: Bearer $DINIE_API_TOKEN\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"url\": \"https://parceiro.example.com/webhooks/dinie\",\n \"events\": [\"customer.active\", \"credit_offer.available\", \"loan.*\"],\n \"description\": \"Webhook de produção\"\n }'\n"
},
{
"lang": "Python",
"source": "from dinie import Dinie\n\nclient = Dinie(\n client_id=\"dinie_ci_abc123\",\n client_secret=\"dinie_cs_live_xyz789\"\n)\n\n# Create a webhook endpoint\nendpoint = client.webhooks.create_endpoint(\n url=\"https://parceiro.example.com/webhooks/dinie\",\n events=[\"customer.active\", \"credit_offer.available\", \"loan.*\"],\n description=\"Webhook de produção\"\n)\n\nprint(endpoint.id) # \"we_550e8400...\"\nprint(endpoint.secret) # \"whsec_a1b2c3...\"\n# Store the secret securely -- shown only once!\n"
},
{
"lang": "Node.js",
"source": "const { Dinie } = require(\"dinie\");\n\nconst client = new Dinie({\n clientId: \"dinie_ci_abc123\",\n clientSecret: \"dinie_cs_live_xyz789\",\n});\n\n// Create a webhook endpoint\nconst endpoint = await client.webhooks.createEndpoint({\n url: \"https://parceiro.example.com/webhooks/dinie\",\n events: [\"customer.active\", \"credit_offer.available\", \"loan.*\"],\n description: \"Webhook de produção\",\n});\n\nconsole.log(endpoint.id); // \"we_550e8400...\"\nconsole.log(endpoint.secret); // \"whsec_a1b2c3...\"\n// Store the secret securely -- shown only once!\n"
},
{
"lang": "Ruby",
"source": "require \"dinie\"\n\nclient = Dinie::Client.new(\n client_id: \"dinie_ci_abc123\",\n client_secret: \"dinie_cs_live_xyz789\"\n)\n\n# Create a webhook endpoint\nendpoint = client.webhooks.create_endpoint(\n url: \"https://parceiro.example.com/webhooks/dinie\",\n events: [\"customer.active\", \"credit_offer.available\", \"loan.*\"],\n description: \"Webhook de produção\"\n)\n\nputs endpoint.id # \"we_550e8400...\"\nputs endpoint.secret # \"whsec_a1b2c3...\"\n# Store the secret securely -- shown only once!\n"
}
]
},
"get": {
"operationId": "listWebhookEndpoints",
"summary": "List webhooks",
"description": "GET /webhooks/endpoints
\n\nList webhook endpoints",
"tags": [
"Webhooks"
],
"parameters": [
{
"$ref": "#/components/parameters/StartingAfter"
},
{
"$ref": "#/components/parameters/Limit"
}
],
"responses": {
"200": {
"description": "List of webhook endpoints",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"data",
"has_more"
],
"properties": {
"data": {
"type": "array",
"items": {
"$ref": "#/components/schemas/WebhookEndpoint"
}
},
"has_more": {
"type": "boolean"
}
}
},
"example": {
"data": [
{
"id": "we_550e8400e29b41d4a716446655440000",
"url": "https://parceiro.example.com/webhooks/dinie",
"events": [
"customer.active",
"credit_offer.available",
"loan.*"
],
"description": "Webhook de produção",
"status": "active",
"created_at": 1772791200,
"updated_at": 1772877600
}
],
"has_more": false
}
}
}
},
"401": {
"$ref": "#/components/responses/BearerTokenUnauthorized",
"description": "Authentication failed"
},
"429": {
"$ref": "#/components/responses/RateLimited",
"description": "Rate limit exceeded"
},
"500": {
"$ref": "#/components/responses/InternalError",
"description": "Internal server error"
}
},
"x-codeSamples": [
{
"lang": "curl",
"source": "curl https://api.dinie.com/api/v3/webhooks/endpoints \\\n -H \"Authorization: Bearer $DINIE_API_TOKEN\"\n"
},
{
"lang": "Python",
"source": "from dinie import Dinie\n\nclient = Dinie(\n client_id=\"dinie_ci_abc123\",\n client_secret=\"dinie_cs_live_xyz789\"\n)\n\n# List all webhook endpoints\nendpoints = client.webhooks.list_endpoints()\n\nfor ep in endpoints.data:\n print(f\"{ep.id}: {ep.url} ({ep.status})\")\n # \"we_550e8400...: https://parceiro.example.com/webhooks/dinie (active)\"\n"
},
{
"lang": "Node.js",
"source": "const { Dinie } = require(\"dinie\");\n\nconst client = new Dinie({\n clientId: \"dinie_ci_abc123\",\n clientSecret: \"dinie_cs_live_xyz789\",\n});\n\n// List all webhook endpoints\nconst endpoints = await client.webhooks.listEndpoints();\n\nfor (const ep of endpoints.data) {\n console.log(`${ep.id}: ${ep.url} (${ep.status})`);\n // \"we_550e8400...: https://parceiro.example.com/webhooks/dinie (active)\"\n}\n"
},
{
"lang": "Ruby",
"source": "require \"dinie\"\n\nclient = Dinie::Client.new(\n client_id: \"dinie_ci_abc123\",\n client_secret: \"dinie_cs_live_xyz789\"\n)\n\n# List all webhook endpoints\nendpoints = client.webhooks.list_endpoints\n\nendpoints.data.each do |ep|\n puts \"#{ep.id}: #{ep.url} (#{ep.status})\"\n # \"we_550e8400...: https://parceiro.example.com/webhooks/dinie (active)\"\nend\n"
}
]
}
},
"/webhooks/endpoints/{webhook_endpoint_id}": {
"get": {
"operationId": "getWebhookEndpoint",
"summary": "Get a webhook",
"description": "GET /webhooks/endpoints/{webhook_endpoint_id}
\n\nGet a webhook endpoint",
"tags": [
"Webhooks"
],
"parameters": [
{
"$ref": "#/components/parameters/WebhookEndpointId"
}
],
"responses": {
"200": {
"description": "Webhook endpoint details",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/WebhookEndpoint"
},
"example": {
"id": "we_550e8400e29b41d4a716446655440000",
"url": "https://parceiro.example.com/webhooks/dinie",
"events": [
"customer.active",
"credit_offer.available",
"loan.*"
],
"description": "Webhook de produção",
"status": "active",
"created_at": 1772791200,
"updated_at": 1772877600
}
}
}
},
"401": {
"$ref": "#/components/responses/BearerTokenUnauthorized",
"description": "Authentication failed"
},
"404": {
"description": "Resource not found",
"content": {
"application/problem+json": {
"schema": {
"type": "object",
"required": [
"type",
"title",
"status",
"detail",
"code"
],
"properties": {
"type": {
"type": "string",
"const": "https://docs.dinie.com/errors/not-found"
},
"title": {
"type": "string",
"const": "Not Found"
},
"status": {
"type": "integer",
"const": 404
},
"detail": {
"type": "string"
},
"code": {
"type": "string",
"const": "webhook_endpoint_not_found",
"x-enumDescriptions": {
"webhook_endpoint_not_found": "Endpoint ID does not exist or does not belong to this partner"
}
}
}
},
"examples": {
"webhook_endpoint_not_found": {
"summary": "Endpoint ID does not exist or does not belong to this partner",
"value": {
"type": "https://docs.dinie.com/errors/not-found",
"title": "Not Found",
"status": 404,
"detail": "Endpoint ID does not exist or does not belong to this partner",
"code": "webhook_endpoint_not_found"
}
}
}
}
}
},
"429": {
"$ref": "#/components/responses/RateLimited",
"description": "Rate limit exceeded"
},
"500": {
"$ref": "#/components/responses/InternalError",
"description": "Internal server error"
}
},
"x-codeSamples": [
{
"lang": "curl",
"source": "curl https://api.dinie.com/api/v3/webhooks/endpoints/we_550e8400e29b41d4a716446655440000 \\\n -H \"Authorization: Bearer $DINIE_API_TOKEN\"\n"
},
{
"lang": "Python",
"source": "from dinie import Dinie\n\nclient = Dinie(\n client_id=\"dinie_ci_abc123\",\n client_secret=\"dinie_cs_live_xyz789\"\n)\n\n# Retrieve a webhook endpoint\nendpoint = client.webhooks.retrieve_endpoint(\n \"we_550e8400e29b41d4a716446655440000\"\n)\n\nprint(endpoint.url) # \"https://parceiro.example.com/webhooks/dinie\"\nprint(endpoint.events) # [\"customer.active\", \"credit_offer.available\", \"loan.*\"]\nprint(endpoint.status) # \"active\"\n"
},
{
"lang": "Node.js",
"source": "const { Dinie } = require(\"dinie\");\n\nconst client = new Dinie({\n clientId: \"dinie_ci_abc123\",\n clientSecret: \"dinie_cs_live_xyz789\",\n});\n\n// Retrieve a webhook endpoint\nconst endpoint = await client.webhooks.retrieveEndpoint(\n \"we_550e8400e29b41d4a716446655440000\"\n);\n\nconsole.log(endpoint.url); // \"https://parceiro.example.com/webhooks/dinie\"\nconsole.log(endpoint.events); // [\"customer.active\", \"credit_offer.available\", \"loan.*\"]\nconsole.log(endpoint.status); // \"active\"\n"
},
{
"lang": "Ruby",
"source": "require \"dinie\"\n\nclient = Dinie::Client.new(\n client_id: \"dinie_ci_abc123\",\n client_secret: \"dinie_cs_live_xyz789\"\n)\n\n# Retrieve a webhook endpoint\nendpoint = client.webhooks.retrieve_endpoint(\n \"we_550e8400e29b41d4a716446655440000\"\n)\n\nputs endpoint.url # \"https://parceiro.example.com/webhooks/dinie\"\nputs endpoint.events # [\"customer.active\", \"credit_offer.available\", \"loan.*\"]\nputs endpoint.status # \"active\"\n"
}
]
},
"patch": {
"operationId": "updateWebhookEndpoint",
"summary": "Update a webhook",
"description": "PATCH /webhooks/endpoints/{webhook_endpoint_id}
\n\nUpdate a webhook endpoint",
"tags": [
"Webhooks"
],
"parameters": [
{
"$ref": "#/components/parameters/WebhookEndpointId"
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/UpdateWebhookEndpointRequest"
},
"example": {
"events": [
"customer.*",
"loan.*"
],
"status": "active"
}
}
}
},
"responses": {
"200": {
"description": "Webhook endpoint updated",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/WebhookEndpoint"
},
"example": {
"id": "we_550e8400e29b41d4a716446655440000",
"url": "https://parceiro.example.com/webhooks/dinie",
"events": [
"customer.*",
"loan.*"
],
"description": "Webhook de produção",
"status": "active",
"created_at": 1772791200,
"updated_at": 1709629200
}
}
}
},
"400": {
"description": "Bad request",
"content": {
"application/problem+json": {
"schema": {
"type": "object",
"required": [
"type",
"title",
"status",
"detail",
"code"
],
"properties": {
"type": {
"type": "string",
"const": "https://docs.dinie.com/errors/invalid-request"
},
"title": {
"type": "string",
"const": "Invalid Request"
},
"status": {
"type": "integer",
"const": 400
},
"detail": {
"type": "string"
},
"code": {
"type": "string",
"enum": [
"invalid_content_type",
"malformed_body"
],
"x-enumDescriptions": {
"invalid_content_type": "`Content-Type` is not `application/json`",
"malformed_body": "Request body is not valid JSON"
}
}
}
},
"examples": {
"invalid_content_type": {
"summary": "`Content-Type` is not `application/json`",
"value": {
"type": "https://docs.dinie.com/errors/invalid-request",
"title": "Invalid Request",
"status": 400,
"detail": "`Content-Type` is not `application/json`",
"code": "invalid_content_type"
}
},
"malformed_body": {
"summary": "Request body is not valid JSON",
"value": {
"type": "https://docs.dinie.com/errors/invalid-request",
"title": "Invalid Request",
"status": 400,
"detail": "Request body is not valid JSON",
"code": "malformed_body"
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/BearerTokenUnauthorized",
"description": "Authentication failed"
},
"404": {
"description": "Resource not found",
"content": {
"application/problem+json": {
"schema": {
"type": "object",
"required": [
"type",
"title",
"status",
"detail",
"code"
],
"properties": {
"type": {
"type": "string",
"const": "https://docs.dinie.com/errors/not-found"
},
"title": {
"type": "string",
"const": "Not Found"
},
"status": {
"type": "integer",
"const": 404
},
"detail": {
"type": "string"
},
"code": {
"type": "string",
"const": "webhook_endpoint_not_found",
"x-enumDescriptions": {
"webhook_endpoint_not_found": "Endpoint ID does not exist or does not belong to this partner"
}
}
}
},
"examples": {
"webhook_endpoint_not_found": {
"summary": "Endpoint ID does not exist or does not belong to this partner",
"value": {
"type": "https://docs.dinie.com/errors/not-found",
"title": "Not Found",
"status": 404,
"detail": "Endpoint ID does not exist or does not belong to this partner",
"code": "webhook_endpoint_not_found"
}
}
}
}
}
},
"422": {
"description": "Validation failed",
"content": {
"application/problem+json": {
"schema": {
"type": "object",
"required": [
"type",
"title",
"status",
"detail",
"code"
],
"properties": {
"type": {
"type": "string",
"const": "https://docs.dinie.com/errors/validation-failed"
},
"title": {
"type": "string",
"const": "Validation Failed"
},
"status": {
"type": "integer",
"const": 422
},
"detail": {
"type": "string"
},
"code": {
"type": "string",
"enum": [
"invalid_url",
"invalid_events",
"invalid_status"
],
"x-enumDescriptions": {
"invalid_url": "`url` is not a valid HTTPS URL",
"invalid_events": "`events` contains unrecognized event types",
"invalid_status": "`status` is not `active` or `disabled`"
}
}
}
},
"examples": {
"invalid_url": {
"summary": "`url` is not a valid HTTPS URL",
"value": {
"type": "https://docs.dinie.com/errors/validation-failed",
"title": "Validation Failed",
"status": 422,
"detail": "`url` is not a valid HTTPS URL",
"code": "invalid_url"
}
},
"invalid_events": {
"summary": "`events` contains unrecognized event types",
"value": {
"type": "https://docs.dinie.com/errors/validation-failed",
"title": "Validation Failed",
"status": 422,
"detail": "`events` contains unrecognized event types",
"code": "invalid_events"
}
},
"invalid_status": {
"summary": "`status` is not `active` or `disabled`",
"value": {
"type": "https://docs.dinie.com/errors/validation-failed",
"title": "Validation Failed",
"status": 422,
"detail": "`status` is not `active` or `disabled`",
"code": "invalid_status"
}
}
}
}
}
},
"429": {
"$ref": "#/components/responses/RateLimited",
"description": "Rate limit exceeded"
},
"500": {
"$ref": "#/components/responses/InternalError",
"description": "Internal server error"
}
},
"x-codeSamples": [
{
"lang": "curl",
"source": "curl -X PATCH https://api.dinie.com/api/v3/webhooks/endpoints/we_550e8400e29b41d4a716446655440000 \\\n -H \"Authorization: Bearer $DINIE_API_TOKEN\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"events\": [\"customer.*\", \"loan.*\"],\n \"status\": \"active\"\n }'\n"
},
{
"lang": "Python",
"source": "from dinie import Dinie\n\nclient = Dinie(\n client_id=\"dinie_ci_abc123\",\n client_secret=\"dinie_cs_live_xyz789\"\n)\n\n# Update webhook endpoint events and status\nendpoint = client.webhooks.update_endpoint(\n \"we_550e8400e29b41d4a716446655440000\",\n events=[\"customer.*\", \"loan.*\"],\n status=\"active\"\n)\n\nprint(endpoint.events) # [\"customer.*\", \"loan.*\"]\nprint(endpoint.status) # \"active\"\n"
},
{
"lang": "Node.js",
"source": "const { Dinie } = require(\"dinie\");\n\nconst client = new Dinie({\n clientId: \"dinie_ci_abc123\",\n clientSecret: \"dinie_cs_live_xyz789\",\n});\n\n// Update webhook endpoint events and status\nconst endpoint = await client.webhooks.updateEndpoint(\n \"we_550e8400e29b41d4a716446655440000\",\n {\n events: [\"customer.*\", \"loan.*\"],\n status: \"active\",\n }\n);\n\nconsole.log(endpoint.events); // [\"customer.*\", \"loan.*\"]\nconsole.log(endpoint.status); // \"active\"\n"
},
{
"lang": "Ruby",
"source": "require \"dinie\"\n\nclient = Dinie::Client.new(\n client_id: \"dinie_ci_abc123\",\n client_secret: \"dinie_cs_live_xyz789\"\n)\n\n# Update webhook endpoint events and status\nendpoint = client.webhooks.update_endpoint(\n \"we_550e8400e29b41d4a716446655440000\",\n events: [\"customer.*\", \"loan.*\"],\n status: \"active\"\n)\n\nputs endpoint.events # [\"customer.*\", \"loan.*\"]\nputs endpoint.status # \"active\"\n"
}
]
},
"delete": {
"operationId": "deleteWebhookEndpoint",
"summary": "Delete a webhook",
"description": "DELETE /webhooks/endpoints/{webhook_endpoint_id}
\n\nDelete a webhook endpoint",
"tags": [
"Webhooks"
],
"parameters": [
{
"$ref": "#/components/parameters/WebhookEndpointId"
}
],
"responses": {
"204": {
"description": "Webhook endpoint deleted (empty body)"
},
"401": {
"$ref": "#/components/responses/BearerTokenUnauthorized",
"description": "Authentication failed"
},
"404": {
"description": "Resource not found",
"content": {
"application/problem+json": {
"schema": {
"type": "object",
"required": [
"type",
"title",
"status",
"detail",
"code"
],
"properties": {
"type": {
"type": "string",
"const": "https://docs.dinie.com/errors/not-found"
},
"title": {
"type": "string",
"const": "Not Found"
},
"status": {
"type": "integer",
"const": 404
},
"detail": {
"type": "string"
},
"code": {
"type": "string",
"const": "webhook_endpoint_not_found",
"x-enumDescriptions": {
"webhook_endpoint_not_found": "Endpoint ID does not exist or does not belong to this partner"
}
}
}
},
"examples": {
"webhook_endpoint_not_found": {
"summary": "Endpoint ID does not exist or does not belong to this partner",
"value": {
"type": "https://docs.dinie.com/errors/not-found",
"title": "Not Found",
"status": 404,
"detail": "Endpoint ID does not exist or does not belong to this partner",
"code": "webhook_endpoint_not_found"
}
}
}
}
}
},
"429": {
"$ref": "#/components/responses/RateLimited",
"description": "Rate limit exceeded"
},
"500": {
"$ref": "#/components/responses/InternalError",
"description": "Internal server error"
}
},
"x-codeSamples": [
{
"lang": "curl",
"source": "curl -X DELETE https://api.dinie.com/api/v3/webhooks/endpoints/we_550e8400e29b41d4a716446655440000 \\\n -H \"Authorization: Bearer $DINIE_API_TOKEN\"\n"
},
{
"lang": "Python",
"source": "from dinie import Dinie\n\nclient = Dinie(\n client_id=\"dinie_ci_abc123\",\n client_secret=\"dinie_cs_live_xyz789\"\n)\n\n# Delete a webhook endpoint\nclient.webhooks.delete_endpoint(\"we_550e8400e29b41d4a716446655440000\")\n# 204 No Content -- endpoint deleted, deliveries stopped\n"
},
{
"lang": "Node.js",
"source": "const { Dinie } = require(\"dinie\");\n\nconst client = new Dinie({\n clientId: \"dinie_ci_abc123\",\n clientSecret: \"dinie_cs_live_xyz789\",\n});\n\n// Delete a webhook endpoint\nawait client.webhooks.deleteEndpoint(\n \"we_550e8400e29b41d4a716446655440000\"\n);\n// 204 No Content -- endpoint deleted, deliveries stopped\n"
},
{
"lang": "Ruby",
"source": "require \"dinie\"\n\nclient = Dinie::Client.new(\n client_id: \"dinie_ci_abc123\",\n client_secret: \"dinie_cs_live_xyz789\"\n)\n\n# Delete a webhook endpoint\nclient.webhooks.delete_endpoint(\"we_550e8400e29b41d4a716446655440000\")\n# 204 No Content -- endpoint deleted, deliveries stopped\n"
}
]
}
},
"/webhooks/endpoints/{webhook_endpoint_id}/rotate-secret": {
"post": {
"operationId": "rotateWebhookSecret",
"summary": "Rotate the secret",
"description": "POST /webhooks/endpoints/{webhook_endpoint_id}/rotate-secret
\n\nRotate a webhook's signing secret",
"tags": [
"Webhooks"
],
"parameters": [
{
"$ref": "#/components/parameters/WebhookEndpointId"
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"expire_current_in": {
"type": "integer",
"description": "Seconds until the current secret expires. Default 3600. Max 86400",
"default": 3600,
"minimum": 0,
"maximum": 86400
}
}
},
"example": {
"expire_current_in": 3600
}
}
}
},
"responses": {
"200": {
"description": "Secret rotated",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/WebhookSecretRotation"
},
"example": {
"id": "we_550e8400e29b41d4a716446655440000",
"secret": "whsec_novo1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8",
"previous_secret_expires_at": 1709550000
}
}
}
},
"400": {
"description": "Bad request",
"content": {
"application/problem+json": {
"schema": {
"type": "object",
"required": [
"type",
"title",
"status",
"detail",
"code"
],
"properties": {
"type": {
"type": "string",
"const": "https://docs.dinie.com/errors/invalid-request"
},
"title": {
"type": "string",
"const": "Invalid Request"
},
"status": {
"type": "integer",
"const": 400
},
"detail": {
"type": "string"
},
"code": {
"type": "string",
"const": "invalid_content_type",
"x-enumDescriptions": {
"invalid_content_type": "`Content-Type` is not `application/json`"
}
}
}
},
"examples": {
"invalid_content_type": {
"summary": "`Content-Type` is not `application/json`",
"value": {
"type": "https://docs.dinie.com/errors/invalid-request",
"title": "Invalid Request",
"status": 400,
"detail": "`Content-Type` is not `application/json`",
"code": "invalid_content_type"
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/BearerTokenUnauthorized",
"description": "Authentication failed"
},
"404": {
"description": "Resource not found",
"content": {
"application/problem+json": {
"schema": {
"type": "object",
"required": [
"type",
"title",
"status",
"detail",
"code"
],
"properties": {
"type": {
"type": "string",
"const": "https://docs.dinie.com/errors/not-found"
},
"title": {
"type": "string",
"const": "Not Found"
},
"status": {
"type": "integer",
"const": 404
},
"detail": {
"type": "string"
},
"code": {
"type": "string",
"const": "webhook_endpoint_not_found",
"x-enumDescriptions": {
"webhook_endpoint_not_found": "Endpoint ID does not exist or does not belong to this partner"
}
}
}
},
"examples": {
"webhook_endpoint_not_found": {
"summary": "Endpoint ID does not exist or does not belong to this partner",
"value": {
"type": "https://docs.dinie.com/errors/not-found",
"title": "Not Found",
"status": 404,
"detail": "Endpoint ID does not exist or does not belong to this partner",
"code": "webhook_endpoint_not_found"
}
}
}
}
}
},
"422": {
"description": "Validation failed",
"content": {
"application/problem+json": {
"schema": {
"type": "object",
"required": [
"type",
"title",
"status",
"detail",
"code"
],
"properties": {
"type": {
"type": "string",
"const": "https://docs.dinie.com/errors/validation-failed"
},
"title": {
"type": "string",
"const": "Validation Failed"
},
"status": {
"type": "integer",
"const": 422
},
"detail": {
"type": "string"
},
"code": {
"type": "string",
"const": "invalid_expire_current_in",
"x-enumDescriptions": {
"invalid_expire_current_in": "`expire_current_in` is outside the 0–86400 range"
}
}
}
},
"examples": {
"invalid_expire_current_in": {
"summary": "`expire_current_in` is outside the 0–86400 range",
"value": {
"type": "https://docs.dinie.com/errors/validation-failed",
"title": "Validation Failed",
"status": 422,
"detail": "`expire_current_in` is outside the 0–86400 range",
"code": "invalid_expire_current_in"
}
}
}
}
}
},
"429": {
"$ref": "#/components/responses/RateLimited",
"description": "Rate limit exceeded"
},
"500": {
"$ref": "#/components/responses/InternalError",
"description": "Internal server error"
}
},
"x-codeSamples": [
{
"lang": "curl",
"source": "curl -X POST https://api.dinie.com/api/v3/webhooks/endpoints/we_550e8400e29b41d4a716446655440000/rotate-secret \\\n -H \"Authorization: Bearer $DINIE_API_TOKEN\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"expire_current_in\": 3600}'\n"
},
{
"lang": "Python",
"source": "from dinie import Dinie\n\nclient = Dinie(\n client_id=\"dinie_ci_abc123\",\n client_secret=\"dinie_cs_live_xyz789\"\n)\n\n# Rotate the webhook signing secret\nrotation = client.webhooks.rotate_secret(\n \"we_550e8400e29b41d4a716446655440000\",\n expire_current_in=3600 # previous secret valid for 1 more hour\n)\n\nprint(rotation.secret) # \"whsec_novo1b2c3...\"\nprint(rotation.previous_secret_expires_at) # 1709550000\n"
},
{
"lang": "Node.js",
"source": "const { Dinie } = require(\"dinie\");\n\nconst client = new Dinie({\n clientId: \"dinie_ci_abc123\",\n clientSecret: \"dinie_cs_live_xyz789\",\n});\n\n// Rotate the webhook signing secret\nconst rotation = await client.webhooks.rotateSecret(\n \"we_550e8400e29b41d4a716446655440000\",\n { expireCurrentIn: 3600 } // previous secret valid for 1 more hour\n);\n\nconsole.log(rotation.secret); // \"whsec_novo1b2c3...\"\nconsole.log(rotation.previousSecretExpiresAt); // 1709550000\n"
},
{
"lang": "Ruby",
"source": "require \"dinie\"\n\nclient = Dinie::Client.new(\n client_id: \"dinie_ci_abc123\",\n client_secret: \"dinie_cs_live_xyz789\"\n)\n\n# Rotate the webhook signing secret\nrotation = client.webhooks.rotate_secret(\n \"we_550e8400e29b41d4a716446655440000\",\n expire_current_in: 3600 # previous secret valid for 1 more hour\n)\n\nputs rotation.secret # \"whsec_novo1b2c3...\"\nputs rotation.previous_secret_expires_at # 1709550000\n"
}
]
}
},
"/webhooks/endpoints/{endpoint_id}/deliveries": {
"get": {
"operationId": "listWebhookDeliveries",
"summary": "List webhook deliveries",
"description": "GET /webhooks/endpoints/{endpoint_id}/deliveries
\n\nPaginated delivery history for a webhook endpoint, newest first",
"tags": [
"Webhooks"
],
"parameters": [
{
"name": "endpoint_id",
"in": "path",
"required": true,
"schema": {
"$ref": "#/components/schemas/WebhookEndpointId"
}
},
{
"name": "limit",
"in": "query",
"required": false,
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 100,
"default": 25
}
},
{
"name": "starting_after",
"in": "query",
"required": false,
"schema": {
"$ref": "#/components/schemas/WebhookDeliveryId"
}
}
],
"responses": {
"200": {
"description": "Delivery history",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"data",
"has_more"
],
"properties": {
"data": {
"type": "array",
"items": {
"$ref": "#/components/schemas/WebhookDelivery"
}
},
"has_more": {
"type": "boolean"
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/BearerTokenUnauthorized"
},
"404": {
"$ref": "#/components/responses/WebhookEndpointNotFound"
},
"429": {
"$ref": "#/components/responses/RateLimited"
},
"500": {
"$ref": "#/components/responses/InternalError"
}
}
}
},
"/webhooks/endpoints/{endpoint_id}/deliveries/{id}/retry": {
"post": {
"operationId": "retryWebhookDelivery",
"summary": "Retry a webhook delivery",
"description": "POST /webhooks/endpoints/{endpoint_id}/deliveries/{id}/retry
\n\nReset a failed delivery and re-enqueue it. Only deliveries in `failed` status can be retried",
"tags": [
"Webhooks"
],
"parameters": [
{
"name": "endpoint_id",
"in": "path",
"required": true,
"schema": {
"$ref": "#/components/schemas/WebhookEndpointId"
}
},
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"$ref": "#/components/schemas/WebhookDeliveryId"
}
}
],
"responses": {
"200": {
"description": "Delivery reset and re-enqueued",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/WebhookDelivery"
}
}
}
},
"401": {
"$ref": "#/components/responses/BearerTokenUnauthorized"
},
"404": {
"$ref": "#/components/responses/WebhookEndpointNotFound"
},
"409": {
"description": "Delivery not retryable",
"content": {
"application/problem+json": {
"schema": {
"type": "object",
"required": [
"type",
"title",
"status",
"detail",
"code"
],
"properties": {
"type": {
"type": "string",
"const": "https://docs.dinie.com/errors/conflict"
},
"title": {
"type": "string",
"const": "Conflict"
},
"status": {
"type": "integer",
"const": 409
},
"detail": {
"type": "string"
},
"code": {
"type": "string",
"const": "delivery_not_retryable"
}
}
},
"example": {
"type": "https://docs.dinie.com/errors/conflict",
"title": "Conflict",
"status": 409,
"detail": "Only failed deliveries can be retried",
"code": "delivery_not_retryable"
}
}
}
},
"429": {
"$ref": "#/components/responses/RateLimited"
},
"500": {
"$ref": "#/components/responses/InternalError"
}
}
}
}
},
"x-webhook-defaults": {
"security": [
{
"webhookSignature": []
}
],
"parameters": [
{
"$ref": "#/components/parameters/WebhookId"
},
{
"$ref": "#/components/parameters/WebhookTimestamp"
},
{
"$ref": "#/components/parameters/WebhookSignatureHeader"
}
],
"responses": {
"200": {
"description": "Delivery confirmed; any 2xx (200-299) is accepted"
},
"410": {
"description": "Endpoint permanently disabled, Dinie stops sending events"
},
"429": {
"description": "Rate-limiting, Dinie reduces send rate and reschedules with backoff"
},
"502": {
"description": "Server overload, Dinie reduces send rate before retrying"
},
"504": {
"description": "Gateway timeout, Dinie reduces send rate before retrying"
},
"4XX": {
"description": "Client error (except 410, 429), failure triggers retry"
},
"5XX": {
"description": "Server error (except 502, 504), failure triggers retry"
}
}
},
"webhooks": {
"customer.created": {
"post": {
"operationId": "onCustomerCreated",
"summary": "Customer created",
"description": "Fires when the customer reaches `pending_kyc` status after async enrichment completes.\nIncludes the full enriched data (`trading_name`, KYC requirements).\nThis is the moment to start collecting KYC documents from the customer.\n",
"tags": [
"Customers"
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/WebhookEvent_CustomerCreated"
},
"example": {
"type": "customer.created",
"id": "evt_550e8400e29b41d4a716446655440000",
"api_version": "2026-03-01",
"created_at": 1772791260,
"delivery_id": "dlv_550e8400e29b41d4a716446655440000",
"timestamp": 1772791260,
"data": {
"id": "cust_550e8400e29b41d4a716446655440000",
"status": "pending_kyc",
"cpf": "123.456.789-00",
"cnpj": "12.345.678/0001-90",
"name": "João Silva",
"email": "joao@example.com",
"phone": "+5511999999999",
"trading_name": "Loja do João",
"external_id": "partner-ref-123",
"kyc": [
{
"requirement_id": "identity_003XXXXXXXXXXXXXXX",
"requirement_type": "identity",
"label": "Documento de identidade",
"mandatory": true,
"subject": {
"id": "003XXXXXXXXXXXXXXX",
"name": "Joao Silva",
"subject_type": "applicant"
}
}
]
}
}
}
}
},
"security": [
{
"webhookSignature": []
}
],
"parameters": [
{
"$ref": "#/components/parameters/WebhookId"
},
{
"$ref": "#/components/parameters/WebhookTimestamp"
},
{
"$ref": "#/components/parameters/WebhookSignatureHeader"
}
],
"responses": {
"200": {
"description": "Delivery confirmed"
},
"410": {
"description": "Endpoint permanently disabled"
},
"429": {
"description": "Rate-limiting, send rate reduced"
},
"502": {
"description": "Server overload, rate reduced before retrying"
},
"504": {
"description": "Gateway timeout, rate reduced before retrying"
},
"4XX": {
"description": "Client error, failure triggers retry"
},
"5XX": {
"description": "Server error, failure triggers retry"
}
}
}
},
"customer.under_review": {
"post": {
"operationId": "onCustomerUnderReview",
"summary": "Customer under review",
"description": "Fires when all required KYC documents have been submitted and the credit review\nis started by Dinie. Includes the customer ID and `under_review` status.\nUse it to update the status in your system and inform the customer that the review is in progress.\n",
"tags": [
"Customers"
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/WebhookEvent_CustomerStatus"
},
"example": {
"type": "customer.under_review",
"id": "evt_550e8400e29b41d4a716446655440001",
"api_version": "2026-03-01",
"created_at": 1772798400,
"delivery_id": "dlv_550e8400e29b41d4a716446655440001",
"timestamp": 1772798400,
"data": {
"id": "cust_550e8400e29b41d4a716446655440000",
"status": "under_review",
"external_id": "partner-ref-123"
}
}
}
}
},
"security": [
{
"webhookSignature": []
}
],
"parameters": [
{
"$ref": "#/components/parameters/WebhookId"
},
{
"$ref": "#/components/parameters/WebhookTimestamp"
},
{
"$ref": "#/components/parameters/WebhookSignatureHeader"
}
],
"responses": {
"200": {
"description": "Delivery confirmed"
},
"410": {
"description": "Endpoint permanently disabled"
},
"429": {
"description": "Rate-limiting, send rate reduced"
},
"502": {
"description": "Server overload, rate reduced before retrying"
},
"504": {
"description": "Gateway timeout, rate reduced before retrying"
},
"4XX": {
"description": "Client error, failure triggers retry"
},
"5XX": {
"description": "Server error, failure triggers retry"
}
}
}
},
"customer.kyc_updated": {
"post": {
"operationId": "onCustomerKycUpdated",
"summary": "Customer KYC updated",
"description": "Fires when any KYC requirement changes status (approved, rejected, or\npending correction). Includes the full `kyc` array with the updated status of\neach item. Use it to identify rejected documents and request resubmission from the customer\nvia `PATCH /customers/{id}` or `POST /customers/{id}/kyc-attachments`.\n",
"tags": [
"Customers"
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/WebhookEvent_CustomerKycUpdated"
},
"example": {
"type": "customer.kyc_updated",
"id": "evt_550e8400e29b41d4a716446655440002",
"api_version": "2026-03-01",
"created_at": 1772800200,
"delivery_id": "dlv_550e8400e29b41d4a716446655440002",
"timestamp": 1772800200,
"data": {
"id": "cust_550e8400e29b41d4a716446655440000",
"status": "pending_kyc",
"external_id": "partner-ref-123",
"kyc": [
{
"requirement_id": "company_document_001XXXXXXXXXXXXXXX",
"requirement_type": "company_document",
"label": "Documento da empresa",
"mandatory": true,
"submitted": {
"evidence_type": "ccmei",
"attachments": [
{
"attachment_type": "file",
"submitted": true
}
],
"review_status": "accepted",
"review_reason": null
}
},
{
"requirement_id": "identity_003XXXXXXXXXXXXXXX",
"requirement_type": "identity",
"label": "Documento de identidade",
"mandatory": true,
"subject": {
"id": "003XXXXXXXXXXXXXXX",
"name": "Joao Silva",
"subject_type": "applicant"
}
}
]
}
}
}
}
},
"security": [
{
"webhookSignature": []
}
],
"parameters": [
{
"$ref": "#/components/parameters/WebhookId"
},
{
"$ref": "#/components/parameters/WebhookTimestamp"
},
{
"$ref": "#/components/parameters/WebhookSignatureHeader"
}
],
"responses": {
"200": {
"description": "Delivery confirmed"
},
"410": {
"description": "Endpoint permanently disabled"
},
"429": {
"description": "Rate-limiting, send rate reduced"
},
"502": {
"description": "Server overload, rate reduced before retrying"
},
"504": {
"description": "Gateway timeout, rate reduced before retrying"
},
"4XX": {
"description": "Client error, failure triggers retry"
},
"5XX": {
"description": "Server error, failure triggers retry"
}
}
}
},
"customer.active": {
"post": {
"operationId": "onCustomerActive",
"summary": "Customer active",
"description": "Fires when the customer is fully verified (KYC approved) — registration is complete.\nNote: `active` means KYC complete, NOT credit eligible. Eligibility is determined\nby CreditOffer availability. Includes the customer ID and `active` status. Query\n`GET /customers/{id}/credit-offers` to check for available pre-approved offers.\n",
"tags": [
"Customers"
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/WebhookEvent_CustomerStatus"
},
"example": {
"type": "customer.active",
"id": "evt_550e8400e29b41d4a716446655440003",
"api_version": "2026-03-01",
"created_at": 1772805600,
"delivery_id": "dlv_550e8400e29b41d4a716446655440003",
"timestamp": 1772805600,
"data": {
"id": "cust_550e8400e29b41d4a716446655440000",
"status": "active",
"external_id": "partner-ref-123"
}
}
}
}
},
"security": [
{
"webhookSignature": []
}
],
"parameters": [
{
"$ref": "#/components/parameters/WebhookId"
},
{
"$ref": "#/components/parameters/WebhookTimestamp"
},
{
"$ref": "#/components/parameters/WebhookSignatureHeader"
}
],
"responses": {
"200": {
"description": "Delivery confirmed"
},
"410": {
"description": "Endpoint permanently disabled"
},
"429": {
"description": "Rate-limiting, send rate reduced"
},
"502": {
"description": "Server overload, rate reduced before retrying"
},
"504": {
"description": "Gateway timeout, rate reduced before retrying"
},
"4XX": {
"description": "Client error, failure triggers retry"
},
"5XX": {
"description": "Server error, failure triggers retry"
}
}
}
},
"credit_offer.available": {
"post": {
"operationId": "onCreditOfferAvailable",
"summary": "Credit offer available",
"description": "Fires when Dinie generates a new pre-approved credit offer for the customer.\nIncludes approved amount, interest rate, installments, and offer expiration date.\nUse it to notify the customer about credit availability and start the simulation flow\nvia `POST /credit-offers/{id}/simulations`.\n",
"tags": [
"Credit Offers"
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/WebhookEvent_CreditOffer"
},
"example": {
"type": "credit_offer.available",
"id": "evt_550e8400e29b41d4a716446655440004",
"api_version": "2026-03-01",
"created_at": 1772809200,
"delivery_id": "dlv_550e8400e29b41d4a716446655440004",
"timestamp": 1772809200,
"data": {
"id": "co_550e8400e29b41d4a716446655440000",
"customer_id": "cust_550e8400e29b41d4a716446655440000",
"external_id": "partner-ref-123",
"status": "available",
"approved_amount": 50000,
"min_amount": 200,
"monthly_interest_rate": 3.5,
"installments": 12,
"due_date_rule": null,
"valid_until": 1775253599
}
}
}
}
},
"security": [
{
"webhookSignature": []
}
],
"parameters": [
{
"$ref": "#/components/parameters/WebhookId"
},
{
"$ref": "#/components/parameters/WebhookTimestamp"
},
{
"$ref": "#/components/parameters/WebhookSignatureHeader"
}
],
"responses": {
"200": {
"description": "Delivery confirmed"
},
"410": {
"description": "Endpoint permanently disabled"
},
"429": {
"description": "Rate-limiting, send rate reduced"
},
"502": {
"description": "Server overload, rate reduced before retrying"
},
"504": {
"description": "Gateway timeout, rate reduced before retrying"
},
"4XX": {
"description": "Client error, failure triggers retry"
},
"5XX": {
"description": "Server error, failure triggers retry"
}
}
}
},
"credit_offer.expired": {
"post": {
"operationId": "onCreditOfferExpired",
"summary": "Credit offer expired",
"description": "Fires when a credit offer expires after exceeding its expiration date\n(`valid_until`). Includes the full offer data with `expired` status.\nUse it to remove the offer from the customer interface. New offers may be generated\nin the future via `credit_offer.available`.\n",
"tags": [
"Credit Offers"
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/WebhookEvent_CreditOffer"
},
"example": {
"type": "credit_offer.expired",
"id": "evt_550e8400e29b41d4a716446655440005",
"api_version": "2026-03-01",
"created_at": 1775253600,
"delivery_id": "dlv_550e8400e29b41d4a716446655440005",
"timestamp": 1775253600,
"data": {
"id": "co_660e8400e29b41d4a716446655440001",
"customer_id": "cust_550e8400e29b41d4a716446655440000",
"external_id": "partner-ref-123",
"status": "expired",
"approved_amount": 30000,
"min_amount": 200,
"monthly_interest_rate": 3.5,
"installments": 12,
"due_date_rule": null,
"valid_until": 1775253599
}
}
}
}
},
"security": [
{
"webhookSignature": []
}
],
"parameters": [
{
"$ref": "#/components/parameters/WebhookId"
},
{
"$ref": "#/components/parameters/WebhookTimestamp"
},
{
"$ref": "#/components/parameters/WebhookSignatureHeader"
}
],
"responses": {
"200": {
"description": "Delivery confirmed"
},
"410": {
"description": "Endpoint permanently disabled"
},
"429": {
"description": "Rate-limiting, send rate reduced"
},
"502": {
"description": "Server overload, rate reduced before retrying"
},
"504": {
"description": "Gateway timeout, rate reduced before retrying"
},
"4XX": {
"description": "Client error, failure triggers retry"
},
"5XX": {
"description": "Server error, failure triggers retry"
}
}
}
},
"loan.created": {
"post": {
"operationId": "onLoanCreated",
"summary": "Loan created",
"description": "Fires when the loan is created via `POST /loans` from an accepted offer.\nCCB contract is generated synchronously. Includes the loan, offer, and customer IDs,\nrequested amount, number of installments, and `signing_url` for contract signing.\nThe loan starts with `awaiting_signatures` status. Present the signing link to the customer.\n",
"tags": [
"Loans"
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/WebhookEvent_LoanCreated"
},
"example": {
"type": "loan.created",
"id": "evt_550e8400e29b41d4a716446655440006",
"api_version": "2026-03-01",
"created_at": 1772812800,
"delivery_id": "dlv_550e8400e29b41d4a716446655440006",
"timestamp": 1772812800,
"data": {
"id": "ln_550e8400e29b41d4a716446655440001",
"credit_offer_id": "co_550e8400e29b41d4a716446655440000",
"customer_id": "cust_550e8400e29b41d4a716446655440000",
"status": "awaiting_signatures",
"requested_amount": 25000,
"installment_count": 12,
"signing_url": "https://clicksign.com/sign/abc123"
}
}
}
}
},
"security": [
{
"webhookSignature": []
}
],
"parameters": [
{
"$ref": "#/components/parameters/WebhookId"
},
{
"$ref": "#/components/parameters/WebhookTimestamp"
},
{
"$ref": "#/components/parameters/WebhookSignatureHeader"
}
],
"responses": {
"200": {
"description": "Delivery confirmed"
},
"410": {
"description": "Endpoint permanently disabled"
},
"429": {
"description": "Rate-limiting, send rate reduced"
},
"502": {
"description": "Server overload, rate reduced before retrying"
},
"504": {
"description": "Gateway timeout, rate reduced before retrying"
},
"4XX": {
"description": "Client error, failure triggers retry"
},
"5XX": {
"description": "Server error, failure triggers retry"
}
}
}
},
"customer.denied": {
"post": {
"operationId": "onCustomerDenied",
"summary": "Customer denied",
"description": "Fires when the customer is permanently blocked (fraud, closed company at\nReceita Federal, or other terminal condition). This is a terminal state —\nthe customer cannot proceed. Includes the customer ID and `denied` status.\n",
"tags": [
"Customers"
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/WebhookEvent_CustomerDenied"
},
"example": {
"type": "customer.denied",
"id": "evt_550e8400e29b41d4a716446655440007",
"api_version": "2026-03-01",
"created_at": 1772807400,
"delivery_id": "dlv_550e8400e29b41d4a716446655440007",
"timestamp": 1772807400,
"data": {
"id": "cust_550e8400e29b41d4a716446655440000",
"status": "denied",
"cpf": "123.456.789-00",
"cnpj": "12.345.678/0001-90",
"name": "Joao Silva",
"email": "joao@example.com",
"phone": "+5511999999999",
"external_id": "partner-ref-123"
}
}
}
}
},
"security": [
{
"webhookSignature": []
}
],
"parameters": [
{
"$ref": "#/components/parameters/WebhookId"
},
{
"$ref": "#/components/parameters/WebhookTimestamp"
},
{
"$ref": "#/components/parameters/WebhookSignatureHeader"
}
],
"responses": {
"200": {
"description": "Delivery confirmed"
},
"410": {
"description": "Endpoint permanently disabled"
},
"429": {
"description": "Rate-limiting, send rate reduced"
},
"502": {
"description": "Server overload, rate reduced before retrying"
},
"504": {
"description": "Gateway timeout, rate reduced before retrying"
},
"4XX": {
"description": "Client error, failure triggers retry"
},
"5XX": {
"description": "Server error, failure triggers retry"
}
}
}
},
"loan.signature_received": {
"post": {
"operationId": "onLoanSignatureReceived",
"summary": "Signature received",
"description": "Fires each time an individual signer completes their signature on the CCB contract.\nIncludes signer identity (name, CPF), signature timestamp, and progress count\n(`signatures_received` / `signatures_required`). Use it to track signing progress\nand notify the customer about remaining signatures.\n",
"tags": [
"Loans"
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/WebhookEvent_LoanSignatureReceived"
},
"example": {
"type": "loan.signature_received",
"id": "evt_550e8400e29b41d4a716446655440008",
"api_version": "2026-03-01",
"created_at": 1772877600,
"delivery_id": "dlv_550e8400e29b41d4a716446655440008",
"timestamp": 1772877600,
"data": {
"id": "ln_550e8400e29b41d4a716446655440001",
"status": "awaiting_signatures",
"signer": {
"name": "Joao Silva",
"cpf": "123.456.789-00",
"signed_at": 1772877600
},
"signatures_received": 1,
"signatures_required": 2
}
}
}
}
},
"security": [
{
"webhookSignature": []
}
],
"parameters": [
{
"$ref": "#/components/parameters/WebhookId"
},
{
"$ref": "#/components/parameters/WebhookTimestamp"
},
{
"$ref": "#/components/parameters/WebhookSignatureHeader"
}
],
"responses": {
"200": {
"description": "Delivery confirmed"
},
"410": {
"description": "Endpoint permanently disabled"
},
"429": {
"description": "Rate-limiting, send rate reduced"
},
"502": {
"description": "Server overload, rate reduced before retrying"
},
"504": {
"description": "Gateway timeout, rate reduced before retrying"
},
"4XX": {
"description": "Client error, failure triggers retry"
},
"5XX": {
"description": "Server error, failure triggers retry"
}
}
}
},
"loan.processing": {
"post": {
"operationId": "onLoanProcessing",
"summary": "Loan processing",
"description": "Fires when all required signatures are collected and disbursement is in progress.\nThe loan transitions to `processing` status. Use it to inform the customer that\nthe funds are being transferred.\n",
"tags": [
"Loans"
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/WebhookEvent_LoanProcessing"
},
"example": {
"type": "loan.processing",
"id": "evt_550e8400e29b41d4a716446655440009",
"api_version": "2026-03-01",
"created_at": 1772881200,
"delivery_id": "dlv_550e8400e29b41d4a716446655440009",
"timestamp": 1772881200,
"data": {
"id": "ln_550e8400e29b41d4a716446655440001",
"credit_offer_id": "co_550e8400e29b41d4a716446655440000",
"customer_id": "cust_550e8400e29b41d4a716446655440000",
"status": "processing",
"ccb_number": "CCB-2026-001234",
"disbursement_method": "pix"
}
}
}
}
},
"security": [
{
"webhookSignature": []
}
],
"parameters": [
{
"$ref": "#/components/parameters/WebhookId"
},
{
"$ref": "#/components/parameters/WebhookTimestamp"
},
{
"$ref": "#/components/parameters/WebhookSignatureHeader"
}
],
"responses": {
"200": {
"description": "Delivery confirmed"
},
"410": {
"description": "Endpoint permanently disabled"
},
"429": {
"description": "Rate-limiting, send rate reduced"
},
"502": {
"description": "Server overload, rate reduced before retrying"
},
"504": {
"description": "Gateway timeout, rate reduced before retrying"
},
"4XX": {
"description": "Client error, failure triggers retry"
},
"5XX": {
"description": "Server error, failure triggers retry"
}
}
}
},
"loan.active": {
"post": {
"operationId": "onLoanActive",
"summary": "Loan active",
"description": "Fires when the disbursement is confirmed and the loan enters the repayment phase.\nIncludes the requested amount (`requested_amount`) and the principal amount received (`principal_amount`).\nUse it to confirm to the customer that the funds have been credited and present the installment schedule.\n",
"tags": [
"Loans"
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/WebhookEvent_LoanActive"
},
"example": {
"type": "loan.active",
"id": "evt_550e8400e29b41d4a71644665544000a",
"api_version": "2026-03-01",
"created_at": 1772884800,
"delivery_id": "dlv_550e8400e29b41d4a71644665544000a",
"timestamp": 1772884800,
"data": {
"id": "ln_550e8400e29b41d4a716446655440001",
"status": "active",
"requested_amount": 25000,
"principal_amount": 29375
}
}
}
}
},
"security": [
{
"webhookSignature": []
}
],
"parameters": [
{
"$ref": "#/components/parameters/WebhookId"
},
{
"$ref": "#/components/parameters/WebhookTimestamp"
},
{
"$ref": "#/components/parameters/WebhookSignatureHeader"
}
],
"responses": {
"200": {
"description": "Delivery confirmed"
},
"410": {
"description": "Endpoint permanently disabled"
},
"429": {
"description": "Rate-limiting, send rate reduced"
},
"502": {
"description": "Server overload, rate reduced before retrying"
},
"504": {
"description": "Gateway timeout, rate reduced before retrying"
},
"4XX": {
"description": "Client error, failure triggers retry"
},
"5XX": {
"description": "Server error, failure triggers retry"
}
}
}
},
"loan.payment_received": {
"post": {
"operationId": "onLoanPaymentReceived",
"summary": "Loan payment received",
"description": "Fires when an installment payment is recorded for the loan. Includes the amount\npaid, payment date, and corresponding installment number. Use it to update the\noutstanding balance in your system and notify the customer about the payment confirmation.\n",
"tags": [
"Loans"
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/WebhookEvent_LoanPaymentReceived"
},
"example": {
"type": "loan.payment_received",
"id": "evt_550e8400e29b41d4a71644665544000b",
"api_version": "2026-03-01",
"created_at": 1775383200,
"delivery_id": "dlv_550e8400e29b41d4a71644665544000b",
"timestamp": 1775383200,
"data": {
"id": "ln_550e8400e29b41d4a716446655440001",
"status": "active",
"payment": {
"amount": 2289.42,
"paid_at": 1775383200,
"installment_number": 1
}
}
}
}
}
},
"security": [
{
"webhookSignature": []
}
],
"parameters": [
{
"$ref": "#/components/parameters/WebhookId"
},
{
"$ref": "#/components/parameters/WebhookTimestamp"
},
{
"$ref": "#/components/parameters/WebhookSignatureHeader"
}
],
"responses": {
"200": {
"description": "Delivery confirmed"
},
"410": {
"description": "Endpoint permanently disabled"
},
"429": {
"description": "Rate-limiting, send rate reduced"
},
"502": {
"description": "Server overload, rate reduced before retrying"
},
"504": {
"description": "Gateway timeout, rate reduced before retrying"
},
"4XX": {
"description": "Client error, failure triggers retry"
},
"5XX": {
"description": "Server error, failure triggers retry"
}
}
}
},
"loan.finished": {
"post": {
"operationId": "onLoanFinished",
"summary": "Loan finished",
"description": "Fires when all loan installments are paid off and the contract is closed.\nIncludes the loan ID and `finished` status. Use it to mark the loan as\ncompleted in your system and check if new credit offers are available.\n",
"tags": [
"Loans"
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/WebhookEvent_LoanStatus"
},
"example": {
"type": "loan.finished",
"id": "evt_550e8400e29b41d4a71644665544000c",
"api_version": "2026-03-01",
"created_at": 1792177200,
"delivery_id": "dlv_550e8400e29b41d4a71644665544000c",
"timestamp": 1792177200,
"data": {
"id": "ln_550e8400e29b41d4a716446655440001",
"status": "finished"
}
}
}
}
},
"security": [
{
"webhookSignature": []
}
],
"parameters": [
{
"$ref": "#/components/parameters/WebhookId"
},
{
"$ref": "#/components/parameters/WebhookTimestamp"
},
{
"$ref": "#/components/parameters/WebhookSignatureHeader"
}
],
"responses": {
"200": {
"description": "Delivery confirmed"
},
"410": {
"description": "Endpoint permanently disabled"
},
"429": {
"description": "Rate-limiting, send rate reduced"
},
"502": {
"description": "Server overload, rate reduced before retrying"
},
"504": {
"description": "Gateway timeout, rate reduced before retrying"
},
"4XX": {
"description": "Client error, failure triggers retry"
},
"5XX": {
"description": "Server error, failure triggers retry"
}
}
}
},
"loan.cancelled": {
"post": {
"operationId": "onLoanCancelled",
"summary": "Loan cancelled",
"description": "Fires when the loan is cancelled before disbursement is completed. Includes the loan ID\nand `cancelled` status. Use it to update the status in your system and\ninform the customer. The original credit offer may still be available for a new request.\n",
"tags": [
"Loans"
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/WebhookEvent_LoanStatus"
},
"example": {
"type": "loan.cancelled",
"id": "evt_550e8400e29b41d4a71644665544000d",
"api_version": "2026-03-01",
"created_at": 1775295000,
"delivery_id": "dlv_550e8400e29b41d4a71644665544000d",
"timestamp": 1775295000,
"data": {
"id": "ln_550e8400e29b41d4a716446655440001",
"status": "cancelled"
}
}
}
}
},
"security": [
{
"webhookSignature": []
}
],
"parameters": [
{
"$ref": "#/components/parameters/WebhookId"
},
{
"$ref": "#/components/parameters/WebhookTimestamp"
},
{
"$ref": "#/components/parameters/WebhookSignatureHeader"
}
],
"responses": {
"200": {
"description": "Delivery confirmed"
},
"410": {
"description": "Endpoint permanently disabled"
},
"429": {
"description": "Rate-limiting, send rate reduced"
},
"502": {
"description": "Server overload, rate reduced before retrying"
},
"504": {
"description": "Gateway timeout, rate reduced before retrying"
},
"4XX": {
"description": "Client error, failure triggers retry"
},
"5XX": {
"description": "Server error, failure triggers retry"
}
}
}
},
"loan.error": {
"post": {
"operationId": "onLoanError",
"summary": "Loan error",
"description": "Fires when an unrecoverable error occurs in the loan, such as a disbursement failure\nor contract generation error. Includes the error code and message in the `error` field.\nUse it to alert your team, log the issue, and inform the customer about the situation.\n",
"tags": [
"Loans"
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/WebhookEvent_LoanStatus"
},
"example": {
"type": "loan.error",
"id": "evt_550e8400e29b41d4a71644665544000e",
"api_version": "2026-03-01",
"created_at": 1775286900,
"delivery_id": "dlv_550e8400e29b41d4a71644665544000e",
"timestamp": 1775286900,
"data": {
"id": "ln_550e8400e29b41d4a716446655440001",
"status": "error",
"error": {
"code": "disbursement_failed",
"message": "Falha na transferência bancária"
}
}
}
}
}
},
"security": [
{
"webhookSignature": []
}
],
"parameters": [
{
"$ref": "#/components/parameters/WebhookId"
},
{
"$ref": "#/components/parameters/WebhookTimestamp"
},
{
"$ref": "#/components/parameters/WebhookSignatureHeader"
}
],
"responses": {
"200": {
"description": "Delivery confirmed"
},
"410": {
"description": "Endpoint permanently disabled"
},
"429": {
"description": "Rate-limiting, send rate reduced"
},
"502": {
"description": "Server overload, rate reduced before retrying"
},
"504": {
"description": "Gateway timeout, rate reduced before retrying"
},
"4XX": {
"description": "Client error, failure triggers retry"
},
"5XX": {
"description": "Server error, failure triggers retry"
}
}
}
}
},
"components": {
"securitySchemes": {
"bearerAuth": {
"type": "http",
"scheme": "bearer",
"bearerFormat": "JWT",
"description": "JWT token obtained via OAuth2 Client Credentials. Send `POST /auth/token`\nwith your credentials (`client_id` and `client_secret`) in the\n`Authorization: Basic base64(client_id:client_secret)` header to receive an\naccess token. Include the token in all requests:\n`Authorization: Bearer `. The token expires in 1 hour (3600s).\n\nPrefixes: `dinie_cs_live_` (production), `dinie_cs_test_` (sandbox).\nThe returned token is prefixed with `dinie_at_`.\n"
},
"oauth2": {
"type": "oauth2",
"description": "OAuth2 Client Credentials flow for obtaining access tokens.\nUse `client_id` and `client_secret` to authenticate.\n",
"flows": {
"clientCredentials": {
"tokenUrl": "/api/v3/auth/token",
"scopes": {
"kyc:read": "Read a customer's KYC state (requirements, attachments, status).",
"kyc:upload": "Upload a KYC attachment (document or selfie via the dedicated route).",
"kyc:submit": "Submit a customer's KYC bundle for review.",
"biometrics:create": "Mint a biometrics capture session for a customer (partner side of the handoff).",
"biometrics:exchange": "Exchange a biometrics bootstrap code for a scoped session token (kyc-app side of the handoff)."
}
}
}
},
"webhookSignature": {
"type": "apiKey",
"in": "header",
"name": "webhook-signature",
"description": "HMAC-SHA256 signature per the Standard Webhooks specification.\nVerify using the `whsec_`-prefixed secret from endpoint creation.\nThe header contains base64-encoded signatures; the signed content\nis `{webhook-id}.{webhook-timestamp}.{body}`.\n"
}
},
"parameters": {
"IdempotencyKey": {
"name": "X-Idempotency-Key",
"in": "header",
"required": false,
"description": "Unique string for idempotent POST requests. Cached for 24 hours.",
"schema": {
"type": "string"
}
},
"StartingAfter": {
"name": "starting_after",
"in": "query",
"description": "Prefixed ID of the last item from the previous page.",
"schema": {
"type": "string"
}
},
"Limit": {
"name": "limit",
"in": "query",
"description": "Number of items to return. Min: 1, Max: 100.",
"schema": {
"type": "integer",
"default": 25,
"minimum": 1,
"maximum": 100
}
},
"CustomerId": {
"name": "customer_id",
"in": "path",
"required": true,
"description": "Customer ID",
"schema": {
"$ref": "#/components/schemas/CustomerId"
}
},
"CreditOfferId": {
"name": "credit_offer_id",
"in": "path",
"required": true,
"description": "Credit offer ID",
"schema": {
"$ref": "#/components/schemas/CreditOfferId"
}
},
"LoanId": {
"name": "loan_id",
"in": "path",
"required": true,
"description": "Loan ID",
"schema": {
"$ref": "#/components/schemas/LoanId"
}
},
"WebhookEndpointId": {
"name": "webhook_endpoint_id",
"in": "path",
"required": true,
"description": "Webhook endpoint ID",
"schema": {
"$ref": "#/components/schemas/WebhookEndpointId"
}
},
"WebhookId": {
"name": "webhook-id",
"in": "header",
"required": true,
"schema": {
"$ref": "#/components/schemas/EventId"
},
"description": "Unique delivery ID. Use as idempotency key to deduplicate events"
},
"WebhookTimestamp": {
"name": "webhook-timestamp",
"in": "header",
"required": true,
"schema": {
"type": "integer"
},
"description": "Unix timestamp of the delivery attempt. Reject if older than 5 minutes (replay protection)"
},
"WebhookSignatureHeader": {
"name": "webhook-signature",
"in": "header",
"required": true,
"schema": {
"type": "string"
},
"description": "HMAC-SHA256 signature(s) for verification per Standard Webhooks spec"
}
},
"responses": {
"RateLimited": {
"description": "Rate limit exceeded",
"headers": {
"Retry-After": {
"schema": {
"type": "integer"
},
"description": "Seconds until the rate limit resets"
}
},
"content": {
"application/problem+json": {
"schema": {
"type": "object",
"required": [
"type",
"title",
"status",
"detail"
],
"properties": {
"type": {
"type": "string",
"const": "https://docs.dinie.com/errors/rate-limit-exceeded"
},
"title": {
"type": "string",
"const": "Rate Limit Exceeded"
},
"status": {
"type": "integer",
"const": 429
},
"detail": {
"type": "string"
}
}
},
"example": {
"type": "https://docs.dinie.com/errors/rate-limit-exceeded",
"title": "Rate Limit Exceeded",
"status": 429,
"detail": "Too many requests. Retry after 30 seconds."
}
}
}
},
"InternalError": {
"description": "Internal server error",
"content": {
"application/problem+json": {
"schema": {
"type": "object",
"required": [
"type",
"title",
"status",
"detail"
],
"properties": {
"type": {
"type": "string",
"const": "https://docs.dinie.com/errors/internal"
},
"title": {
"type": "string",
"const": "Internal Error"
},
"status": {
"type": "integer",
"const": 500
},
"detail": {
"type": "string"
}
}
},
"example": {
"type": "https://docs.dinie.com/errors/internal",
"title": "Internal Error",
"status": 500,
"detail": "An unexpected error occurred."
}
}
}
},
"WebhookEndpointNotFound": {
"description": "Webhook endpoint or delivery not found",
"content": {
"application/problem+json": {
"schema": {
"type": "object",
"required": [
"type",
"title",
"status",
"detail",
"code"
],
"properties": {
"type": {
"type": "string",
"const": "https://docs.dinie.com/errors/not-found"
},
"title": {
"type": "string",
"const": "Not Found"
},
"status": {
"type": "integer",
"const": 404
},
"detail": {
"type": "string"
},
"code": {
"type": "string",
"const": "not_found"
}
}
},
"example": {
"type": "https://docs.dinie.com/errors/not-found",
"title": "Not Found",
"status": 404,
"detail": "Endpoint ID does not exist or does not belong to this partner",
"code": "not_found"
}
}
}
},
"BearerTokenUnauthorized": {
"description": "Authentication failed",
"content": {
"application/problem+json": {
"schema": {
"type": "object",
"required": [
"type",
"title",
"status",
"detail",
"code"
],
"properties": {
"type": {
"type": "string",
"const": "https://docs.dinie.com/errors/authentication-failed"
},
"title": {
"type": "string",
"const": "Authentication Failed"
},
"status": {
"type": "integer",
"const": 401
},
"detail": {
"type": "string"
},
"code": {
"type": "string",
"enum": [
"missing_token",
"invalid_token",
"token_expired"
],
"x-enumDescriptions": {
"missing_token": "Authorization header is missing",
"invalid_token": "Bearer token is invalid or malformed",
"token_expired": "Bearer token has expired"
}
}
}
},
"examples": {
"missing_token": {
"summary": "Authorization header is missing",
"value": {
"type": "https://docs.dinie.com/errors/authentication-failed",
"title": "Authentication Failed",
"status": 401,
"detail": "Authorization header is missing",
"code": "missing_token"
}
},
"invalid_token": {
"summary": "Bearer token is invalid or malformed",
"value": {
"type": "https://docs.dinie.com/errors/authentication-failed",
"title": "Authentication Failed",
"status": 401,
"detail": "Bearer token is invalid or malformed",
"code": "invalid_token"
}
},
"token_expired": {
"summary": "Bearer token has expired",
"value": {
"type": "https://docs.dinie.com/errors/authentication-failed",
"title": "Authentication Failed",
"status": 401,
"detail": "Bearer token has expired",
"code": "token_expired"
}
}
}
}
}
},
"ClientCredentialUnauthorized": {
"description": "Authentication failed",
"content": {
"application/problem+json": {
"schema": {
"type": "object",
"required": [
"type",
"title",
"status",
"detail",
"code"
],
"properties": {
"type": {
"type": "string",
"const": "https://docs.dinie.com/errors/authentication-failed"
},
"title": {
"type": "string",
"const": "Authentication Failed"
},
"status": {
"type": "integer",
"const": 401
},
"detail": {
"type": "string"
},
"code": {
"type": "string",
"enum": [
"missing_authorization",
"invalid_client",
"invalid_client_secret",
"credential_revoked",
"credential_expired"
],
"x-enumDescriptions": {
"missing_authorization": "Missing client credentials",
"invalid_client": "`client_id` does not exist",
"invalid_client_secret": "`client_secret` does not match",
"credential_revoked": "Credential has been revoked",
"credential_expired": "Credential has passed its `expires_at`"
}
}
}
},
"examples": {
"missing_authorization": {
"summary": "Missing client credentials",
"value": {
"type": "https://docs.dinie.com/errors/authentication-failed",
"title": "Authentication Failed",
"status": 401,
"detail": "Missing client credentials",
"code": "missing_authorization"
}
},
"invalid_client": {
"summary": "`client_id` does not exist",
"value": {
"type": "https://docs.dinie.com/errors/authentication-failed",
"title": "Authentication Failed",
"status": 401,
"detail": "`client_id` does not exist",
"code": "invalid_client"
}
},
"invalid_client_secret": {
"summary": "`client_secret` does not match",
"value": {
"type": "https://docs.dinie.com/errors/authentication-failed",
"title": "Authentication Failed",
"status": 401,
"detail": "`client_secret` does not match",
"code": "invalid_client_secret"
}
},
"credential_revoked": {
"summary": "Credential has been revoked",
"value": {
"type": "https://docs.dinie.com/errors/authentication-failed",
"title": "Authentication Failed",
"status": 401,
"detail": "Credential has been revoked",
"code": "credential_revoked"
}
},
"credential_expired": {
"summary": "Credential has passed its `expires_at`",
"value": {
"type": "https://docs.dinie.com/errors/authentication-failed",
"title": "Authentication Failed",
"status": 401,
"detail": "Credential has passed its `expires_at`",
"code": "credential_expired"
}
}
}
}
}
},
"Forbidden": {
"description": "The credential is not permitted to perform this action",
"content": {
"application/problem+json": {
"schema": {
"type": "object",
"required": [
"type",
"title",
"status",
"detail",
"code"
],
"properties": {
"type": {
"type": "string",
"const": "https://docs.dinie.com/errors/forbidden"
},
"title": {
"type": "string",
"const": "Forbidden"
},
"status": {
"type": "integer",
"const": 403
},
"detail": {
"type": "string"
},
"code": {
"type": "string",
"const": "forbidden"
}
}
},
"examples": {
"forbidden": {
"summary": "The credential is not permitted to perform this action",
"value": {
"type": "https://docs.dinie.com/errors/forbidden",
"title": "Forbidden",
"status": 403,
"detail": "Forbidden",
"code": "forbidden"
}
}
}
}
}
}
},
"schemas": {
"CustomerId": {
"description": "Unique customer identifier",
"type": "string",
"pattern": "^cust_[0-9a-f]{32}$",
"example": "cust_550e8400e29b41d4a716446655440000"
},
"CreditOfferId": {
"description": "Unique credit offer identifier",
"type": "string",
"pattern": "^co_[0-9a-f]{32}$",
"example": "co_550e8400e29b41d4a716446655440000"
},
"LoanId": {
"description": "Unique loan identifier",
"type": "string",
"pattern": "^ln_[0-9a-f]{32}$",
"example": "ln_550e8400e29b41d4a716446655440000"
},
"TransactionId": {
"description": "Unique transaction identifier",
"type": "string",
"pattern": "^tx_[0-9a-f]{32}$",
"example": "tx_550e8400e29b41d4a716446655440000"
},
"SimulationId": {
"description": "Unique simulation identifier",
"type": "string",
"pattern": "^sim_[0-9a-f]{32}$",
"example": "sim_550e8400e29b41d4a716446655440000"
},
"WebhookEndpointId": {
"description": "Unique webhook endpoint identifier",
"type": "string",
"pattern": "^we_[0-9a-f]{32}$",
"example": "we_550e8400e29b41d4a716446655440000"
},
"WebhookDeliveryId": {
"description": "Unique identifier for a webhook delivery attempt",
"type": "string",
"pattern": "^dlv_[0-9a-f]{32}$",
"example": "dlv_550e8400e29b41d4a716446655440000"
},
"ApiClientId": {
"description": "Unique API credential identifier (includes the `live`/`test` environment prefix)",
"type": "string",
"pattern": "^dinie_ci_(live|test)_[A-Za-z0-9]+$",
"example": "dinie_ci_live_550e8400e29b41d4a71644"
},
"BankAccountId": {
"description": "Unique bank account identifier",
"type": "string",
"pattern": "^ba_[0-9a-f]{32}$",
"example": "ba_550e8400e29b41d4a716446655440000"
},
"Money": {
"type": "number",
"format": "double",
"description": "Monetary value in BRL",
"example": 25000
},
"TokenResponse": {
"description": "Response containing the JWT access token",
"type": "object",
"required": [
"access_token",
"token_type",
"expires_in"
],
"properties": {
"access_token": {
"type": "string",
"description": "JWT access token",
"example": "dinie_at_eyJhbGciOiJIUzI1NiJ9..."
},
"token_type": {
"type": "string",
"description": "Type of the returned token",
"const": "bearer"
},
"expires_in": {
"type": "integer",
"description": "Token lifetime in seconds",
"example": 3600
}
}
},
"CreateCredentialRequest": {
"description": "Data to create a new API credential",
"type": "object",
"required": [
"name"
],
"properties": {
"name": {
"type": "string",
"description": "Human-readable label for this key",
"example": "Production Key"
},
"expires_at": {
"type": [
"integer",
"null"
],
"format": "int64",
"description": "Optional expiration date as Unix epoch seconds. Null means never expires.",
"example": 1803945600
}
}
},
"Credential": {
"description": "Partner API credential",
"type": "object",
"required": [
"id",
"client_id",
"name",
"status",
"last_used_at",
"expires_at",
"created_at",
"updated_at"
],
"properties": {
"id": {
"$ref": "#/components/schemas/ApiClientId",
"description": "Unique credential identifier"
},
"client_id": {
"$ref": "#/components/schemas/ApiClientId",
"description": "Public credential identifier used for authentication"
},
"name": {
"type": "string",
"description": "Human-readable credential label",
"example": "Production Key"
},
"status": {
"type": "string",
"description": "Current credential state",
"enum": [
"active",
"revoked"
],
"x-enumDescriptions": {
"active": "Active and functional credential",
"revoked": "Permanently revoked credential"
}
},
"last_used_at": {
"type": [
"integer",
"null"
],
"format": "int64",
"description": "Unix epoch seconds of last use, `null` if never used"
},
"expires_at": {
"type": [
"integer",
"null"
],
"format": "int64",
"description": "Unix epoch seconds of expiration, `null` for no expiration"
},
"created_at": {
"type": "integer",
"format": "int64",
"description": "Unix epoch seconds"
},
"updated_at": {
"type": "integer",
"format": "int64",
"description": "Unix epoch seconds"
}
}
},
"CredentialWithSecret": {
"description": "Returned only at creation. The `client_secret` cannot be retrieved again.",
"allOf": [
{
"$ref": "#/components/schemas/Credential"
},
{
"type": "object",
"required": [
"client_secret"
],
"properties": {
"client_secret": {
"type": "string",
"description": "Store securely -- shown only once",
"example": "dinie_cs_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
}
}
}
]
},
"CreateCustomerRequest": {
"description": "Data to register a new customer",
"type": "object",
"required": [
"email",
"phone",
"cpf",
"cnpj"
],
"properties": {
"external_id": {
"type": "string",
"description": "Partner external reference for this customer",
"example": "partner-ref-123"
},
"name": {
"type": "string",
"description": "Customer's full name, auto-fetched from government records via CPF when not provided",
"example": "Joao Silva"
},
"email": {
"type": "string",
"format": "email",
"example": "joao@example.com",
"description": "Contact email"
},
"phone": {
"type": "string",
"pattern": "^\\+55\\d{10,11}$",
"description": "E.164 format — Brazilian numbers only (+55 followed by 10 or 11 digits)",
"example": "+5511999999999"
},
"cpf": {
"type": "string",
"pattern": "^\\d{3}\\.\\d{3}\\.\\d{3}-\\d{2}$",
"description": "Customer CPF (required)",
"example": "123.456.789-00"
},
"cnpj": {
"type": "string",
"pattern": "^\\d{2}\\.\\d{3}\\.\\d{3}/\\d{4}-\\d{2}$",
"description": "Company CNPJ",
"example": "12.345.678/0001-90"
}
}
},
"UpdateCustomerRequest": {
"description": "Data to update an existing customer",
"type": "object",
"properties": {
"email": {
"type": "string",
"format": "email",
"description": "New contact email"
},
"phone": {
"type": "string",
"pattern": "^\\+55\\d{10,11}$",
"description": "New contact phone — E.164, Brazilian numbers only (+55 followed by 10 or 11 digits)"
}
}
},
"Customer": {
"description": "Full representation of a registered customer",
"type": "object",
"required": [
"id",
"external_id",
"name",
"email",
"phone",
"cpf",
"cnpj",
"trading_name",
"status",
"created_at",
"updated_at"
],
"properties": {
"id": {
"$ref": "#/components/schemas/CustomerId",
"description": "Unique customer identifier"
},
"external_id": {
"type": [
"string",
"null"
],
"example": "partner-ref-123",
"description": "Partner's reference ID for this customer"
},
"name": {
"type": [
"string",
"null"
],
"example": "Joao Silva",
"description": "Legal name of the business owner"
},
"email": {
"type": "string",
"format": "email",
"example": "joao@example.com",
"description": "Contact email"
},
"phone": {
"type": "string",
"pattern": "^\\+[1-9]\\d{1,14}$",
"example": "+5511999999999",
"description": "Contact phone in E.164 format"
},
"cpf": {
"type": "string",
"pattern": "^\\d{3}\\.\\d{3}\\.\\d{3}-\\d{2}$",
"description": "Customer CPF. Always formatted as `XXX.XXX.XXX-XX` in responses",
"example": "123.456.789-00"
},
"cnpj": {
"type": [
"string",
"null"
],
"pattern": "^\\d{2}\\.\\d{3}\\.\\d{3}/\\d{4}-\\d{2}$",
"description": "Company CNPJ. Always formatted as `XX.XXX.XXX/XXXX-XX` in responses",
"example": "12.345.678/0001-90"
},
"trading_name": {
"type": [
"string",
"null"
],
"example": "Loja do Joao",
"description": "Business trade name"
},
"status": {
"type": "string",
"enum": [
"creating",
"pending_kyc",
"under_review",
"active",
"denied"
],
"x-enumDescriptions": {
"creating": "Registration received, co-owner enrichment in progress",
"pending_kyc": "Customer registered, but KYC documents/biometrics not yet submitted or under review",
"under_review": "All required KYC items submitted; Dinie's compliance team is reviewing",
"active": "KYC approved; customer is eligible to receive credit offers",
"denied": "Permanently blocked (fraud, closed company, or other terminal condition)"
},
"description": "Lifecycle state: `creating`, `pending_kyc`, `under_review`, `active`, `denied`"
},
"kyc": {
"type": "array",
"description": "KYC requirements array. Omitted during `creating` status. Present from `pending_kyc` onward",
"items": {
"$ref": "#/components/schemas/KycRequirement"
}
},
"created_at": {
"type": "integer",
"format": "int64",
"description": "When this resource was created (Unix epoch seconds)"
},
"updated_at": {
"type": "integer",
"format": "int64",
"description": "When this resource was last modified (Unix epoch seconds)"
}
}
},
"KycRequirement": {
"oneOf": [
{
"$ref": "#/components/schemas/IdentityRequirement"
},
{
"$ref": "#/components/schemas/SelfieRequirement"
},
{
"$ref": "#/components/schemas/ProofOfAddressRequirement"
},
{
"$ref": "#/components/schemas/CompanyDocumentRequirement"
},
{
"$ref": "#/components/schemas/EiMeiDocumentsRequirement"
},
{
"$ref": "#/components/schemas/IncomeStatementRequirement"
},
{
"$ref": "#/components/schemas/ArticlesOfAssociationRequirement"
},
{
"$ref": "#/components/schemas/EireliIncorporationStatementRequirement"
},
{
"$ref": "#/components/schemas/EmailRequirement"
}
],
"discriminator": {
"propertyName": "requirement_type",
"mapping": {
"identity": "#/components/schemas/IdentityRequirement",
"selfie": "#/components/schemas/SelfieRequirement",
"proof_of_address": "#/components/schemas/ProofOfAddressRequirement",
"company_document": "#/components/schemas/CompanyDocumentRequirement",
"ei_mei_documents": "#/components/schemas/EiMeiDocumentsRequirement",
"income_statement": "#/components/schemas/IncomeStatementRequirement",
"articles_of_association": "#/components/schemas/ArticlesOfAssociationRequirement",
"eireli_incorporation_statement": "#/components/schemas/EireliIncorporationStatementRequirement",
"email": "#/components/schemas/EmailRequirement"
}
},
"description": "A KYC requirement — something that needs to be verified (e.g., identity, address). Discriminated by `requirement_type`. Person-specific requirements include a `subject` field; company-wide requirements do not."
},
"KycSubject": {
"type": "object",
"required": [
"id",
"name",
"subject_type"
],
"properties": {
"id": {
"type": "string",
"description": "Opaque identifier for this subject (used in `requirement_id` suffix and document uploads).",
"example": "003XXXXXXXXXXXXXXX"
},
"name": {
"type": "string",
"description": "Human-readable name of the subject.",
"example": "Joao Silva"
},
"subject_type": {
"type": "string",
"enum": [
"applicant",
"co_owner"
],
"description": "`applicant` — the customer themselves. `co_owner` — a director/shareholder of the company.",
"x-enumDescriptions": {
"applicant": "The customer themselves (applicant)",
"co_owner": "Director or shareholder of the company"
}
}
},
"description": "Identifies who the requirement is about (a person or company co-owner)."
},
"IdentityRequirement": {
"type": "object",
"required": [
"requirement_type",
"requirement_id",
"label",
"mandatory",
"subject"
],
"properties": {
"requirement_type": {
"type": "string",
"description": "KYC requirement type discriminator",
"const": "identity"
},
"requirement_id": {
"type": "string",
"description": "Format: `identity_{subject_id}`",
"example": "identity_003XXXXXXXXXXXXXXX"
},
"label": {
"type": "string",
"description": "Human-readable label.",
"example": "Documento de identidade"
},
"mandatory": {
"type": "boolean",
"description": "Whether this requirement must be fulfilled"
},
"subject": {
"$ref": "#/components/schemas/KycSubject",
"description": "Person associated with this requirement"
},
"submitted": {
"oneOf": [
{
"$ref": "#/components/schemas/IdentityCnhSubmitted"
},
{
"$ref": "#/components/schemas/IdentityRgSubmitted"
}
],
"description": "Evidence submitted for this requirement. Absent if nothing submitted yet"
}
},
"description": "Identity document requirement (CNH or RG). Always person-specific."
},
"IdentityCnhSubmitted": {
"type": "object",
"required": [
"evidence_type",
"attachments",
"review_status",
"review_reason"
],
"properties": {
"evidence_type": {
"type": "string",
"description": "Type of submitted evidence",
"const": "cnh"
},
"attachments": {
"oneOf": [
{
"$ref": "#/components/schemas/CnhPhysicalAttachmentSet"
},
{
"$ref": "#/components/schemas/CnhDigitalAttachmentSet"
}
],
"description": "Physical CNH (front + back photos) or digital CNH (single PDF)"
},
"review_status": {
"$ref": "#/components/schemas/ReviewStatus",
"description": "Document review status"
},
"review_reason": {
"$ref": "#/components/schemas/ReviewReason",
"description": "Rejection reason, `null` if approved"
}
},
"description": "CNH evidence — either physical (front + back) or digital (single PDF)."
},
"CnhPhysicalAttachmentSet": {
"type": "array",
"description": "Physical CNH — front and back photos.",
"minItems": 2,
"maxItems": 2,
"items": {
"type": "object",
"required": [
"attachment_type",
"submitted"
],
"properties": {
"attachment_type": {
"type": "string",
"description": "Physical CNH attachment type",
"enum": [
"front",
"back"
],
"x-enumDescriptions": {
"front": "Front of the document",
"back": "Back of the document"
}
},
"submitted": {
"type": "boolean",
"description": "`true` if this slot has been filled"
}
}
}
},
"CnhDigitalAttachmentSet": {
"type": "array",
"description": "Digital CNH — single PDF file.",
"minItems": 1,
"maxItems": 1,
"items": {
"type": "object",
"required": [
"attachment_type",
"submitted"
],
"properties": {
"attachment_type": {
"type": "string",
"description": "Digital CNH attachment type",
"const": "file"
},
"submitted": {
"type": "boolean",
"description": "`true` if this slot has been filled"
}
}
}
},
"IdentityRgSubmitted": {
"type": "object",
"required": [
"evidence_type",
"attachments",
"review_status",
"review_reason"
],
"properties": {
"evidence_type": {
"type": "string",
"description": "Type of submitted evidence",
"const": "rg"
},
"attachments": {
"type": "array",
"description": "RG — front and back photos",
"minItems": 2,
"maxItems": 2,
"items": {
"type": "object",
"required": [
"attachment_type",
"submitted"
],
"properties": {
"attachment_type": {
"type": "string",
"description": "RG attachment type",
"enum": [
"front",
"back"
],
"x-enumDescriptions": {
"front": "Front of the document",
"back": "Back of the document"
}
},
"submitted": {
"type": "boolean",
"description": "`true` if this slot has been filled"
}
}
}
},
"review_status": {
"$ref": "#/components/schemas/ReviewStatus",
"description": "Document review status"
},
"review_reason": {
"$ref": "#/components/schemas/ReviewReason",
"description": "Rejection reason, `null` if approved"
}
},
"description": "RG evidence — front and back photos."
},
"SelfieRequirement": {
"type": "object",
"required": [
"requirement_type",
"requirement_id",
"label",
"mandatory",
"subject"
],
"properties": {
"requirement_type": {
"type": "string",
"description": "KYC requirement type discriminator",
"const": "selfie"
},
"requirement_id": {
"type": "string",
"description": "Format: `selfie_{subject_id}`",
"example": "selfie_003XXXXXXXXXXXXXXX"
},
"label": {
"type": "string",
"description": "Human-readable requirement label",
"example": "Selfie"
},
"mandatory": {
"type": "boolean",
"description": "Whether this requirement is mandatory"
},
"subject": {
"$ref": "#/components/schemas/KycSubject",
"description": "Person associated with this requirement"
},
"submitted": {
"$ref": "#/components/schemas/SelfieSubmitted",
"description": "Submitted evidence and review status"
}
},
"description": "Selfie requirement. Always person-specific."
},
"SelfieSubmitted": {
"type": "object",
"required": [
"evidence_type",
"attachments",
"review_status",
"review_reason"
],
"properties": {
"evidence_type": {
"type": "string",
"description": "Type of submitted evidence",
"const": "selfie"
},
"attachments": {
"type": "array",
"description": "Submitted selfie photo",
"minItems": 1,
"maxItems": 1,
"items": {
"type": "object",
"required": [
"attachment_type",
"submitted"
],
"properties": {
"attachment_type": {
"type": "string",
"description": "Type of submitted attachment",
"const": "photo"
},
"submitted": {
"type": "boolean",
"description": "`true` if this slot has been filled"
}
}
}
},
"review_status": {
"$ref": "#/components/schemas/ReviewStatus",
"description": "Document review state"
},
"review_reason": {
"$ref": "#/components/schemas/ReviewReason",
"description": "Rejection reason, `null` if approved"
}
},
"description": "Selfie evidence."
},
"ProofOfAddressRequirement": {
"type": "object",
"required": [
"requirement_type",
"requirement_id",
"label",
"mandatory",
"subject"
],
"properties": {
"requirement_type": {
"type": "string",
"description": "KYC requirement type discriminator",
"const": "proof_of_address"
},
"requirement_id": {
"type": "string",
"description": "Format: `proof_of_address_{subject_id}`",
"example": "proof_of_address_003XXXXXXXXXXXXXXX"
},
"label": {
"type": "string",
"description": "Human-readable requirement label",
"example": "Comprovante de endereço"
},
"mandatory": {
"type": "boolean",
"description": "Whether this requirement is mandatory"
},
"subject": {
"$ref": "#/components/schemas/KycSubject",
"description": "Person associated with this requirement"
},
"submitted": {
"$ref": "#/components/schemas/ProofOfAddressSubmitted",
"description": "Submitted evidence and review status"
}
},
"description": "Proof of address requirement. Always person-specific."
},
"ProofOfAddressSubmitted": {
"type": "object",
"required": [
"evidence_type",
"attachments",
"review_status",
"review_reason"
],
"properties": {
"evidence_type": {
"type": "string",
"description": "Type of submitted evidence",
"const": "proof_of_address"
},
"attachments": {
"type": "array",
"description": "Submitted proof of address file",
"minItems": 1,
"maxItems": 1,
"items": {
"type": "object",
"required": [
"attachment_type",
"submitted"
],
"properties": {
"attachment_type": {
"type": "string",
"description": "Type of submitted attachment",
"const": "file"
},
"submitted": {
"type": "boolean",
"description": "`true` if this slot has been filled"
}
}
}
},
"review_status": {
"$ref": "#/components/schemas/ReviewStatus",
"description": "Document review state"
},
"review_reason": {
"$ref": "#/components/schemas/ReviewReason",
"description": "Rejection reason, `null` if approved"
}
},
"description": "Proof of address evidence."
},
"CompanyDocumentRequirement": {
"type": "object",
"required": [
"requirement_type",
"requirement_id",
"label",
"mandatory"
],
"properties": {
"requirement_type": {
"type": "string",
"description": "KYC requirement type discriminator",
"const": "company_document"
},
"requirement_id": {
"type": "string",
"description": "Fixed requirement identifier",
"example": "company_document_001XXXXXXXXXXXXXXX"
},
"label": {
"type": "string",
"description": "Human-readable requirement label",
"example": "Documento da empresa"
},
"mandatory": {
"type": "boolean",
"description": "Whether this requirement is mandatory"
},
"submitted": {
"$ref": "#/components/schemas/CompanyDocumentSubmitted",
"description": "Submitted evidence and review status"
}
},
"description": "Company document requirement (CCMEI). No subject — applies to the customer's company."
},
"CompanyDocumentSubmitted": {
"type": "object",
"required": [
"evidence_type",
"attachments",
"review_status",
"review_reason"
],
"properties": {
"evidence_type": {
"type": "string",
"description": "Type of submitted evidence",
"const": "ccmei"
},
"attachments": {
"type": "array",
"description": "Submitted CCMEI file",
"minItems": 1,
"maxItems": 1,
"items": {
"type": "object",
"required": [
"attachment_type",
"submitted"
],
"properties": {
"attachment_type": {
"type": "string",
"description": "Type of submitted attachment",
"const": "file"
},
"submitted": {
"type": "boolean",
"description": "`true` if this slot has been filled"
}
}
}
},
"review_status": {
"$ref": "#/components/schemas/ReviewStatus",
"description": "Document review state"
},
"review_reason": {
"$ref": "#/components/schemas/ReviewReason",
"description": "Rejection reason, `null` if approved"
}
},
"description": "Company document evidence."
},
"EiMeiDocumentsRequirement": {
"type": "object",
"required": [
"requirement_type",
"requirement_id",
"label",
"mandatory"
],
"properties": {
"requirement_type": {
"type": "string",
"description": "KYC requirement type discriminator",
"const": "ei_mei_documents"
},
"requirement_id": {
"type": "string",
"description": "Fixed requirement identifier",
"const": "ei_mei_documents"
},
"label": {
"type": "string",
"description": "Human-readable requirement label",
"example": "Documentos de EI/MEI"
},
"mandatory": {
"type": "boolean",
"description": "Whether this requirement is mandatory"
},
"submitted": {
"$ref": "#/components/schemas/EiMeiDocumentsSubmitted",
"description": "Submitted evidence and review status"
}
},
"description": "EI/MEI documents requirement. Both attachments (EI registration + CCMEI) are required. No subject."
},
"EiMeiDocumentsSubmitted": {
"type": "object",
"required": [
"evidence_type",
"attachments",
"review_status",
"review_reason"
],
"properties": {
"evidence_type": {
"type": "string",
"description": "Type of submitted evidence",
"const": "ei_mei"
},
"attachments": {
"type": "array",
"description": "Both attachments are required",
"minItems": 2,
"maxItems": 2,
"items": {
"type": "object",
"required": [
"attachment_type",
"submitted"
],
"properties": {
"attachment_type": {
"type": "string",
"description": "Type of submitted attachment",
"enum": [
"ei_registration_requirement",
"ccmei"
],
"x-enumDescriptions": {
"ei_registration_requirement": "EI registration requirement document",
"ccmei": "MEI Registration Certificate (CCMEI)"
}
},
"submitted": {
"type": "boolean",
"description": "`true` if this slot has been filled"
}
}
}
},
"review_status": {
"$ref": "#/components/schemas/ReviewStatus",
"description": "Document review status"
},
"review_reason": {
"$ref": "#/components/schemas/ReviewReason",
"description": "Rejection reason, `null` if approved"
}
},
"description": "EI/MEI evidence."
},
"IncomeStatementRequirement": {
"type": "object",
"required": [
"requirement_type",
"requirement_id",
"label",
"mandatory"
],
"properties": {
"requirement_type": {
"type": "string",
"description": "KYC requirement type discriminator",
"const": "income_statement"
},
"requirement_id": {
"type": "string",
"description": "Fixed requirement identifier",
"const": "income_statement"
},
"label": {
"type": "string",
"description": "Human-readable requirement label",
"example": "Declaração de faturamento"
},
"mandatory": {
"type": "boolean",
"description": "Whether this requirement is mandatory"
},
"submitted": {
"$ref": "#/components/schemas/IncomeStatementSubmitted",
"description": "Submitted evidence and review status"
}
},
"description": "Income statement requirement. No subject — applies to the customer's company."
},
"IncomeStatementSubmitted": {
"type": "object",
"required": [
"evidence_type",
"attachments",
"review_status",
"review_reason"
],
"properties": {
"evidence_type": {
"type": "string",
"description": "Type of submitted evidence",
"const": "income_statement"
},
"attachments": {
"type": "array",
"description": "Submitted revenue statement file",
"minItems": 1,
"maxItems": 1,
"items": {
"type": "object",
"required": [
"attachment_type",
"submitted"
],
"properties": {
"attachment_type": {
"type": "string",
"description": "Type of submitted attachment",
"const": "file"
},
"submitted": {
"type": "boolean",
"description": "`true` if this slot has been filled"
}
}
}
},
"review_status": {
"$ref": "#/components/schemas/ReviewStatus",
"description": "Document review state"
},
"review_reason": {
"$ref": "#/components/schemas/ReviewReason",
"description": "Rejection reason, `null` if approved"
}
},
"description": "Income statement evidence."
},
"ArticlesOfAssociationRequirement": {
"type": "object",
"required": [
"requirement_type",
"requirement_id",
"label",
"mandatory"
],
"properties": {
"requirement_type": {
"type": "string",
"description": "KYC requirement type discriminator",
"const": "articles_of_association"
},
"requirement_id": {
"type": "string",
"description": "Fixed requirement identifier",
"const": "articles_of_association"
},
"label": {
"type": "string",
"description": "Human-readable requirement label",
"example": "Contrato social"
},
"mandatory": {
"type": "boolean",
"description": "Whether this requirement is mandatory"
},
"submitted": {
"$ref": "#/components/schemas/ArticlesOfAssociationSubmitted",
"description": "Submitted evidence and review status"
}
},
"description": "Articles of association requirement. No subject — applies to the customer's company."
},
"ArticlesOfAssociationSubmitted": {
"type": "object",
"required": [
"evidence_type",
"attachments",
"review_status",
"review_reason"
],
"properties": {
"evidence_type": {
"type": "string",
"description": "Type of submitted evidence",
"const": "articles_of_association"
},
"attachments": {
"type": "array",
"description": "Submitted articles of association file",
"minItems": 1,
"maxItems": 1,
"items": {
"type": "object",
"required": [
"attachment_type",
"submitted"
],
"properties": {
"attachment_type": {
"type": "string",
"description": "Type of submitted attachment",
"const": "file"
},
"submitted": {
"type": "boolean",
"description": "`true` if this slot has been filled"
}
}
}
},
"review_status": {
"$ref": "#/components/schemas/ReviewStatus",
"description": "Document review state"
},
"review_reason": {
"$ref": "#/components/schemas/ReviewReason",
"description": "Rejection reason, `null` if approved"
}
},
"description": "Articles of association evidence."
},
"EireliIncorporationStatementRequirement": {
"type": "object",
"required": [
"requirement_type",
"requirement_id",
"label",
"mandatory"
],
"properties": {
"requirement_type": {
"type": "string",
"description": "KYC requirement type discriminator",
"const": "eireli_incorporation_statement"
},
"requirement_id": {
"type": "string",
"description": "Fixed requirement identifier",
"const": "eireli_incorporation_statement"
},
"label": {
"type": "string",
"description": "Human-readable requirement label",
"example": "Ato constitutivo de EIRELI"
},
"mandatory": {
"type": "boolean",
"description": "Whether this requirement is mandatory"
},
"submitted": {
"$ref": "#/components/schemas/EireliIncorporationStatementSubmitted",
"description": "Submitted evidence and review status"
}
},
"description": "EIRELI incorporation statement requirement. No subject — applies to the customer's company."
},
"EireliIncorporationStatementSubmitted": {
"type": "object",
"required": [
"evidence_type",
"attachments",
"review_status",
"review_reason"
],
"properties": {
"evidence_type": {
"type": "string",
"description": "Type of submitted evidence",
"const": "eireli_incorporation_statement"
},
"attachments": {
"type": "array",
"description": "Submitted EIRELI incorporation statement file",
"minItems": 1,
"maxItems": 1,
"items": {
"type": "object",
"required": [
"attachment_type",
"submitted"
],
"properties": {
"attachment_type": {
"type": "string",
"description": "Type of submitted attachment",
"const": "file"
},
"submitted": {
"type": "boolean",
"description": "`true` if this slot has been filled"
}
}
}
},
"review_status": {
"$ref": "#/components/schemas/ReviewStatus",
"description": "Document review state"
},
"review_reason": {
"$ref": "#/components/schemas/ReviewReason",
"description": "Rejection reason, `null` if approved"
}
},
"description": "EIRELI incorporation statement evidence."
},
"EmailRequirement": {
"type": "object",
"required": [
"requirement_type",
"requirement_id",
"label",
"mandatory",
"subject"
],
"properties": {
"requirement_type": {
"type": "string",
"description": "KYC requirement type discriminator",
"const": "email"
},
"requirement_id": {
"type": "string",
"description": "Format: `email_{subject_id}`",
"example": "email_003XXXXXXXXXXXXXXX"
},
"label": {
"type": "string",
"description": "Human-readable requirement label",
"example": "Email do co-titular para assinatura da CCB"
},
"mandatory": {
"type": "boolean",
"description": "Whether this requirement is mandatory"
},
"subject": {
"$ref": "#/components/schemas/KycSubject",
"description": "Person associated with this requirement"
},
"submitted": {
"$ref": "#/components/schemas/EmailSubmitted",
"description": "Submitted evidence and review status"
}
},
"description": "Email verification requirement. Data-only — no evidence or attachments. Corrections are made via `PATCH /customers/{id}`."
},
"EmailSubmitted": {
"type": "object",
"required": [
"evidence_type",
"attachments",
"review_status",
"review_reason"
],
"properties": {
"evidence_type": {
"type": "string",
"description": "Type of submitted evidence",
"const": "email"
},
"attachments": {
"type": "array",
"description": "Email submitted for CCB contract signing",
"minItems": 1,
"maxItems": 1,
"items": {
"type": "object",
"required": [
"attachment_type",
"submitted"
],
"properties": {
"attachment_type": {
"type": "string",
"description": "Type of submitted attachment",
"const": "email"
},
"submitted": {
"type": "boolean",
"description": "`true` if this slot has been filled"
}
}
}
},
"review_status": {
"$ref": "#/components/schemas/ReviewStatus",
"description": "Document review status"
},
"review_reason": {
"$ref": "#/components/schemas/ReviewReason",
"description": "Rejection reason, `null` if approved"
}
},
"description": "Email verification state. No evidence_type or attachments — this is a data-field validation."
},
"ReviewStatus": {
"type": "string",
"enum": [
"pending",
"accepted",
"rejected"
],
"description": "`pending` — awaiting review. `accepted` — approved. `rejected` — partner must resubmit."
},
"ReviewReason": {
"type": [
"string",
"null"
],
"description": "Explanation when `review_status` is `rejected`. `null` otherwise."
},
"KycAttachmentResponse": {
"type": "object",
"required": [
"attachment_type",
"submitted"
],
"properties": {
"attachment_type": {
"type": "string",
"description": "Echoes the slot just submitted",
"example": "front"
},
"submitted": {
"type": "boolean",
"description": "Always `true` on a successful upload — confirms the slot was filled"
}
},
"description": "Confirmation that a KYC attachment slot was filled. Read the customer endpoint to see the full requirement state."
},
"Bank": {
"type": "object",
"required": [
"id",
"name",
"display_name"
],
"properties": {
"id": {
"type": "string",
"example": "001",
"description": "Bank COMPE code"
},
"name": {
"type": "string",
"example": "Banco do Brasil",
"description": "Bank name"
},
"display_name": {
"type": "string",
"example": "001 - Banco do Brasil",
"description": "Code and name formatted for display"
}
},
"description": "A bank available for customer bank account submission"
},
"CustomerBankAccountRequest": {
"type": "object",
"required": [
"bank_id",
"kind",
"branch",
"number",
"digit"
],
"properties": {
"bank_id": {
"type": "string",
"description": "Bank COMPE code; zero-padded to 3 digits when stored",
"pattern": "^\\d{1,3}$",
"example": "001"
},
"kind": {
"type": "string",
"enum": [
"checking",
"saving",
"payment"
],
"description": "Account type: `checking`, `saving`, `payment`"
},
"branch": {
"type": "string",
"description": "Branch number without the check digit; zero-padded to 4 digits when stored",
"pattern": "^\\d{1,4}$",
"example": "0001"
},
"number": {
"type": "string",
"pattern": "^\\d+$",
"example": "1234567",
"description": "Account number"
},
"digit": {
"type": "string",
"description": "Account check digit (a single digit, or \"X\" for some banks)",
"pattern": "^[0-9Xx]$",
"example": "0"
}
},
"description": "Customer disbursement bank account data"
},
"CustomerBankAccount": {
"allOf": [
{
"$ref": "#/components/schemas/CustomerBankAccountRequest"
},
{
"type": "object",
"required": [
"id",
"bank_name",
"updated_at"
],
"properties": {
"id": {
"$ref": "#/components/schemas/BankAccountId",
"description": "Unique bank account identifier"
},
"bank_name": {
"type": "string",
"description": "Bank name"
},
"updated_at": {
"type": "integer",
"format": "int64",
"description": "Unix epoch in seconds"
}
}
}
],
"description": "Disbursement bank account linked to the customer"
},
"KycUploadCnh": {
"type": "object",
"required": [
"evidence_type",
"requirement_id",
"attachment_type",
"file"
],
"properties": {
"evidence_type": {
"type": "string",
"description": "Evidence type to submit",
"const": "cnh"
},
"requirement_id": {
"type": "string",
"description": "Format: `identity_{subject_id}`",
"example": "identity_003XXXXXXXXXXXXXXX"
},
"attachment_type": {
"type": "string",
"description": "Physical CNH: `front` and `back`. Digital CNH: `file` (single PDF)",
"enum": [
"front",
"back",
"file"
],
"x-enumDescriptions": {
"front": "Document front",
"back": "Document back",
"file": "PDF file"
}
},
"file": {
"type": "string",
"format": "binary",
"description": "Binary file upload (JPEG, PNG for physical; PDF for digital)"
}
},
"description": "Upload a CNH (driver's license) attachment"
},
"KycUploadRg": {
"type": "object",
"required": [
"evidence_type",
"requirement_id",
"attachment_type",
"file"
],
"properties": {
"evidence_type": {
"type": "string",
"description": "Evidence type to submit",
"const": "rg"
},
"requirement_id": {
"type": "string",
"description": "Format: `identity_{subject_id}`",
"example": "identity_003XXXXXXXXXXXXXXX"
},
"attachment_type": {
"type": "string",
"description": "RG: `front` and `back`",
"enum": [
"front",
"back"
],
"x-enumDescriptions": {
"front": "Document front",
"back": "Document back"
}
},
"file": {
"type": "string",
"format": "binary",
"description": "Binary file upload (JPEG, PNG)"
}
},
"description": "Upload an RG (identity card) attachment"
},
"KycUploadSelfie": {
"type": "object",
"required": [
"evidence_type",
"requirement_id",
"attachment_type",
"file"
],
"properties": {
"evidence_type": {
"type": "string",
"description": "Evidence type to submit",
"const": "selfie"
},
"requirement_id": {
"type": "string",
"description": "Format: `selfie_{subject_id}`",
"example": "selfie_003XXXXXXXXXXXXXXX"
},
"attachment_type": {
"type": "string",
"description": "Attachment type",
"const": "photo"
},
"file": {
"type": "string",
"format": "binary",
"description": "Binary file upload (JPEG, PNG)"
}
},
"description": "Upload a selfie photo for biometric validation"
},
"KycUploadProofOfAddress": {
"type": "object",
"required": [
"evidence_type",
"requirement_id",
"attachment_type",
"file"
],
"properties": {
"evidence_type": {
"type": "string",
"description": "Evidence type to submit",
"const": "proof_of_address"
},
"requirement_id": {
"type": "string",
"description": "Format: `proof_of_address_{subject_id}`",
"example": "proof_of_address_003XXXXXXXXXXXXXXX"
},
"attachment_type": {
"type": "string",
"description": "Attachment type",
"const": "file"
},
"file": {
"type": "string",
"format": "binary",
"description": "Binary file upload (PDF, JPEG, PNG)"
}
},
"description": "Upload a proof of address document"
},
"KycUploadCcmei": {
"type": "object",
"required": [
"evidence_type",
"requirement_id",
"attachment_type",
"file"
],
"properties": {
"evidence_type": {
"type": "string",
"description": "Evidence type to submit",
"const": "ccmei"
},
"requirement_id": {
"type": "string",
"description": "Company document requirement identifier",
"pattern": "^company_document_.+$",
"example": "company_document_001XXXXXXXXXXXXXXX"
},
"attachment_type": {
"type": "string",
"description": "Attachment type",
"const": "file"
},
"file": {
"type": "string",
"format": "binary",
"description": "Binary file upload (PDF, JPEG, PNG)"
}
},
"description": "Upload a CCMEI (Individual Micro-Entrepreneur Status Certificate)"
},
"KycUploadEiMei": {
"type": "object",
"required": [
"evidence_type",
"requirement_id",
"attachment_type",
"file"
],
"properties": {
"evidence_type": {
"type": "string",
"description": "Evidence type to submit",
"const": "ei_mei"
},
"requirement_id": {
"type": "string",
"description": "EI/MEI document requirement identifier",
"pattern": "^ei_mei_documents_.+$",
"example": "ei_mei_documents_001XXXXXXXXXXXXXXX"
},
"attachment_type": {
"type": "string",
"description": "Two documents required: `ei_registration_requirement` and `ccmei`",
"enum": [
"ei_registration_requirement",
"ccmei"
],
"x-enumDescriptions": {
"ei_registration_requirement": "EI registration requirement form",
"ccmei": "MEI status certificate (CCMEI)"
}
},
"file": {
"type": "string",
"format": "binary",
"description": "Binary file upload (PDF, JPEG, PNG)"
}
},
"description": "Upload an EI/MEI document (registration requirement or CCMEI)"
},
"KycUploadIncomeStatement": {
"type": "object",
"required": [
"evidence_type",
"requirement_id",
"attachment_type",
"file"
],
"properties": {
"evidence_type": {
"type": "string",
"description": "Evidence type to submit",
"const": "income_statement"
},
"requirement_id": {
"type": "string",
"description": "Revenue statement requirement identifier",
"pattern": "^income_statement_.+$",
"example": "income_statement_001XXXXXXXXXXXXXXX"
},
"attachment_type": {
"type": "string",
"description": "Attachment type",
"const": "file"
},
"file": {
"type": "string",
"format": "binary",
"description": "Binary file upload (PDF, JPEG, PNG)"
}
},
"description": "Upload an income statement (DRE)"
},
"KycUploadArticlesOfAssociation": {
"type": "object",
"required": [
"evidence_type",
"requirement_id",
"attachment_type",
"file"
],
"properties": {
"evidence_type": {
"type": "string",
"description": "Evidence type to submit",
"const": "articles_of_association"
},
"requirement_id": {
"type": "string",
"description": "Articles of association requirement identifier",
"pattern": "^articles_of_association_.+$",
"example": "articles_of_association_001XXXXXXXXXXXXXXX"
},
"attachment_type": {
"type": "string",
"description": "Attachment type",
"const": "file"
},
"file": {
"type": "string",
"format": "binary",
"description": "Binary file upload (PDF, JPEG, PNG)"
}
},
"description": "Upload articles of association (contrato social)"
},
"KycUploadEireliIncorporation": {
"type": "object",
"required": [
"evidence_type",
"requirement_id",
"attachment_type",
"file"
],
"properties": {
"evidence_type": {
"type": "string",
"description": "Evidence type to submit",
"const": "eireli_incorporation_statement"
},
"requirement_id": {
"type": "string",
"description": "EIRELI incorporation statement requirement identifier",
"pattern": "^eireli_incorporation_statement_.+$",
"example": "eireli_incorporation_statement_001XXXXXXXXXXXXXXX"
},
"attachment_type": {
"type": "string",
"description": "Attachment type",
"const": "file"
},
"file": {
"type": "string",
"format": "binary",
"description": "Binary file upload (PDF, JPEG, PNG)"
}
},
"description": "Upload an EIRELI incorporation statement (ato constitutivo)"
},
"KycUploadEmail": {
"type": "object",
"required": [
"evidence_type",
"requirement_id",
"attachment_type",
"value"
],
"properties": {
"evidence_type": {
"type": "string",
"description": "Evidence type to submit",
"const": "email"
},
"requirement_id": {
"type": "string",
"description": "Format: `email_{subject_id}`",
"example": "email_003XXXXXXXXXXXXXXX"
},
"attachment_type": {
"type": "string",
"description": "Attachment type",
"const": "email"
},
"value": {
"type": "string",
"format": "email",
"description": "Email address for the co-owner (used for CCB digital signature)",
"example": "co-owner@example.com"
}
},
"description": "Submit a co-owner email address for CCB signature"
},
"BiometricsSession": {
"description": "Biometrics session for identity validation",
"type": "object",
"required": [
"session_url",
"expires_at"
],
"properties": {
"session_url": {
"type": "string",
"format": "uri",
"description": "URL for the partner to embed in their flow (webview or redirect)",
"example": "https://biometrics.dinie.com.br/session/..."
},
"expires_at": {
"type": "integer",
"format": "int64",
"example": 1772748000,
"description": "Expiration timestamp (Unix epoch seconds)"
}
}
},
"CreditOffer": {
"description": "Pre-approved credit offer for a customer",
"oneOf": [
{
"$ref": "#/components/schemas/FixedInstallmentCreditOffer"
},
{
"$ref": "#/components/schemas/RangeInstallmentCreditOffer"
}
]
},
"CreditOfferBase": {
"description": "Campos comuns a toda oferta de crédito",
"type": "object",
"required": [
"id",
"customer_id",
"status",
"approved_amount",
"min_amount",
"monthly_interest_rate",
"valid_until",
"created_at",
"updated_at"
],
"properties": {
"id": {
"$ref": "#/components/schemas/CreditOfferId",
"description": "Unique credit offer identifier"
},
"customer_id": {
"$ref": "#/components/schemas/CustomerId",
"description": "Customer associated with this offer"
},
"external_id": {
"type": "string",
"description": "Partner reference ID for the customer this offer belongs to"
},
"status": {
"type": "string",
"enum": [
"available",
"accepted",
"expired"
],
"x-enumDescriptions": {
"available": "Offer is active and can be accepted by the customer",
"accepted": "Customer accepted the offer and a loan was created",
"expired": "Offer passed the valid_until date without being accepted"
},
"description": "`available`, `accepted` or `expired`"
},
"approved_amount": {
"$ref": "#/components/schemas/Money",
"description": "Maximum approved withdrawal amount"
},
"min_amount": {
"type": "number",
"format": "double",
"description": "Minimum withdrawal amount",
"example": 200
},
"monthly_interest_rate": {
"type": "number",
"format": "double",
"description": "Monthly interest rate percentage",
"example": 3.5
},
"due_date_rule": {
"type": [
"string",
"null"
],
"description": "Due date rule for installments. Pending Core implementation."
},
"valid_until": {
"type": "integer",
"format": "int64",
"example": 1775253599,
"description": "Offer expiration timestamp (Unix epoch seconds)"
},
"created_at": {
"type": "integer",
"format": "int64",
"description": "When this resource was created (Unix epoch seconds)"
},
"updated_at": {
"type": "integer",
"format": "int64",
"description": "When this resource was last modified (Unix epoch seconds)"
}
}
},
"FixedInstallmentCreditOffer": {
"description": "Credit offer with a fixed number of installments",
"allOf": [
{
"$ref": "#/components/schemas/CreditOfferBase"
},
{
"type": "object",
"required": [
"installments"
],
"properties": {
"installments": {
"type": "integer",
"description": "Number of installments for a fixed-term offer",
"example": 12
}
}
}
],
"example": {
"id": "co_550e8400e29b41d4a716446655440000",
"customer_id": "cust_550e8400e29b41d4a716446655440000",
"external_id": "partner-ref-123",
"status": "available",
"approved_amount": 50000,
"min_amount": 200,
"monthly_interest_rate": 3.5,
"installments": 12,
"due_date_rule": null,
"valid_until": 1775253599,
"created_at": 1772791200,
"updated_at": 1772877600
}
},
"RangeInstallmentCreditOffer": {
"description": "Credit offer with a customer-selectable installment range",
"allOf": [
{
"$ref": "#/components/schemas/CreditOfferBase"
},
{
"type": "object",
"required": [
"min_installments",
"max_installments"
],
"properties": {
"min_installments": {
"type": "integer",
"description": "Minimum number of installments the customer may select",
"example": 3
},
"max_installments": {
"type": "integer",
"description": "Maximum number of installments the customer may select",
"example": 12
}
}
}
],
"example": {
"id": "co_660f9500f30c52e5b827557766551111",
"customer_id": "cust_550e8400e29b41d4a716446655440000",
"external_id": "partner-ref-456",
"status": "available",
"approved_amount": 50000,
"min_amount": 200,
"monthly_interest_rate": 3.5,
"min_installments": 3,
"max_installments": 12,
"due_date_rule": null,
"valid_until": 1775253599,
"created_at": 1772791200,
"updated_at": 1772877600
}
},
"CreateSimulationRequest": {
"description": "Parameters to create a loan simulation",
"type": "object",
"required": [
"requested_amount",
"installment_count"
],
"properties": {
"requested_amount": {
"type": "number",
"description": "Requested loan amount",
"example": 25000
},
"installment_count": {
"type": "integer",
"minimum": 1,
"description": "Number of installments for the simulation",
"example": 12
}
}
},
"Simulation": {
"description": "Loan simulation result with calculated values",
"type": "object",
"required": [
"id",
"credit_offer_id",
"requested_amount",
"principal_amount",
"interest_amount",
"iof_amount",
"total_amount",
"monthly_interest_rate",
"annual_interest_rate",
"monthly_cet_rate",
"annual_cet_rate",
"installment_count",
"installment_amount",
"fee_amount",
"first_due_date",
"created_at"
],
"properties": {
"id": {
"$ref": "#/components/schemas/SimulationId",
"description": "Unique simulation identifier"
},
"credit_offer_id": {
"$ref": "#/components/schemas/CreditOfferId",
"description": "Credit offer used in this simulation"
},
"requested_amount": {
"type": "number",
"format": "double",
"description": "Amount requested by the partner",
"example": 25000
},
"principal_amount": {
"type": "number",
"format": "double",
"description": "Principal amount (requested amount + financed fees)",
"example": 29375
},
"interest_amount": {
"type": "number",
"format": "double",
"description": "Total interest amount",
"example": 2614.36
},
"iof_amount": {
"type": "number",
"format": "double",
"description": "IOF tax amount",
"example": 1875
},
"fee_amount": {
"type": "number",
"format": "double",
"description": "Registration fee amount",
"example": 2500
},
"total_amount": {
"type": "number",
"format": "double",
"description": "Total amount (sum of all installments)",
"example": 31989.36
},
"monthly_interest_rate": {
"type": "number",
"format": "double",
"description": "Monthly interest rate (percentage)",
"example": 3.5
},
"annual_interest_rate": {
"type": "number",
"format": "double",
"description": "Annual interest rate (percentage, compounded from monthly)",
"example": 51.11
},
"monthly_cet_rate": {
"type": "number",
"format": "double",
"description": "Monthly total effective cost (percentage)",
"example": 2
},
"annual_cet_rate": {
"type": "number",
"format": "double",
"description": "Annual total effective cost (percentage)",
"example": 233.18
},
"installment_count": {
"type": "integer",
"description": "Number of installments",
"example": 4
},
"installment_amount": {
"type": "number",
"format": "double",
"description": "Installment amount",
"example": 7997.34
},
"first_due_date": {
"type": "string",
"description": "ISO 8601 · date\n\nFirst installment due date",
"example": "2026-04-03"
},
"created_at": {
"type": "integer",
"format": "int64",
"description": "When this resource was created (Unix epoch seconds)"
}
}
},
"CreateLoanRequest": {
"description": "Parameters to create a loan from a credit offer",
"type": "object",
"required": [
"credit_offer_id",
"simulation_id",
"installment_count",
"installment_amount",
"first_due_date"
],
"properties": {
"credit_offer_id": {
"$ref": "#/components/schemas/CreditOfferId",
"description": "Credit offer to accept"
},
"simulation_id": {
"$ref": "#/components/schemas/SimulationId",
"description": "Simulation used for this loan"
},
"installment_count": {
"type": "integer",
"minimum": 1,
"description": "Number of installments",
"example": 4
},
"installment_amount": {
"type": "number",
"description": "Installment amount",
"example": 7997.34
},
"first_due_date": {
"type": "string",
"description": "ISO 8601 · date\n\nFirst installment due date",
"example": "2026-04-03"
}
}
},
"Loan": {
"description": "Full representation of a loan",
"type": "object",
"required": [
"id",
"credit_offer_id",
"customer_id",
"simulation_id",
"status",
"requested_amount",
"principal_amount",
"iof_amount",
"monthly_interest_rate",
"annual_interest_rate",
"monthly_cet_rate",
"annual_cet_rate",
"total_amount",
"installment_count",
"installment_amount",
"first_due_date",
"ccb_number",
"disbursement_method",
"signing_url",
"created_at",
"updated_at"
],
"properties": {
"id": {
"$ref": "#/components/schemas/LoanId",
"description": "Unique loan identifier"
},
"credit_offer_id": {
"$ref": "#/components/schemas/CreditOfferId",
"description": "Credit offer that originated this loan"
},
"customer_id": {
"$ref": "#/components/schemas/CustomerId",
"description": "Customer associated with this loan"
},
"simulation_id": {
"$ref": "#/components/schemas/SimulationId",
"description": "Simulation used to create this loan"
},
"status": {
"type": "string",
"enum": [
"awaiting_signatures",
"processing",
"active",
"finished",
"cancelled",
"error"
],
"x-enumDescriptions": {
"awaiting_signatures": "CCB contract generated, awaiting customer signature",
"processing": "All signatures collected, disbursement in progress",
"active": "Loan disbursed, installments are being collected",
"finished": "All installments paid, loan completed",
"cancelled": "Loan cancelled before disbursement",
"error": "An error occurred during processing"
},
"description": "`awaiting_signatures`, `processing`, `active`, `finished`, `cancelled`, `error`"
},
"requested_amount": {
"$ref": "#/components/schemas/Money",
"description": "Amount requested by the customer"
},
"principal_amount": {
"type": [
"number",
"null"
],
"format": "double",
"description": "Principal amount (requested + financed fees). Null until calculated."
},
"iof_amount": {
"type": [
"number",
"null"
],
"format": "double",
"description": "IOF tax amount"
},
"monthly_interest_rate": {
"type": "number",
"format": "double",
"description": "Monthly interest rate (percentage)"
},
"annual_interest_rate": {
"type": "number",
"format": "double",
"description": "Annual interest rate (percentage, compounded from monthly)"
},
"monthly_cet_rate": {
"type": "number",
"format": "double",
"description": "Monthly total effective cost (percentage)"
},
"annual_cet_rate": {
"type": "number",
"format": "double",
"description": "Annual total effective cost (percentage)"
},
"total_amount": {
"$ref": "#/components/schemas/Money",
"description": "Sum of all installment payments"
},
"installment_count": {
"type": "integer",
"description": "Number of installments"
},
"installment_amount": {
"type": "number",
"format": "double",
"description": "Installment amount",
"example": 7997.34
},
"first_due_date": {
"type": "string",
"description": "ISO 8601 · date\n\nFirst installment due date",
"example": "2026-04-03"
},
"ccb_number": {
"type": [
"string",
"null"
],
"description": "CCB contract number. Null until the contract is generated."
},
"disbursement_method": {
"type": [
"string",
"null"
],
"description": "Disbursement method (e.g., `pix`). Null until disbursement."
},
"signing_url": {
"type": [
"string",
"null"
],
"format": "uri",
"description": "ClickSign widget URL. Present only during `awaiting_signatures` status."
},
"created_at": {
"type": "integer",
"format": "int64",
"description": "When this resource was created (Unix epoch seconds)"
},
"updated_at": {
"type": "integer",
"format": "int64",
"description": "When this resource was last modified (Unix epoch seconds)"
}
}
},
"Transaction": {
"description": "Loan installment with amounts and payment status",
"type": "object",
"required": [
"id",
"loan_id",
"type",
"status",
"due_date",
"amount_due",
"amount_paid",
"amount_remaining",
"principal",
"interest",
"fees",
"days_overdue",
"paid_at",
"created_at",
"updated_at"
],
"properties": {
"id": {
"$ref": "#/components/schemas/TransactionId",
"description": "Unique transaction identifier"
},
"loan_id": {
"$ref": "#/components/schemas/LoanId",
"description": "Associated loan identifier"
},
"type": {
"type": "string",
"const": "installment",
"description": "Always `installment`"
},
"status": {
"type": "string",
"enum": [
"pending",
"paid",
"overdue",
"partially_paid"
],
"x-enumDescriptions": {
"pending": "Payment not yet due or awaiting payment",
"paid": "Full payment received",
"overdue": "Payment overdue without full settlement",
"partially_paid": "Partial payment received"
},
"description": "`pending`, `paid`, `overdue` or `partially_paid`"
},
"due_date": {
"type": "string",
"example": "2026-04-03",
"description": "ISO 8601 · date\n\nInstallment due date"
},
"amount_due": {
"$ref": "#/components/schemas/Money",
"description": "Total amount due for this installment"
},
"amount_paid": {
"$ref": "#/components/schemas/Money",
"description": "Amount already paid for this installment"
},
"amount_remaining": {
"$ref": "#/components/schemas/Money",
"description": "Remaining amount to pay for this installment"
},
"principal": {
"$ref": "#/components/schemas/Money",
"description": "Principal portion"
},
"interest": {
"$ref": "#/components/schemas/Money",
"description": "Interest portion"
},
"fees": {
"$ref": "#/components/schemas/Money",
"description": "Fees and charges portion"
},
"days_overdue": {
"type": "integer",
"minimum": 0,
"description": "Days overdue (0 if current)"
},
"paid_at": {
"type": [
"integer",
"null"
],
"format": "int64",
"description": "When payment was received (Unix epoch seconds)"
},
"created_at": {
"type": "integer",
"format": "int64",
"description": "When this resource was created (Unix epoch seconds)"
},
"updated_at": {
"type": "integer",
"format": "int64",
"description": "When this resource was last modified (Unix epoch seconds)"
}
}
},
"CreateWebhookEndpointRequest": {
"description": "Parameters to create a new webhook endpoint",
"type": "object",
"required": [
"url"
],
"properties": {
"url": {
"type": "string",
"format": "uri",
"description": "HTTPS URL to receive webhook deliveries",
"example": "https://partner.example.com/webhooks/dinie"
},
"events": {
"type": "array",
"items": {
"type": "string"
},
"description": "Event types to subscribe to. Supports wildcards `*` (e.g., `loan.*`). Empty or omitted = all events.",
"example": [
"customer.active",
"credit_offer.available",
"loan.*"
]
},
"description": {
"type": "string",
"description": "Optional human-readable label",
"example": "Production webhook"
}
}
},
"UpdateWebhookEndpointRequest": {
"description": "Parameters to update a webhook endpoint",
"type": "object",
"properties": {
"url": {
"type": "string",
"format": "uri",
"description": "HTTPS URL to receive webhook deliveries"
},
"events": {
"type": "array",
"items": {
"type": "string"
},
"description": "Subscribed event types, supports wildcards `*`"
},
"description": {
"type": "string",
"description": "Optional human-readable description for this endpoint"
},
"status": {
"type": "string",
"description": "Enable or disable the endpoint",
"enum": [
"active",
"disabled"
],
"x-enumDescriptions": {
"active": "Endpoint active, receiving webhooks",
"disabled": "Endpoint paused, no webhooks will be sent"
}
}
}
},
"WebhookEndpoint": {
"description": "Endpoint configured to receive event notifications",
"type": "object",
"required": [
"id",
"url",
"events",
"description",
"status",
"created_at",
"updated_at"
],
"properties": {
"id": {
"$ref": "#/components/schemas/WebhookEndpointId",
"description": "Unique webhook endpoint identifier"
},
"url": {
"type": "string",
"format": "uri",
"description": "Delivery URL (HTTPS only)"
},
"events": {
"type": "array",
"items": {
"type": "string"
},
"description": "Event types to subscribe to (empty = all events)"
},
"description": {
"type": "string",
"description": "Human-readable description for this endpoint"
},
"status": {
"type": "string",
"description": "`active` or `disabled`",
"enum": [
"active",
"disabled"
],
"x-enumDescriptions": {
"active": "Endpoint is receiving webhook deliveries",
"disabled": "Endpoint is paused; no webhooks will be sent"
}
},
"created_at": {
"type": "integer",
"format": "int64",
"description": "When this resource was created (Unix epoch seconds)"
},
"updated_at": {
"type": "integer",
"format": "int64",
"description": "When this resource was last modified (Unix epoch seconds)"
}
}
},
"WebhookEndpointWithSecret": {
"description": "Returned only on creation. The `secret` cannot be retrieved again.",
"allOf": [
{
"$ref": "#/components/schemas/WebhookEndpoint"
},
{
"type": "object",
"required": [
"secret"
],
"properties": {
"secret": {
"type": "string",
"description": "HMAC signing secret (prefix `whsec_`). Store securely — displayed only once.",
"example": "whsec_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
}
}
}
]
},
"WebhookDelivery": {
"description": "Record of a webhook delivery attempt",
"type": "object",
"required": [
"id",
"event_type",
"status",
"attempt_count",
"created_at"
],
"properties": {
"id": {
"$ref": "#/components/schemas/WebhookDeliveryId"
},
"event_type": {
"type": "string",
"description": "Event type for this delivery"
},
"status": {
"type": "string",
"enum": [
"pending",
"delivered",
"failed"
],
"description": "Delivery status",
"x-enumDescriptions": {
"pending": "Awaiting delivery",
"delivered": "Successfully delivered",
"failed": "Delivery failed"
}
},
"response_status": {
"type": [
"integer",
"null"
],
"description": "HTTP status code from the last delivery attempt (`null` if none)"
},
"attempt_count": {
"type": "integer",
"description": "Number of attempts already made"
},
"delivered_at": {
"type": [
"string",
"null"
],
"description": "ISO 8601 · date-time\n\nWhen the delivery succeeded (`null` if not yet delivered)"
},
"failed_at": {
"type": [
"string",
"null"
],
"description": "ISO 8601 · date-time\n\nWhen the delivery last failed (`null` if it has not failed)"
},
"created_at": {
"type": "string",
"description": "ISO 8601 · date-time\n\nWhen this delivery was created"
}
}
},
"WebhookSecretRotation": {
"description": "Result of the webhook signing secret rotation",
"type": "object",
"required": [
"id",
"secret",
"previous_secret_expires_at"
],
"properties": {
"id": {
"$ref": "#/components/schemas/WebhookEndpointId",
"description": "Unique webhook endpoint identifier"
},
"secret": {
"type": "string",
"description": "New HMAC signing secret",
"example": "whsec_yyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyy"
},
"previous_secret_expires_at": {
"type": "integer",
"format": "int64",
"description": "When the old secret stops being included in signatures (Unix epoch seconds)"
}
}
},
"EventId": {
"description": "Unique webhook event identifier",
"type": "string",
"pattern": "^evt_[0-9a-f]{32}$",
"example": "evt_550e8400e29b41d4a716446655440000"
},
"WebhookEventBase": {
"type": "object",
"required": [
"id",
"type",
"api_version",
"created_at",
"delivery_id",
"timestamp"
],
"description": "Standard Webhooks envelope delivered with `webhook-id`, `webhook-timestamp`, `webhook-signature` headers.",
"properties": {
"id": {
"$ref": "#/components/schemas/EventId",
"description": "Unique event identifier"
},
"type": {
"type": "string",
"description": "Event type identifier"
},
"api_version": {
"type": "string",
"description": "API version used to generate this event",
"example": "2026-03-01"
},
"created_at": {
"type": "integer",
"format": "int64",
"description": "When the event was created (Unix epoch seconds)"
},
"delivery_id": {
"type": "string",
"description": "Unique delivery attempt identifier"
},
"timestamp": {
"type": "integer",
"format": "int64",
"description": "When the event occurred (Unix epoch seconds)"
}
}
},
"WebhookEvent_CustomerCreated": {
"description": "Fires after co-owner enrichment completes and KYC requirements are populated. Customer is at `pending_kyc` status.",
"allOf": [
{
"$ref": "#/components/schemas/WebhookEventBase"
},
{
"type": "object",
"properties": {
"type": {
"type": "string",
"description": "Event type",
"const": "customer.created"
},
"data": {
"type": "object",
"description": "Created customer data",
"required": [
"id",
"external_id",
"name",
"email",
"phone",
"cpf",
"trading_name",
"status",
"kyc"
],
"properties": {
"id": {
"$ref": "#/components/schemas/CustomerId"
},
"external_id": {
"type": [
"string",
"null"
]
},
"name": {
"type": "string"
},
"email": {
"type": "string"
},
"phone": {
"type": "string"
},
"cpf": {
"type": "string"
},
"cnpj": {
"type": [
"string",
"null"
]
},
"trading_name": {
"type": "string"
},
"status": {
"type": "string",
"const": "pending_kyc"
},
"kyc": {
"type": "array",
"description": "KYC requirements populated after enrichment",
"items": {
"$ref": "#/components/schemas/KycRequirement"
}
}
}
}
}
}
]
},
"WebhookEvent_CustomerStatus": {
"description": "Used for `customer.under_review` and `customer.active` events.",
"allOf": [
{
"$ref": "#/components/schemas/WebhookEventBase"
},
{
"type": "object",
"properties": {
"type": {
"type": "string",
"description": "Event type",
"enum": [
"customer.under_review",
"customer.active"
],
"x-enumDescriptions": {
"customer.under_review": "Customer under verification review",
"customer.active": "Customer approved and active"
}
},
"data": {
"type": "object",
"description": "Customer status change data",
"required": [
"id",
"external_id",
"status"
],
"properties": {
"id": {
"$ref": "#/components/schemas/CustomerId"
},
"external_id": {
"type": [
"string",
"null"
]
},
"status": {
"type": "string",
"enum": [
"under_review",
"active"
]
}
}
}
}
}
]
},
"WebhookEvent_CustomerDenied": {
"description": "Fires when the customer is permanently blocked (fraud, closed company, or other terminal condition).",
"allOf": [
{
"$ref": "#/components/schemas/WebhookEventBase"
},
{
"type": "object",
"properties": {
"type": {
"type": "string",
"description": "Event type",
"const": "customer.denied"
},
"data": {
"type": "object",
"description": "Denied customer data",
"required": [
"id",
"external_id",
"name",
"email",
"phone",
"cpf",
"status"
],
"properties": {
"id": {
"$ref": "#/components/schemas/CustomerId"
},
"external_id": {
"type": [
"string",
"null"
]
},
"name": {
"type": "string"
},
"email": {
"type": "string"
},
"phone": {
"type": "string"
},
"cpf": {
"type": "string"
},
"cnpj": {
"type": [
"string",
"null"
]
},
"status": {
"type": "string",
"const": "denied"
}
}
}
}
}
]
},
"WebhookEvent_CustomerKycUpdated": {
"allOf": [
{
"$ref": "#/components/schemas/WebhookEventBase"
},
{
"type": "object",
"properties": {
"type": {
"type": "string",
"description": "Event type",
"const": "customer.kyc_updated"
},
"data": {
"type": "object",
"description": "Customer KYC update data",
"required": [
"id",
"external_id",
"status",
"kyc"
],
"properties": {
"id": {
"$ref": "#/components/schemas/CustomerId"
},
"external_id": {
"type": [
"string",
"null"
]
},
"status": {
"type": "string",
"enum": [
"pending_kyc",
"under_review",
"active"
]
},
"kyc": {
"type": "array",
"description": "Full current state of all KYC requirements",
"items": {
"$ref": "#/components/schemas/KycRequirement"
}
}
}
}
}
}
],
"description": "Fires when any KYC requirement changes status"
},
"WebhookEvent_CreditOffer": {
"description": "Used for `credit_offer.available` and `credit_offer.expired` events.",
"allOf": [
{
"$ref": "#/components/schemas/WebhookEventBase"
},
{
"type": "object",
"properties": {
"type": {
"type": "string",
"description": "Event type",
"enum": [
"credit_offer.available",
"credit_offer.expired"
],
"x-enumDescriptions": {
"credit_offer.available": "New credit offer available for withdrawal",
"credit_offer.expired": "Credit offer expired or replaced"
}
},
"data": {
"type": "object",
"description": "Credit offer data",
"required": [
"id",
"customer_id",
"external_id",
"status",
"approved_amount",
"min_amount",
"monthly_interest_rate",
"installments",
"valid_until"
],
"properties": {
"id": {
"$ref": "#/components/schemas/CreditOfferId"
},
"customer_id": {
"$ref": "#/components/schemas/CustomerId"
},
"external_id": {
"type": [
"string",
"null"
],
"description": "Partner external reference for this customer",
"example": "partner-ref-123"
},
"status": {
"type": "string",
"enum": [
"available",
"expired"
]
},
"approved_amount": {
"$ref": "#/components/schemas/Money"
},
"min_amount": {
"type": "number",
"format": "double",
"description": "Minimum withdrawal amount"
},
"monthly_interest_rate": {
"type": "number",
"format": "double",
"description": "Monthly interest rate percentage"
},
"installments": {
"type": "integer",
"description": "Number of installments"
},
"due_date_rule": {
"type": [
"string",
"null"
],
"description": "Due date rule for installments. Pending Core implementation."
},
"valid_until": {
"type": "integer",
"format": "int64",
"description": "Offer expiration timestamp (Unix epoch seconds)"
}
}
}
}
}
]
},
"WebhookEvent_LoanCreated": {
"description": "Fires when the loan is created with CCB generated synchronously. Loan starts in `awaiting_signatures` status.",
"allOf": [
{
"$ref": "#/components/schemas/WebhookEventBase"
},
{
"type": "object",
"properties": {
"type": {
"type": "string",
"description": "Event type",
"const": "loan.created"
},
"data": {
"type": "object",
"description": "Created loan data",
"required": [
"id",
"credit_offer_id",
"customer_id",
"status",
"requested_amount",
"installment_count",
"signing_url"
],
"properties": {
"id": {
"$ref": "#/components/schemas/LoanId"
},
"credit_offer_id": {
"$ref": "#/components/schemas/CreditOfferId"
},
"customer_id": {
"$ref": "#/components/schemas/CustomerId"
},
"status": {
"type": "string",
"const": "awaiting_signatures"
},
"requested_amount": {
"$ref": "#/components/schemas/Money"
},
"installment_count": {
"type": "integer"
},
"signing_url": {
"type": "string",
"format": "uri",
"description": "ClickSign widget URL for customer signing"
}
}
}
}
}
]
},
"WebhookEvent_LoanSignatureReceived": {
"description": "Fires each time an individual signer completes their signature on the CCB contract.",
"allOf": [
{
"$ref": "#/components/schemas/WebhookEventBase"
},
{
"type": "object",
"properties": {
"type": {
"type": "string",
"description": "Event type",
"const": "loan.signature_received"
},
"data": {
"type": "object",
"description": "Signature received data",
"required": [
"id",
"status",
"signer",
"signatures_received",
"signatures_required"
],
"properties": {
"id": {
"$ref": "#/components/schemas/LoanId"
},
"status": {
"type": "string",
"const": "awaiting_signatures"
},
"signer": {
"type": "object",
"required": [
"name",
"cpf",
"signed_at"
],
"properties": {
"name": {
"type": "string",
"description": "Signer name"
},
"cpf": {
"type": "string",
"description": "Signer CPF"
},
"signed_at": {
"type": "integer",
"format": "int64",
"description": "When the signature was captured (Unix epoch seconds)"
}
}
},
"signatures_received": {
"type": "integer",
"description": "Number of signatures collected so far"
},
"signatures_required": {
"type": "integer",
"description": "Total number of signatures required"
}
}
}
}
}
]
},
"WebhookEvent_LoanProcessing": {
"description": "Fires when all required signatures are collected and disbursement is in progress.",
"allOf": [
{
"$ref": "#/components/schemas/WebhookEventBase"
},
{
"type": "object",
"properties": {
"type": {
"type": "string",
"description": "Event type",
"const": "loan.processing"
},
"data": {
"type": "object",
"description": "Loan processing data",
"required": [
"id",
"credit_offer_id",
"customer_id",
"status",
"ccb_number",
"disbursement_method"
],
"properties": {
"id": {
"$ref": "#/components/schemas/LoanId"
},
"credit_offer_id": {
"$ref": "#/components/schemas/CreditOfferId"
},
"customer_id": {
"$ref": "#/components/schemas/CustomerId"
},
"status": {
"type": "string",
"const": "processing"
},
"ccb_number": {
"type": "string",
"description": "CCB contract number"
},
"disbursement_method": {
"type": "string",
"description": "Disbursement method (e.g., `pix`)"
}
}
}
}
}
]
},
"WebhookEvent_LoanActive": {
"allOf": [
{
"$ref": "#/components/schemas/WebhookEventBase"
},
{
"type": "object",
"properties": {
"type": {
"type": "string",
"description": "Event type",
"const": "loan.active"
},
"data": {
"type": "object",
"description": "Active loan data",
"required": [
"id",
"status",
"requested_amount",
"principal_amount"
],
"properties": {
"id": {
"$ref": "#/components/schemas/LoanId"
},
"status": {
"type": "string",
"const": "active"
},
"requested_amount": {
"$ref": "#/components/schemas/Money"
},
"principal_amount": {
"$ref": "#/components/schemas/Money"
}
}
}
}
}
],
"description": "Fires when the disbursement is confirmed and the loan enters the repayment phase."
},
"WebhookEvent_LoanPaymentReceived": {
"allOf": [
{
"$ref": "#/components/schemas/WebhookEventBase"
},
{
"type": "object",
"properties": {
"type": {
"type": "string",
"description": "Event type",
"const": "loan.payment_received"
},
"data": {
"type": "object",
"description": "Payment received data",
"required": [
"id",
"status",
"payment"
],
"properties": {
"id": {
"$ref": "#/components/schemas/LoanId"
},
"status": {
"type": "string",
"const": "active"
},
"payment": {
"type": "object",
"required": [
"amount",
"paid_at",
"installment_number"
],
"properties": {
"amount": {
"$ref": "#/components/schemas/Money",
"description": "Payment amount received"
},
"paid_at": {
"type": "integer",
"format": "int64",
"description": "When payment was received (Unix epoch seconds)"
},
"installment_number": {
"type": "integer",
"description": "Installment number paid"
}
}
}
}
}
}
}
],
"description": "Fires when an installment payment is recorded for the loan."
},
"WebhookEvent_LoanStatus": {
"description": "Used for `loan.finished`, `loan.cancelled`, and `loan.error` events.",
"allOf": [
{
"$ref": "#/components/schemas/WebhookEventBase"
},
{
"type": "object",
"properties": {
"type": {
"type": "string",
"description": "Event type",
"enum": [
"loan.finished",
"loan.cancelled",
"loan.error"
],
"x-enumDescriptions": {
"loan.finished": "Loan fully paid off",
"loan.cancelled": "Loan cancelled before disbursement",
"loan.error": "Disbursement or processing error"
}
},
"data": {
"type": "object",
"description": "Loan status change data",
"required": [
"id",
"status"
],
"properties": {
"id": {
"$ref": "#/components/schemas/LoanId"
},
"status": {
"type": "string",
"enum": [
"finished",
"cancelled",
"error"
]
},
"error": {
"type": "object",
"description": "Error details. Present only for `loan.error` events",
"required": [
"code",
"message"
],
"properties": {
"code": {
"type": "string",
"description": "Machine-readable error code"
},
"message": {
"type": "string",
"description": "Human-readable error description"
}
}
}
}
}
}
}
]
}
}
}
}