Rest API

Reminder: The basic integration with aCuotaz only requires webhooks and does not require using an API. Only review this page if you plan to use advanced functions.

Authentication

To authenticate your requests, you must include the following header in all your requests:

Authorization: Bearer [secret_token]

It is mandatory to use https, to avoid sending your credentials in clear text through the web. If you don't, you will be redirected to the https version of aCuotaz, but your credentials will have already been compromised on the web.

Get funding limits

It includes the minimum and maximum amounts that can be financed and the minimum and maximum number of installments that can be financed.

URL: /pos/client/landing_config

Method: GET

Success Response:

Code: 200 OK
{
  landing_version: [string],
  min_amount: [int],
  max_amount: [int],
  min_steps: [int],
  max_steps: [int]
}

Sample curl:

curl 'https://apurata.com/pos/client/landing_config' \
  -H 'Authorization: Bearer 69a06d50c17e4267a18e84f8530d6asd'

Error Responses:

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

Manage orders

Create order

URL: /pos/order/create

Method: POST

Data constraints

• amount (Float/Required)

Total amount of the purchase to finance

• acuotaz_send_sms (Bool/Optional/Default=False)

Boolean parameter to specify whether aCuotaz is responsible for sending the credit assessment application link to the customer after the order is created.

• order_id (String/Required/Unique)

Order id generated by your store which will be used to identify the order when we send information back to you

• expiration_ts (String(offset=utc0)/Optional)

Format: YYYY-MM-DD hh:mm:ss.mmm

Orders expire normally through our cascade expiration but it is used to shorten that time. For more details see Order expiration

IMPORTANT: Make sure that the timezone is UTC-0. To get the correct time, you can reduce 5 hours to peru timezone.

• pos_client_id (String/Required)

Client id provided by us to identify your store

• description (String/Optional)

Field to specify what is being purchased in this order.

• url_redir_on_canceled (URL/Required)

URL of your store to redirect when the aCuotaz application is canceled so the customer can select another payment method

• url_redir_on_rejected (URL/Required)

URL of your store to redirect when the aCuotaz application is rejected so the customer can select another payment method

• url_redir_on_success (URL/Required)

URL of your store to redirect when the aCuotaz application is successful. This is usually the order paid details.

• url_redir_on_downpayment (URL/Required)

Merchant URL to redirect the customer when he wants to pay the down payment in the e-commerce.

• url_redir_on_order_detail (URL/Optional)

Merchant URL to redirect the customer when he wants to see the purchased order details. This is usually the profile tab that shows paid orders.

• customer_6m_payment (List of Dict/Optional)
  
  Here you must send the customer’s last 6 month payments to your store. Each item has the following parameters:

  • dni (String/Required)

  • amount (String/Required)

  • payment_time (String(offset=utc0)/Required)

  • payment_detail (String/Required)

  • subscription_plan (Bool/Required)
    
    

• customer_data (Dict/Optional)
  
  Dictionary with user data. The fields available to use are described below.
  
  NOTE: The following parameters are to facilitate data entry in the steps of our funnel. It is important to send all the fields you have available.

  • address (String/Optional)

  • dni (String/Optional)

  • email (String/Optional)

  • name (String/Optional)

  • phone (String/Optional)

  • billing_address_1 (String/Optional)

  • billing_address_2 (String/Optional)

  • billing_city (String/Optional)

  • billing_company (String/Optional)

  • billing_first_name (String/Optional)

  • billing_last_name (String/Optional)

  • shipping_address_1 (String/Optional)

  • shipping_address_2 (String/Optional)

  • shipping_city (String/Optional)

  • shipping_company (String/Optional)

  • shipping_first_name (String/Optional)

  • shipping_last_name(String/Optional)

  • merchant_reference (String/Optional)

Success Response:

Code: 200 OK
{
    redirect_to: "https://apurata.com/pos?client={client_id}&acuotaz_order={ObjectId()}",
    status: "new_order"|"already_created"
}

If a new order_id is sent, the order will be created and the "new_order" status will be returned. In case you try to create an order with an existing id, the status "already_created" will be returned. In both cases the "redirect_to" field will be returned.

Sample curl:

curl -X POST 'https://apurata.com/pos/order/create' \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer {secret_token}' \
    --data-raw $'{
        "amount": 123.30,
        "order_id": "001",
        "pos_client_id": "tecno-tiendaz",
        "description": "name:product x, total:200",
        "url_redir_on_canceled": "https://tecnotiendaz.com/checkout",
        "url_redir_on_rejected": "https://tecnotiendaz.com/checkout",
        "url_redir_on_success": "https://tecnotiendaz.com/order_paid",
        "customer_data":{
            "address": "Dir. 123",
            "dni": "14159265",
            "email": "example@example.com",
            "name": "Example ",
            "phone": "99999999",
            "billing_city": "Lima"
        },
        "customer_6m_payment":{
            [
                    {
                        "dni": "14159265",
                        "amount": 200,
                        "payment_due_date": "2021-09-30",
                        "payment_date": "2021-09-30",
                        "payment_detail": "what is that payment?",
                        "subscription_plan": True/False
                    },{
                        "dni": "14159265",
                        "amount": 200,
                        "payment_due_date": "2021-08-30",
                        "payment_date": "2021-08-30",
                        "payment_detail": "what is that payment?",
                        "subscription_plan": True/False
                    },{
                        "dni": "14159265",
                        "amount": 200,
                        "payment_due_date": "2021-07-30",
                        "payment_date": "2021-07-30",
                        "payment_detail": "what is that payment?",
                        "subscription_plan": True/False
                    },...
            ]
        }
    }'

Error Responses:

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

Code: 400 BAD REQUEST
{ error: "Validation error, field XXXX required, etc." }

Code: 400 BAD REQUEST
{ error: "Client not registered" }

Code: 400 BAD REQUEST
{ error: "Cannot modify order" }

Get order information

It includes the order status and a magic link to easily continue.

URL: /pos/order/[order_id]

Method: GET

Success Response:

Code: 200 OK
{
    "amount": [float],
    "expiration_ts": [time],
    "url_redir_on_canceled": [URL],
    "order_id": [id],
    "url_redir_on_rejected": [URL],
    "url_redir_on_success": [URL],
    "customer_data": [dict],
    "description": [string],
    "pos_client_id": [string],
    "confirmed": [bool],
    "status": [string] # 'initial','created','approved','onhold','validated','funded','rejected', 'canceled'
    "magic_link": "https://apurata.com/magic_link_to_continue_application"
}

To see the possible values of the status variable, see the Order statuses.

Sample curl:

curl 'https://apurata.com/pos/order/48' \
  -H 'Authorization: Bearer 69a06d50c17e4267a18e84f8530d6asd'

Error Responses:

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

Code: 404 NOT FOUND
{ error: "Order does not exist" }

To total refund an order

URL /pos/order/[order_id]/total-refund

Method: POST

Data constraints

• author (String/Required)

Identifier of the reimburser for audit, it can be user_id, name, dni or some identifier of yours.

• reason (String/Required)

Reason for refund

Extra headers

• X-Unique-Token (String/Required/Unique)

A unique token from you to identify the transaction and avoid multiple reimbursements.

Success Response:

Code: 200 OK
{
    refund_method: 'transfer' | 'card',
    tracking_id: [string], // With this we can audit the reimbursements
    status: 'success' | 'already_refunded',
    successful: True
}

Error Responses:

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

Code: 404 NOT FOUND
{ error: "Order does not exist" }

Code: 400 BAD REQUEST
{ error: "Already canceled"}

Code: 400 BAD REQUEST
{ error: "Disbursement could not be made"}

Sample curl:

curl -X POST 'https://apurata.com/pos/order/48/total-refund' \
  -H 'Authorization: Bearer 69a06d50c17e4267a18e84f8530d6asd'\
  -H 'X-Unique-Token: 16763be4-6022-406e-a950-fcd5018633ca' \
  --data-raw $'{
        "author": 'Andy Sanchez',
        "reason": "Customer returned the product"
    }'

To partial refund an order

URL /pos/order/[order_id]/partial-refund

Method: POST

Data constraints

• amount (Float/Required)

The amount to be returned to the user, do not send the amount of the new order.

• author (String/Required)

Identifier of the reimburser for audit, it can be user_id, name, dni or some identifier of yours.

• reason (String/Required)

Reason for refund

Extra headers

• X-Unique-Token (String/Required/Unique)

A unique token from you to identify the transaction and avoid multiple reimbursements.

Success Response:

Code: 200 OK
{
    refund_method: 'transfer' | 'card',
    tracking_id: [string], // With this we can audit the reimbursements
    status: 'success' | 'decreased_debt',  // Multiple partial refunds can be made
    successful: True
}

Error Responses:

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

Code: 404 NOT FOUND
{ error: "Order does not exist" }

Code: 400 BAD REQUEST
{ error: "Amount must be greater than 0" | "Already canceled" | "Amount must be less than the approved amount"}

