Collect down payment in brick and mortar store (v4)

If you want to enable down payments collection at your brick and mortar store, please follow this guide.

The following map will show you a process flow to help you understand the interactions that must happen between your salesman/cashier and your customer when financing a product with aCuotaz. In parallel, it also shows the interactions between aCuotaz and your invoicing software through APIs.

Process flow summary

The customer requests aCuotaz financing to purchase a product at the brick and mortar store
The salesperson creates an order on aCuotaz dashboard or merchant ERP system
The customer recieves an application link through an SMS and completes the application process (web app)
During the application process, the customer will have the opportunity to select whether he wants to make the down payment at the store or through aCuotaz webpage. Then, he will continue to validate his identity.
Once the customer is approved for financing and his identity is validated, aCuotaz will show a funding_code on the customer´s phone screen (web app)
The customer will be instructed to provide the cashier his DNI and funding code.
The cashier will scan/register all the items the customer plans to purchase and then input funding_code and dni in the store invoice system.
Your system will then validate the transaction details by calling the endpoint Verify funding_code and funding conditions to check: 1) whether the funding_code is valid, 2) the total payment amount the store needs to collect, and 3) the number and amount of installments the customer needs to pay to aCuotaz
Once the payment is collected, but before the invoice is generated, the store invoice system calls the endpoint Receive downpayment and billing to confirm funding_code is valid and transaction details are correct
Only when the merchant receives a 200 ok response from aCuotaz, an invoice can be generated and the product delivered. Note that only orders we responded with code 200 at this stage will be billable to aCuotaz
If you receive a code 400 because the billed amount changed, you must make a second query to the endpoint Verify funding_code and funding conditions and collect the right down payment before calling the endpoint Receive downpayment and billing again
If the store wants to undo the billing, e.g. to change the product color, it should call the endpoint Undo billing ( This option does not cancel the credit loan )

Endpoints

We use a REST JSON API.

Verify funding_code and funding conditions

Validates whether the provided dni/ruc and funding_code are valid and returns information about the down payment amount the store needs to collect and the number and amount of installments the customer needs to pay aCuotaz. In some ocassions, aCuotaz will extend extra credit line to customers during their application process. Customers may opt to use the credit line by selecting extra items at your store. Thus, changing the final billed amount. In those cases, this API will recalculate the amount of installments and the down payment amount. Note that we won't ask the customer´s confirmation for his new credit conditions. However, we will notify them via sms and email, and your cashier will also have that information available.

Important in v4: The request must include financed_products, a non-empty list of product objects with detailed information about the items being financed.

The merchant is responsible for checking whether the funding code is valid through this endpoint.

URL:

https://apurata.com/pos/client/inhouse-downpayment/v4/verify-fundingcode-and-conditions

Method: POST

Request body:

{
    dni: [string],
    ruc: [string],                    # DNI or RUC can be sent to identify the operation
    funding_code: [string],
    billed_amount: [float],
    cashier_id: [string],             # ID of the cashier processing the transaction
    financed_products: [list<object>] # Required. Non-empty list of product objects
}

Product object structure (all fields are required):

{
    sku: [string],                      # Product SKU code
    name: [string],                     # Product name
    unit_price_after_discount: [float], # Unit price after discount (must be > 0)
    quantity: [integer],                # Quantity (must be >= 1)
    discount: [float],                  # Discount amount (must be >= 0)
    brand: [string],                    # Product brand
    category: [string],                 # Product category
    warranty_months: [integer],         # Warranty in months (must be >= 0)
    product_stage: [string]             # Product stage: "new", "used", or "refurbished"
}

Success Response:

Code: 200 OK
{
  dni: [string],                        # Could be ruc instead
  funding_code: [string],
  billed_amount: [float],
  billed_by_ecommerce: [bool],

  approved_amount: [float],
  excedent_amount: [float],             # billed_amount - approved_amount

  downpayment_amount: [float],          # Total down payment amount
  downpayment_amount_inhouse: [float],  # downpayment_amount - already_paid_in_acuotaz_platform

  installments_number: [int],           # Does not include down payment
  installments_amount: [float],         # Other than down payment amount

  financed_products: [list<object>]     # Echo of products persisted on lend.financed_products
}

To clarify some concepts:

excedent_amount is the amount that we cannot finance, so excedent_amount = billed_amount - approved_amount
downpayment_amount is the total amount of the down payment. However, if the customer selected to make the down payment directly to us during the application process, we might have collected either 100% of the final down payment amount or a portion of it if the billed amount changed. If the billed amount changed, the store would have to collect the difference between downpayment_amount - already_paid. This amount will be inform to you using the variabledownpayment_amount_inhouse. If already_paid is greater than the down_payment amount, we will credit the difference by reducing the next installmment amount.
The exact amount that should be collected by the store before delivering is downpayment_amount_inhouse + excedent_amount`

Sample curl:

    curl 'https://apurata.com/pos/client/inhouse-downpayment/v4/verify-fundingcode-and-conditions' \
  -H 'Authorization: Bearer 5f80f8c488b0458db0603e85a38b62c5' \
  -H 'Content-Type: application/json' \
  --data '{"dni": "70323554", "funding_code": "3806888", "billed_amount":600, "cashier_id":"12345", "financed_products":[{"sku":"SKU-1","name":"zapatillas","unit_price_after_discount":300.0,"quantity":1,"discount":0.0,"brand":"Nike","category":"calzado","warranty_months":6,"product_stage":"new"},{"sku":"SKU-2","name":"celular","unit_price_after_discount":300.0,"quantity":1,"discount":0.0,"brand":"Xiaomi","category":"telefonia","warranty_months":12,"product_stage":"new"}]}'

Error Responses:

Code: 401 UNAUTHORIZED
{ error: "Wrong or missing client token" }

Code: 404 NOT FOUND
{ error: "Funding code does not exist or not active" }

Code: 404 NOT FOUND
{ error: "Financing DNI does not match with the DNI sent" }

Code: 400 BAD REQUEST
{ dni: "Error on dni format", funding_code: "Error on funding_code format" }

Code: 400 BAD REQUEST
{ error: "cashier_id changed" }

Code: 400 BAD REQUEST
{ error: "billed_amount cannot change after being marked as billed" }

Code: 400 BAD REQUEST
{ error: "Missing data for required field." }  # When financed_products is missing

Code: 400 BAD REQUEST
{ error: "Length must be at least 1." }  # When financed_products is an empty list

Code: 400 BAD REQUEST
{ error: { "financed_products": { "0": { "sku": ["Missing data for required field."] } } } }  # Invalid product schema

Code: 400 BAD REQUEST
{ error: "Your store is not allowed to use this endpoint" }

Receive down payment and billing

Only orders we successfully marked as billed with this endpoint will be billable to aCuotaz. The store is responsible for any products delivered without receiving confirmation from us through this endpoint.

This endpoint verifies two things:

That the billed_amount didn´t change
That the user accepted the new installment schedule (we may request it in some ocassions for risk managment reasons).

If you get the error "billed_amount changed", you need to call the previous endpoint again: Verify funding_code and funding conditions

If you get the error "Customer did not accept new installment schedule yet", you need to ask your customer to review and accept the new installment schedule in the aCuotaz website.

You should call this API before generating an invoice in your invoice system, but after collecting the down payment. This way, if we have an error preventing the billing process, you don't have to undo your billing.

If you call this API several times, only the first one will have effect. After you get success response from this API, if you call the endpoint Verify funding_code and funding conditions, the field billed_by_ecommerce will be True and if there was no excedent_amount the downpayment_amount_inhouse will show the amount you should have collected from the customer

URL: https://apurata.com/pos/client/inhouse-downpayment/v4/paid-and-billed

Method: POST

Request body:

{
    dni: [string],
    ruc: [string],                    # DNI or RUC can be sent to identify the operation
    funding_code: [string],
    billed_amount: [float],
    cashier_id: [string],             # ID of the cashier processing the transaction
    financed_products: [list<object>] # Required. Must be EXACTLY the same as sent in verify endpoint
}

Note: The financed_products must be exactly the same as those sent in the verify-fundingcode-and-conditions endpoint. The order does not matter, but the data must match.

Success Response:

Code: 200 OK
{ "status": "ok" }

Sample curl:

    curl 'https://apurata.com/pos/client/inhouse-downpayment/v4/paid-and-billed' \
      -H 'Authorization: Bearer 69a06d50c17e4267a18e84f8530d6asd' \
      -H 'Content-Type: application/json' \
      --data '{"dni": "70323554", "funding_code": "3806888", "billed_amount":600, "cashier_id":"12345", "financed_products":[{"sku":"SKU-1","name":"zapatillas","unit_price_after_discount":300.0,"quantity":1,"discount":0.0,"brand":"Nike","category":"calzado","warranty_months":6,"product_stage":"new"},{"sku":"SKU-2","name":"celular","unit_price_after_discount":300.0,"quantity":1,"discount":0.0,"brand":"Xiaomi","category":"telefonia","warranty_months":12,"product_stage":"new"}]}'

Error Responses:

Code: 401 UNAUTHORIZED
{ error: "Wrong or missing client token" }

Code: 404 NOT FOUND
{ error: "Funding code does not exist or not active" }

Code: 400 BAD REQUEST
{
    dni: "Error on dni format",
    funding_code: "Error on funding_code format"
}

Code: 400 BAD REQUEST
{ error: "billed_amount changed" }

Code: 400 BAD REQUEST
{ error: "cashier_id changed" }

Code: 400 BAD REQUEST
{ error: "Missing data for required field." }  # When financed_products is missing

Code: 400 BAD REQUEST
{ error: "Length must be at least 1." }  # When financed_products is an empty list

Code: 400 BAD REQUEST
{ error: { "financed_products": { "0": { "sku": ["Missing data for required field."] } } } }  # Invalid product schema

Code: 400 BAD REQUEST
{ error: "Products have changed. Please call info endpoint again with the correct products." }

Code: 400 BAD REQUEST
{ error: "Client not enabled to use this API" }

Code: 400 BAD REQUEST
{ error: "Customer did not accept new installment schedule yet" }

Undo billing

Notify aCuotaz the billing of a funding_code was undone, so the endpoint Receive downpayment and billing can be used again. The down payment stays as paid though.

Note: This endpoint uses v3 as it has not changed in v4.

URL: https://apurata.com/pos/client/inhouse-downpayment/v3/undo-billing

Method: POST

Request body:

{
    dni: [string],              # DNI or RUC can be sent to identify the operation
    ruc: [string],              # Only RUCs starting with '10' are supported
    funding_code: [string]
}

Success Response:

Code: 200 OK
{ "status": "ok" }

Sample curl:

    curl 'https://apurata.com/pos/client/inhouse-downpayment/v3/undo-billing' \
      -H 'Authorization: Bearer 69a06d50c17e4267a18e84f8530d6asd' \
      -H 'Content-Type: application/json' \
      --data '{"dni": "70323554", "funding_code": "3806888"}'

Note: This endpoint clears billed_amount state if present so the flow can proceed again.

Examples

Down Payment Fully Collected at Store:

Case: Approved amount greater than purchased items price

The customer requests financing for S/200, but later decides to purchase a S/150 item. The store invoice system will call the endpoint

URL:

https://apurata.com/pos/client/inhouse-downpayment/v4/verify-fundingcode-and-conditions

Method: POST

Request body:

{
    dni: '14159265',
    funding_code: '1234567',
    billed_amount: 150,
    cashier_id: 'cashier123',
    financed_products: [
        {
            sku: 'SKU-1',
            name: 'zapatillas',
            unit_price_after_discount: 150.0,
            quantity: 1,
            discount: 0.0,
            brand: 'Nike',
            category: 'calzado',
            warranty_months: 6,
            product_stage: 'new'
        }
    ]
}

Success Response: (billed_amount:200)

Code: 200 OK
{
  dni: '14159265',
  funding_code: '1234567'
  billed_amount: 200,
  billed_by_ecommerce: False,
  approved_amount: 200,
  excedent_amount: 0,
  downpayment_amount: 50,
  downpayment_amount_inhouse: 50,
  installments_number: 3,
  installments_amount: 50,
}

Success Response: (billed_amount:150)

Code: 200 OK
{
  dni: '14159265',
  funding_code: '1234567'
  billed_amount: 150,
  billed_by_ecommerce: False,
  approved_amount: 150,
  excedent_amount: 0,
  downpayment_amount: 37.5,
  downpayment_amount_inhouse: 37.5,
  installments_number: 3,
  installments_amount: 37.5,
}

Case: Purchased items price exceeds approved amount but are within credit line limit

The customer requests financing for S/200 and during the application process we inform the customer that he has access to a S/600 credit line . The customer later decides to purchase items worth S/400. The store invoice system will call the endpoint

URL:

https://apurata.com/pos/client/inhouse-downpayment/v4/verify-fundingcode-and-conditions

Method: POST

Request body:

{
    dni: '14159265',
    funding_code: '1234567',
    billed_amount: 400,
    cashier_id: 'cashier123',
    financed_products: [
        {
            sku: 'SKU-1',
            name: 'zapatillas',
            unit_price_after_discount: 200.0,
            quantity: 1,
            discount: 0.0,
            brand: 'Nike',
            category: 'calzado',
            warranty_months: 6,
            product_stage: 'new'
        },
        {
            sku: 'SKU-2',
            name: 'celular',
            unit_price_after_discount: 200.0,
            quantity: 1,
            discount: 0.0,
            brand: 'Xiaomi',
            category: 'telefonia',
            warranty_months: 12,
            product_stage: 'new'
        }
    ]
}

Success Response: (billed_amount:200)

Code: 200 OK
{
  dni: '14159265',
  funding_code: '1234567',
  billed_amount: 200,
  billed_by_ecommerce: False,
  approved_amount: 200,
  excedent_amount: 0,
  downpayment_amount: 50,
  downpayment_amount_inhouse: 50,
  installments_number: 3,
  installments_amount: 50,
}

Success Response: (billed_amount:400)

Code: 200 OK
{
  dni: '14159265',
  funding_code: '1234567',
  billed_amount: 400,
  billed_by_ecommerce: False,
  approved_amount: 400,
  excedent_amount: 0,
  downpayment_amount: 100,
  downpayment_amount_inhouse: 100,
  installments_number: 3,
  installments_amount: 100,
}

Case: Purchased items price exceeds credit line

The customer requests financing for S/200 and during the application process we inform the customer that he has access to a S/600 credit line. The customer later decides to purchase items worth S/800. The store invoice system will call the endpoint

URL:

https://apurata.com/pos/client/inhouse-downpayment/v4/verify-fundingcode-and-conditions

Method: POST

Request body:

{
    dni: '14159265',
    funding_code: '1234567',
    billed_amount: 800,
    cashier_id: 'cashier123',
    financed_products: [
        {
            sku: 'SKU-1',
            name: 'zapatillas',
            unit_price_after_discount: 400.0,
            quantity: 1,
            discount: 0.0,
            brand: 'Nike',
            category: 'calzado',
            warranty_months: 6,
            product_stage: 'new'
        },
        {
            sku: 'SKU-2',
            name: 'celular',
            unit_price_after_discount: 400.0,
            quantity: 1,
            discount: 0.0,
            brand: 'Xiaomi',
            category: 'telefonia',
            warranty_months: 12,
            product_stage: 'new'
        }
    ]
}

with a billled_amount of S/800. The endpoint will recalculate the new down payment and installments amount for S/600. The portion of the sale that will not be financed by aCuotaz will be the excedent amount (billed amount - credit line). In this example, the excedent amount is S/200. For example, if the customer wanted to pay in 4 interest free installments. The down payment and the amount of installments will change from S/50 (S/200 / 4) to S/150 (S/600 / 4). In addition, the store must collect the excedent amount of S/200 to complete the purchase. From the customer perspective, he will have to pay a total of S/350 (S/150 aCuotaz down payment and S/200 excedent amount) and then 3 more installments of S/150 each.

Success Response: (billed_amount:200)

Code: 200 OK
{
  dni: '14159265',
  funding_code: '1234567',
  billed_amount: 200,
  billed_by_ecommerce: False,
  approved_amount: 200,
  excedent_amount: 0,
  downpayment_amount: 50,
  downpayment_amount_inhouse: 50,
  installments_number: 3,
  installments_amount: 50,
}

Success Response: (billed_amount:800)

Code: 200 OK
{
  dni: '14159265',
  funding_code: '1234567',
  billed_amount: 800,
  billed_by_ecommerce: False,
  approved_amount: 600,
  excedent_amount: 200,
  downpayment_amount: 150,
  downpayment_amount_inhouse: 150,
  installments_number: 3,
  installments_amount: 150,
}

Down Payment Collected by aCuotaz before Customer Validation:

Case: Approved amount is greater than price of purchased items

The customer requests financing for S/200 and makes the down payment directly to aCuotaz through credit/debit card or direct transfer, but later decides to purchase a S/150 item. The store invoice system will call the endpoint

URL:

https://apurata.com/pos/client/inhouse-downpayment/v4/verify-fundingcode-and-conditions

Method: POST

Request body:

{
    dni: '14159265',
    funding_code: '1234567',
    billed_amount: 150,
    cashier_id: 'cashier123',
    financed_products: [
        {
            sku: 'SKU-1',
            name: 'zapatillas',
            unit_price_after_discount: 150.0,
            quantity: 1,
            discount: 0.0,
            brand: 'Nike',
            category: 'calzado',
            warranty_months: 6,
            product_stage: 'new'
        }
    ]
}

with a billled_amount of S/150. The endpoint will recalculate the new down payment and installments amount. For example, if the customer wanted to pay in 4 interest free installments. The down payment and the amount of installments will change from S/50 (S/200 / 4) to S/37.5 (S/150 / 4). Since the customer already paid S/50 to aCuotaz, we will credit the difference between what we originally collected and what is owed S/12.5 (S/50-S/37.5) to his next installment.

Success Response: (billed_amount:200)

Code: 200 OK
{
  dni: '14159265',
  funding_code: '1234567',
  billed_amount: 200,
  billed_by_ecommerce: False,
  approved_amount: 200,
  excedent_amount: 0,
  downpayment_amount: 50,
  downpayment_amount_inhouse: 50,
  installments_number: 3,
  installments_amount: 50,
}

Success Response: (billed_amount:150)

Code: 200 OK
{
  dni: '14159265',
  funding_code: '1234567',
  billed_amount: 150,
  billed_by_ecommerce: False,
  approved_amount: 150,
  excedent_amount: 0,
  downpayment_amount: 37.5,
  downpayment_amount_inhouse: 37.5,
  installments_number: 3,
  installments_amount: 37.5,
}

Case: Purchased items price exceeds either the approved amount or the credit line

The customer requests financing for S/200 and makes the down payment directly to aCuotaz through credit/debit card or direct transfer. During the application process we inform the customer that he has access to a S/600 credit line . The customer later decides to purchase items worth S/400. The store invoice system will call the endpoint

URL:

https://apurata.com/pos/client/inhouse-downpayment/v4/verify-fundingcode-and-conditions

Method: POST

Request body:

{
    dni: '14159265',
    funding_code: '1234567',
    billed_amount: 400,
    cashier_id: 'cashier123',
    financed_products: [
        {
            sku: 'SKU-1',
            name: 'zapatillas',
            unit_price_after_discount: 200.0,
            quantity: 1,
            discount: 0.0,
            brand: 'Nike',
            category: 'calzado',
            warranty_months: 6,
            product_stage: 'new'
        },
        {
            sku: 'SKU-2',
            name: 'celular',
            unit_price_after_discount: 200.0,
            quantity: 1,
            discount: 0.0,
            brand: 'Xiaomi',
            category: 'telefonia',
            warranty_months: 12,
            product_stage: 'new'
        }
    ]
}

with a billled_amount of S/400. The endpoint will recalculate the new down payment and installments amount. For example, if the customer wanted to pay in 4 interest free installments. The down payment and the amount of installments will change from S/50 (S/200 / 4) to S/100 (S/400 / 4). Since the customer already paid S/50 to aCuotaz, the endpoint will calculate the extra amount the customer needs to pay to complete the new down payment of S/100. In this case, it will be S/50 (S/100 - S/50). This data point will be informed to you as downpayment_inhouse.

Success Response: (billed_amount:200)

Code: 200 OK
{
  dni: '14159265',
  funding_code: '1234567',
  billed_amount: 200,
  billed_by_ecommerce: False,
  approved_amount: 200,
  excedent_amount: 0,
  downpayment_amount: 50,
  downpayment_amount_inhouse: 50,
  installments_number: 3,
  installments_amount: 50,
}

Success Response: (billed_amount:400)

Code: 200 OK
{
  dni: '14159265',
  funding_code: '1234567',
  billed_amount: 400,
  billed_by_ecommerce: False,
  approved_amount: 400,
  excedent_amount: 0,
  downpayment_amount: 100,
  downpayment_amount_inhouse: 50,
  installments_number: 3,
  installments_amount: 100,
}

Keys	Action
`?`	Open this help
`n`	Next page
`p`	Previous page
`s`	Search