Collect the downpayment in the physical store

aCuotaz accepts down payments through credit/debit card and wire transfer. To allow your customers to do the down payments in the physical store, follow this guide.

Flow

The customer requests a credit loan as usual.
In the down payment stage, we present the customer the option to pay in the physical store.
If the customer selects this option, he goes directly to validate his information.
Once everything is validated, the customer receives a funding_code
With the funding_code, the customer approaches the cashier. As a visual help, if the funding_code screen is red, it means there is a pending down payment. It's green otherwise.
The cashier inputs the funding_code in the store system.
The store system makes a query to the endpoint Check funding_code to check if the funding_code is valid and if the downpayment is pending.
If the downpayment is pending, we return in the downpayment_status field PENDING, if the payment has already been made we return FULFILLED.
In the same way, if the payment was made or will be made in a store, we return in the downpayment_channel field, Tienda, if it was made directly in aCuotaz, aCuotaz is returned, for a greater detail of each processed transaction consult Day summary
Once the payment is received, the store system calls the endpoint Receive downpayment and billing
Only when the merchant receives a 200 ok response from aCuotaz, the screen showing the funding_code will turn green and the product can be delivered.
If the store wants to undo the billing, e.g. to change the product color, it should call the endpoint Undo billing ( This option do not cancel the credit loan ).
At the end of the day, the store can use the endpoint Day summary to do the cashier balancing.

Endpoints

We use a REST JSON API.

For the endpoints to work correctly, in the Authorization part, place the token that was provided, the token in this documentation is for reference.

Check funding_code

Validates whether a funding_code is valid and provides information about the funding. The merchant is responsible for checking whether the funding is valid through this endpoint.

URL: https://apurata.com/pos/client/inhouse-downpayment/v2/info?dni={dni}&funding_code={funding_code}

Method: GET

Success Response:

Code: 200 OK
{
  funding_code: [string],
  purchase_total: [float],
  billed_by_ecommerce: [bool],

  downpayment_amount: [float],
  downpayment_status: [string],    # "FULFILLED" | "PENDING"
  downpayment_channel: [string],   # "aCuotaz" | "Tienda"
}

Sample curl:

    curl 'https://apurata.com/pos/client/inhouse-downpayment/v2/info?dni=14159265&funding_code=1234567' \
      -H 'Authorization: Bearer 69a06d50c17e4267a18e84f8530d6asd'

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" }

Test Data:

You can get a success response using the following data:

URL: 'https://apurata.com/pos/client/inhouse-downpayment/mock/info?dni=XXXXXXXX&funding_code=XXXXXXX'
Auth token: 69a06d50c17e4267a18e84f8530d6asd
dni: 14159265
funding_code: 1234567

Receive down payment and billing

Notify aCuotaz that the total down payment amount was received by the physical store. Also mark the funding code as billed. If you call this API several times, only the first one will have effect. At this point, you have already validated the customer’s financing status through the endpoint Check funding_code. The field billed_by_ecommerce will be True and downpayment_status "FULFILLED".

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

Method: POST

Request body:

{
    dni: [string],
    ruc: [string],            # DNI or RUC can be sent to identify the operation
    funding_code: [string]
}

Success Response:

Code: 200 OK

Sample curl:

    curl 'https://apurata.com/pos/client/inhouse-downpayment/v2/paid-and-billed' \

      -H 'Authorization: Bearer 69a06d50c17e4267a18e84f8530d6asd' \
      -H 'Content-Type: application/json' \
      --data '{"dni": "14159265", "funding_code": "1234567"}'

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"
}

Test Data:

You can get a success response using the following data:

URL: 'https://apurata.com/pos/client/inhouse-downpayment/mock/paid-and-billed'
Auth token: 69a06d50c17e4267a18e84f8530d6asd
dni: 14159265
funding_code: 1234567

Undo billing

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

URL: https://apurata.com/pos/client/inhouse-downpayment/v2/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

Sample curl:

    curl 'https://apurata.com/pos/client/inhouse-downpayment/v2/undo-billing' \

      -H 'Authorization: Bearer 69a06d50c17e4267a18e84f8530d6asd' \
      -H 'Content-Type: application/json' \
      --data '{"dni": "14159265", "funding_code": "1234567"}'

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
{ error: "Not billed yet" }

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

Test Data:

You can get a success response using the following data:

URL: 'https://apurata.com/pos/client/inhouse-downpayment/mock/undo-billing'
dni: 14159265
funding_code: 1234567

Day summary

Return information about a given day to help with the cashier balancing.

URL: https://apurata.com/pos/client/inhouse-downpayment/v2/day-summary?day=YYYY-MM-DD

Method: GET

Success Response:

Code: 200 OK
{
    total_purchases: [float],
    total_paid_in_store: [float],
    total_financed: [float],        # total_purchases - total_paid_in_store
}

Sample curl:

    curl 'https://apurata.com/pos/client/inhouse-downpayment/v2/day-summary?day=2021-06-15' \
      -H 'Authorization: Bearer 69a06d50c17e4267a18e84f8530d6asd'

Error Responses:

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

Test Data:

You can get a success response using the following data:

URL: 'https://apurata.com/pos/client/inhouse-downpayment/mock/day-summary?day=YYYY-MM-DD'
Auth token: 69a06d50c17e4267a18e84f8530d6asd

If you want to get the details of each order, you can add the field detail=True to get a list with all the orders that were financed with aCuotaz for a specific day, this parameter is optional.

URL: https://apurata.com/pos/client/inhouse-downpayment/v2/day-summary?day=YYYY-MM-DD?detail=true

Method: GET

Success Response:

Code: 200 OK
{
    total_purchases: [float],
    total_paid_in_store: [float],
    total_financed: [float],        # total_purchases - total_paid_in_store
    order_detail: [
        {
            order_id : [string],
            dni: [string],
            payment_origin: [string],   # "transfer" | "card" | "external"
            amount: [float],
        }
    ],
}

When payment_origin is external, it means that the payment was made in store.

Sample curl:

    curl 'https://apurata.com/pos/client/inhouse-downpayment/v2/day-summary?day=2022-11-16&detail=true' \
    -H   'Authorization: Bearer 69a06d50c17e4267a18e84f8530d6asd'

Error Responses:

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

Code: 400 BAD REQUEST
{ day: "Not a valid date", detail: "Not a valid boolean" }

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