Guides

Quick Start

Environments

EnvironmentBase URL
Sandboxhttps://api-bnpl.sandbox.geru.com.br/
Productionhttps://***

Authentication

All API requests require authentication via Bearer Token or API Key:

# Bearer Token
Authorization: Bearer <your-token>

# OR API Key
X-API-Key: <your-api-key>

Application State Machine

An application goes through the following states during its lifecycle:

#StatusDescription
1APPLICATION_CREATEDInitial state after creating the application
2APPLICATION_APPROVEDCredit model approved the application (has offers and available limit)
3APPLICATION_DECLINEDCredit model declined the application (no offers or limit available)
4APPLICATION_COMPLETEDCustomer selected an offer and application was updated
5CONTRACT_SIGNEDCustomer signed the contract with OTP
6APPROVEDAnti-fraud review approved the application
7DECLINEDAnti-fraud review declined the application
8SUBMITTED_TO_FIApplication submitted to financial institution
9FUNDEDLoan disbursed successfully
10CANCELLEDApplication was cancelled
11FUNDING_FAILEDFunding process failed

Step 1: Check Customer Eligibility

Before starting the application, verify if the customer is eligible for BNPL:

POST /fastqualify
{
  "cpf": "78011189603"
}

Response:

{
  "status": "Eligible",
  "person_id": "19474477-dc20-4b0a-9dfa-b3d3012c5401"
}
📘

Note

If the customer is Not Eligible, they cannot proceed with the BNPL application. Save the person_id - you'll need it for subsequent API calls.


Step 2: Create the Application

Create a credit application to run the credit policy and get available offers:

POST /application/create

Request:

{
  "cpf": "111.111.111-11",
  "order_reference": "order_reference_001",
  "cart": [
    { "item": "Product A", "value": 300.00 },
    { "item": "Product B", "value": 200.00 }
  ],
  "shipping": {
    "value": 15.00,
    "zip": "01310100"
  }
}
📝

Note: The order_reference, cart, and shipping fields are optional at this stage but recommended for better offer calculation.

Response:

{
  "application_id": "6ffd813a-1e88-4a4a-a892-758ca310e607",
  "max_total_value": 4726.28,
  "available_limit": 4726.28,
  "max_installment_value": 1500.0,
  "min_installment_value": 20.00,
  "offer_parameters_list": [
    {
      "term": 3,
      "monthly_interest_rate": 0.0445,
      "amount": 25.50,
      "upfront_installment": 10.50,
      "additional_iof": 0.14,
      "annual_cet": 145.08,
      "assignment_amount": 36.21,
      "base_iof": 0.1,
      "cet": 7.76,
      "total_interest": 52.17,
      "total_iof": 0.24,
      "first_due_date": "2024-09-25",
      "disbursement_date": "2024-09-06",
      "fees": [
        {
          "amount": 0.0,
          "fee_amount": 0.0,
          "amount_type": "absolute",
          "fee_type": "tac",
          "type": "external"
        }
      ],
      "installments": [
        {
          "installment_number": 1,
          "due_date": "2024-09-25",
          "amount": 10.50,
          "due_principal": 36.14,
          "due_interest": 0.0,
          "tax_amount": 0.14,
          "principal_amortization_amount": 10.36
        },
        {
          "installment_number": 2,
          "due_date": "2024-10-25",
          "amount": 25.50,
          "due_principal": 36.14,
          "due_interest": 18.07,
          "tax_amount": 0.05,
          "principal_amortization_amount": 7.38
        },
        {
          "installment_number": 3,
          "due_date": "2024-11-25",
          "amount": 25.50,
          "due_principal": 36.14,
          "due_interest": 17.02,
          "tax_amount": 0.05,
          "principal_amortization_amount": 8.43
        }
      ]
    },
    {
      "term": 4,
      "monthly_interest_rate": 0.0449,
      "amount": 19.50,
      "upfront_installment": 10.50,
      "additional_iof": 0.14,
      "annual_cet": 145.08,
      "assignment_amount": 36.21,
      "base_iof": 0.1,
      "cet": 7.76,
      "total_interest": 45.83,
      "total_iof": 0.24,
      "first_due_date": "2024-09-25",
      "disbursement_date": "2024-09-06",
      "fees": [
        {
          "amount": 0.0,
          "fee_amount": 0.0,
          "amount_type": "absolute",
          "fee_type": "tac",
          "type": "external"
        }
      ],
      "installments": [
        {
          "installment_number": 1,
          "due_date": "2024-09-25",
          "amount": 10.50,
          "due_principal": 36.14,
          "due_interest": 0.0,
          "tax_amount": 0.14,
          "principal_amortization_amount": 10.36
        },
        {
          "installment_number": 2,
          "due_date": "2024-10-25",
          "amount": 19.50,
          "due_principal": 36.14,
          "due_interest": 15.85,
          "tax_amount": 0.05,
          "principal_amortization_amount": 3.60
        },
        {
          "installment_number": 3,
          "due_date": "2024-11-25",
          "amount": 19.50,
          "due_principal": 36.14,
          "due_interest": 14.99,
          "tax_amount": 0.03,
          "principal_amortization_amount": 4.48
        },
        {
          "installment_number": 4,
          "due_date": "2024-12-25",
          "amount": 19.50,
          "due_principal": 36.14,
          "due_interest": 14.99,
          "tax_amount": 0.02,
          "principal_amortization_amount": 4.49
        }
      ]
    },
    {
      "term": 5,
      "monthly_interest_rate": 0.0449,
      "amount": 10.50,
      "upfront_installment": 0.00,
      "additional_iof": 0.14,
      "annual_cet": 145.08,
      "assignment_amount": 36.21,
      "base_iof": 0.1,
      "cet": 7.76,
      "total_interest": 39.45,
      "total_iof": 0.24,
      "first_due_date": "2024-09-25",
      "disbursement_date": "2024-09-06",
      "fees": [
        {
          "amount": 0.0,
          "fee_amount": 0.0,
          "amount_type": "absolute",
          "fee_type": "tac",
          "type": "external"
        }
      ],
      "installments": [
        {
          "installment_number": 1,
          "due_date": "2024-09-25",
          "amount": 10.50,
          "due_principal": 36.14,
          "due_interest": 0.0,
          "tax_amount": 0.14,
          "principal_amortization_amount": 10.36
        },
        {
          "installment_number": 2,
          "due_date": "2024-10-25",
          "amount": 10.50,
          "due_principal": 36.14,
          "due_interest": 9.87,
          "tax_amount": 0.05,
          "principal_amortization_amount": 0.58
        },
        {
          "installment_number": 3,
          "due_date": "2024-11-25",
          "amount": 10.50,
          "due_principal": 36.14,
          "due_interest": 9.85,
          "tax_amount": 0.03,
          "principal_amortization_amount": 0.62
        },
        {
          "installment_number": 4,
          "due_date": "2024-12-25",
          "amount": 10.50,
          "due_principal": 36.14,
          "due_interest": 9.83,
          "tax_amount": 0.01,
          "principal_amortization_amount": 0.66
        },
        {
          "installment_number": 5,
          "due_date": "2025-01-25",
          "amount": 10.50,
          "due_principal": 36.14,
          "due_interest": 9.90,
          "tax_amount": 0.01,
          "principal_amortization_amount": 0.59
        }
      ]
    }
  ],
  "expires_at": "2026-01-21T00:00:00-03:00"
}
📘

Available Limit

The available_limit field shows the customer's current credit limit. You can also check this in real-time using the /person/{person_id}/available-limit endpoint.

🔄

Offer Simulation

Field Descriptions:

FieldDescription
termNumber of installments
amountRegular installment amount in BRL
upfront_installmentFirst installment amount (may differ from regular installments)
cetMonthly CET (Total Effective Cost) percentage
annual_cetAnnual CET percentage
total_iofTotal IOF (Tax on Financial Operations) amount
total_interestTotal interest amount for the loan
first_due_dateDate of the first installment
disbursement_dateExpected disbursement date
feesList of fees applied to the loan
installmentsDetailed breakdown of each installment
⚠️

Important: Cart Updates

Every time the shopping cart is updated (items added/removed, quantities changed, shipping modified, coupon added - basically everything that will change the amount), you must call the createApplication endpoint again to recalculate the offers with the new amount. This ensures accurate financial simulations and compliance with regulations.