Code: 400 BAD REQUEST
{ error: "Partial disbursement could not be made"}

Sample curl:

curl -X POST 'https://apurata.com/pos/order/48/partial-refund' \
  -H 'Authorization: Bearer 69a06d50c17e4267a18e84f8530d6asd' \
  -H 'X-Unique-Token: 16763be4-6022-406e-a950-fcd5018633ca' \
  --data-raw $'{
        "amount": 123.52,
        "author": 'Andy Sanchez',
        "reason": "Customer change the product"
    }'

To cancel an order

URL /pos/order/[order_id]/cancel

Method: POST

Success Response:

Code: 200 OK
{ modified_orders: 1 } // Order found and cancelled

Code: 200 OK
{ result: "It is already canceled" } // Order was previously cancelled

Error Responses:

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

Code: 404 NOT FOUND
{ error: "Order does not exist" }

Code: 400 BAD REQUEST
{ error: "Cannot cancel a confirmed order" }

Sample curl:

curl -X POST 'https://apurata.com/pos/order/48/cancel' \
  -H 'Authorization: Bearer 69a06d50c17e4267a18e84f8530d6asd'

To confirm an order

URL /pos/order/[order_id]/confirm

Method: POST

Success Response:

Code: 200 OK
{ modified_orders: 1 }

Error Responses:

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

Code: 404 NOT FOUND
{ error: "Order does not exist" }

Code: 400 BAD REQUEST
{ error: "Cannot confirm an order before it is approved" }

Code: 400 BAD REQUEST
{ error: "Cannot confirm a funded order" }

Sample curl:

curl -X POST 'https://apurata.com/pos/order/48/confirm' \
  -H 'Authorization: Bearer 69a06d50c17e4267a18e84f8530d6asd'

To get aCuotaz Add-on

We highly recommend you to include this add-on to show information about the purchase price for a specific product or cart when financing it with aCuotaz.

URL: /pos/pay-with-apurata-add-on/[amount]

Method: GET

Success Response:

Code: 200 OK
Text:
    <style>
        /* Apurata style*/
    </style>
    <div id="pay-with-apurata" title="- Desde 0% de interés
        - Sin tarjeta de crédito
        - Hasta 8 cuotas
        - Aprobación instantánea" tabindex="0">
        <span>Paga tu compra en partes, desde S/18.45 con</span>
        <a href="https://apurata.com/app/partners/acuotaz">
            <img src="https://static.apurata.com/img/logo-dark-aCuotaz.svg" alt="aCuotaz">
        </a>
    </div>

Sample curl:

You have to include your "client_id" provided by Apurata and the amount, it can be integer or float.

curl 'https://apurata.com/pos/pay-with-apurata-add-on/[amount]' \
  -H 'Client_id: yourclientid'

Error Response:

Code: 401 UNAUTHORIZED
Detail: { "Unauthorized" }

To get aCuotaz info-steps

You can include this info-steps in your checkout page to show information about aCuotaz.

URL: /pos/[client_id]/info-steps

Method: GET

Success Response:

Code: 200 OK
Text:
    <style>
        /* Apurata style*/
    </style>
    <div class="apurata-checkout">
        <p class="title">Paga en Cuotas SIN TARJETA DE CR&#201;DITO</p>
        <div class="steps">
            <div class="step">
                <img src="https://static.apurata.com/img/pos/clock.svg">
                <br>
                <p class="text-center">Entrega Inmediata</p>
            </div>
            <div class="step">
                <img src="https://static.apurata.com/img/pos/form.svg">
                <br>
                <p class="text-center">Aprobación Instantánea</p>
            </div>
        </div>
        <div class="requeriments">
            <p class="title">Requisitos:</p>
            <ul class="list">
                <li>No estar reportado en <b>infocorp</b></li>
                <li>DNI <b>vigente</b> o C4 a la mano</li>
            </ul>
        </div>
        <div class="footer">
            <div class="payment">
                <p>Paga tu cuota inicial vía transferencia, tarjeta de débito o crédito</p>
                <img src="https://static.apurata.com/img/pos/all_banks.png" alt="bancos" class="responsive m-1">
            </div>
            <a class="how-work" href="https://apurata.com/app/partners/tecno-tiendaz">
                <b class="question">¿Cómo funciona?</b>
                <img src="https://static.apurata.com/img/logo-white-aCuotaz.svg" alt="aCuotaz"/>
            </a>
        </div>
    </div>

Sample curl:

You have to include your "client_id" provided by Apurata.

curl 'https://apurata.com/pos/[client_id]/info-steps'