Example: Cart Update Flow

Scenario: Customer adds more items to cart after initial application

  1. Initial Application (Cart Total: R$ 515.00)
POST /application/create
{
  "person_id": "ff0024e6-d11e-4700-b7f3-b3d201624e62",
  "order_reference": "order_001",
  "cart": [
    { "item": "Product A", "value": 300.00 },
    { "item": "Product B", "value": 200.00 }
  ],
  "shipping": { "value": 15.00, "zip": "01310100" }
}

Response includes offers for R$ 515.00

  1. Customer Adds Item (New Cart Total: R$ 715.00)
POST /application/create
{
  "person_id": "ff0024e6-d11e-4700-b7f3-b3d201624e62",
  "order_reference": "order_001",
  "cart": [
    { "item": "Product A", "value": 300.00 },
    { "item": "Product B", "value": 200.00 },
    { "item": "Product C", "value": 200.00 }
  ],
  "shipping": { "value": 15.00, "zip": "01310100" }
}

Response includes recalculated offers for R$ 715.00 with updated installment amounts, IOF, and CET values

📌

Important: Always use the latest application_id from the most recent createApplication call when proceeding to the update/sign steps.

Step 3: Update with Selected Offer

Once the customer selects an offer, update the application with the purchase details:

PUT /application/{application_id}/update

Headers:

Ip-Address: <client-ip-address>
{
  "person_id": "ff0024e6-d11e-4700-b7f3-b3d201624e62",
  "amount": 500.00,
  "currency": "BRL",
  "term": 4,
  "order_reference": "order_reference",
  "cart": [
    { "item": "Product Name", "value": 500.00 }
  ],
  "shipping": {
    "value": 0,
    "zip": "01310100"
  }
}

Response includes:

  • installment_amount: Monthly payment value
  • total_interest_amount: Total interest
  • contract_string: Base64 PDF contract
  • person_phone_number: Phone where OTP was sent
⚠️

Important

An OTP code will be sent to the customer's phone for contract signing.

Step 4: Sign the Contract

Sign the contract using the OTP sent to the customer:

POST /application/{application_id}/sign

Headers:

Ip-Address: <client-ip-address>
{
  "person_id": "ff0024e6-d11e-4700-b7f3-b3d201624e62",
  "otp": "265117"
}

Response:

{
  "application_id": "6ffd813a-1e88-4a4a-a892-758ca310e607",
  "status": "CONTRACT_SIGNED",
  "signed_at": "2026-01-20T10:40:00Z"
}
💡

Anti-Fraud Integration Note

If you don't integrate Step 6 (selfie liveness validation), the anti-fraud rules will be executed automatically at this step. In that case, the response will include approved_at or declined_at fields:

Approved Example:

{
  "application_id": "6ffd813a-1e88-4a4a-a892-758ca310e607",
  "status": "APPROVED",
  "signed_at": "2026-01-20T10:40:00Z",
  "approved_at": "2026-01-20T10:40:00Z"
}

Declined Example:

{
  "application_id": "6ffd813a-1e88-4a4a-a892-758ca310e607",
  "status": "DECLINED",
  "signed_at": "2026-01-20T10:40:00Z",
  "declined_at": "2026-01-20T10:40:00Z"
}

Resend OTP (if needed)

If the customer didn't receive the OTP or if it expired:

POST /application/{application_id}/resend
{
  "person_id": "ff0024e6-d11e-4700-b7f3-b3d201624e62"
}

Response:

{
  "person_phone_number": 83991116537,
  "sent_at": "2026-01-20T10:42:00Z",
  "expires_at": "2026-01-20T10:47:00Z"
}

Step 5: Anti-Fraud Approval (Selfie Liveness Validation) - OPTIONAL

⚠️

This step is OPTIONAL

If you integrate with the selfie liveness validation, this endpoint will trigger the disbursement process. If you don't integrate this step, the anti-fraud rules will be executed automatically during Step 5 (Sign Contract), and the disbursement will be triggered from there.

Submit the application for anti-fraud review with selfie liveness validation:

🔐

QI Tech SDK Integration Requirement

Partner needs to integrate the QI Tech SDK into the front-end for selfie liveness capture.

SDK Documentation: QI Tech Face Recognition - Android Liveness

Integration Flow:

  1. Call the QI Tech SDK liveness function with the customer's CPF (required parameter)
  2. The SDK captures the customer's selfie and performs liveness detection
  3. The SDK returns a registration_key for the validated face liveness
  4. Save this registration key - you'll need it to call the approval endpoint
POST /application/{application_id}/approval

Headers:

Ip-Address: <client-ip-address>

Request:

{
  "person_id": "ff0024e6-d11e-4700-b7f3-b3d201624e62",
  "face": {
    "registration_key": "46f38cf4-07b2-4de6-93e9-64b51a68378a"
  },
  "selfie": "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNk+M9QDwADhgGAWjR9awAAAABJRU5ErkJggg=="
}

Note: The selfie field is optional and accepts a base64 encoded image for additional verification.

📝

Backend Validation Process

On the backend, we validate the liveness using the QI Tech API: Natural Person Onboarding

The registration key is used to validate the liveness based on pre-established anti-fraud rules. This includes checking for:

  • Face matching against cpf
  • Liveness detection (real person vs photo/video)
  • Fraud prevention signals
  • Identity verification

Response (Approved):

{
  "application_id": "6ffd813a-1e88-4a4a-a892-758ca310e607",
  "approved_at": "2026-01-20T10:40:00Z"
}

Response (Declined):

{
  "application_id": "6ffd813a-1e88-4a4a-a892-758ca310e607",
  "declined_at": "2026-01-20T10:40:00Z"
}

Step 6: Charge Application and Monitor Disbursement

Once the anti-fraud validation is approved (either via Step 6 or automatically during sign), charge the application to check disbursement:

POST /application/{application_id}/charge

Request:

{
  "person_id": "ff0024e6-d11e-4700-b7f3-b3d201624e62",
  "order_reference": "testCredit1"
}

Response Examples:

1. Submitted to FI (Pending):

{
  "application_id": "6ffd813a-1e88-4a4a-a892-758ca310e607",
  "status": "SUBMITTED_TO_FI",
  "updated_at": "2026-01-20T10:45:00Z",
  "order_reference": "testCredit1"
}

2. Funded (Success):

{
  "application_id": "6ffd813a-1e88-4a4a-a892-758ca310e607",
  "status": "FUNDED",
  "updated_at": "2026-01-20T10:45:00Z",
  "order_reference": "testCredit1"
}

3. Funding Failed:

{
  "application_id": "6ffd813a-1e88-4a4a-a892-758ca310e607",
  "status": "FUNDING_FAILED",
  "updated_at": "2026-01-20T10:45:00Z",
  "order_reference": "testCredit1"
}
💰

Credit Limit Update

When the status is SUBMITTED_TO_FI, the customer's credit limit is updated:

  • Customer's initial limit: R$ 1,000.00
  • Financed amount: R$ 500.00
  • New available limit: R$ 500.00

Status Meanings:

StatusAction Required
SUBMITTED_TO_FI⏳ PENDING - Disbursement in progress, call again to check status
FUNDED✅ CONFIRM ORDER - Disbursement successful, proceed with order fulfillment
FUNDING_FAILED❌ CANCEL ORDER - Disbursement failed, customer's limit is restored
🔄

Limit Restoration on Failure

If the status is FUNDING_FAILED, the customer's credit limit is automatically restored to the original amount (the financed amount is credited back).

Recommended Flow:

  1. Call /charge endpoint → Get initial status
  2. If SUBMITTED_TO_FI → Wait a few seconds and call /charge again to check updated status
  3. If FUNDED → ✅ Confirm and ship the order
  4. If FUNDING_FAILED → ❌ Cancel the order and notify customer
🎉

Success!

When status is FUNDED, the loan is active and the customer will receive their payment plan. You can now proceed with order fulfillment.

Additional Endpoints

Get Real-Time Available Lim

Check the customer's current available credit limit:

GET /person/{person_id}/available-limit

Response:

{
  "person_id": "ff0024e6-d11e-4700-b7f3-b3d201624e62",
  "available_limit": 4726.28,
  "currency": "BRL",
  "updated_at": "2026-01-20T10:30:00Z"
}

Need Help?

Updated 4 months ago