Acqio Mais API

This document will cover the basics of how to receive a payment using the Acqio Mais API.

Requirements

You will need a computer with windows 7+ connected to the internet, the Acqio Mais software installed, and a pinpad properly connected and configured.

Starting a transaction

To start a transaction, run Acqio Mais then submit a POST request to http://localhost:12030/transaction/start with a payload similar to the examples below:

{
   "installment":3,
   "cardApplication":"CREDITO",
   "value":0.03,
   "tenantPlanMode":"DISABLED",
   "qrApplication":"NENHUM"
}

{
   "installment":1,
   "cardApplication":"DEBITO",
   "value":0.03,
   "tenantPlanMode":"DISABLED",
   "qrApplication":"NENHUM"
}

• installment: credit transactions has one or more installments. Debit transactions will always have one installment. Installments number cannot be zero.
• cardApplication: credit (CREDITO) transaction or debit (DEBITO) transaction.
• value: transaction value.
• tenantPlanMode: transaction value increment. This field is mandatory and must be fulfilled with one of the following values:
  • DISABLED: function deactivation.
  • TENANT: the transaction value increment will be based on “Lojista e Portador” plan.
  • MDR_0: The transaction value increment will be evaluated in a way that the transaction cost is passed forward to the card holder.
• qrApplication: payment method.
  • ELO_BRCODE_DEBITO (debit transaction) or ELO_BRCODE_CREDITO (credit transaction): Qr Code payment.
  • PIX_DEBITO: instant electronic payment (PIX).
  • NENHUM: card payment.

The application will return the status 1 (PROCESSING) with the transaction id. All the communication betweeen the pinpad and the acquirer host is carried out by Acqio Mais. An Example of the API’s response should look similar to the example below:

{
   "id":89,
   "status":1,
   "actions":[
      "/transaction/status",
      "/transaction/abort"
   ],
   "message":"ACQIO MAIS"
}

If there’s a transaction in course, the API’s response should look similar to the example below:

{
   "status":-1,
   "actions":[
      "/transaction/status",
      "/transaction/abort"
   ],
   "message":"JÁ EXISTE UMA TRANSAÇÃO SENDO PROCESSADA"
}

If the pinpad is not configured or it is disconnected, the API’s response should look similar to the example below:

{
   "id":1,
   "status":1,
   "actions":[
      "/transaction/status",
      "/transaction/abort"
   ],
   "message":"NÃO FOI POSSIVEL SE COMUNICAR COM O PINPAD.[COMXX]"
}

Keeping track of the current transaction

The application consuming the API should make a GET request in loop to http://localhost:12030/transaction/status to keep track of the transaction flow until it gets a response with status 2 (WAITING CHARGE). The API response to this request should look similar to the examples below:

Transaction with status 1 (PROCESSING).

{
   "id":3,
   "status":1,
   "actions":[
      "/transaction/abort"
   ],
   "message":"APROX, INSIRA OU PASSE O CARTAO",
   "installmentInfo":null,
   "cardInfo":null,
   "clearDataResponseDTO":null
}

{
   "id":3,
   "status":1,
   "actions":[
      "/transaction/abort"
   ],
   "message":"SELECIONADO:    Credito Nubank  ",
   "installmentInfo":null,
   "cardInfo":null,
   "clearDataResponseDTO":null
}

Transaction with status 2 (WAITING CHARGE).

{
   "id":1,
   "status":2,
   "actions":[
      "/transaction/charge/{installment}",
      "/transaction/abort"
   ],
   "message":"SELECIONADO:    Credito Nubank  ",
   "installmentInfo":[
      {
         "cardBrand":"Mastercard",
         "cardApplication":"CREDITO",
         "installment":1,
         "installmentValue":0.03,
         "total":0.03
      },
      {
         "cardBrand":"Mastercard",
         "cardApplication":"CREDITO",
         "installment":2,
         "installmentValue":0.02,
         "total":0.04
      },
      {
         "cardBrand":"Mastercard",
         "cardApplication":"CREDITO",
         "installment":3,
         "installmentValue":0.01,
         "total":0.03
      }
   ],
   "cardInfo":{
      "requireSignature":false,
      "holderName":"SILVA/PEDRO A B",
      "bin":"123456"
   }
}

Password request

When the API returns status 2 (WAITING CHARGE), send a GET request to http://localhost:12030/api/transaction/charge/{installment}, where the {installment} parameter should be replaced by the number of installments in this transaction (the same number informed in the installment field when a request was sent to http://localhost:12030/api/transaction/start)

Request example to http://localhost:12030/api/transaction/start.

{
   "installment": 3,
   "cardApplication": "CREDITO",
   "value": 0.03,
   "tenantPlanMode": "DISABLED",
   "qrApplication": "NENHUM"
   }

Therefore, the request must be sent to http://localhost:12030/api/transaction/charge/3.

After sending a request to http://localhost:12030/api/transaction/charge/{installment}, the API will return status 3 (PROCESSING_CHARGE). The API response to this request should look like the example below:

{
   "id":2,
   "status":3,
   "actions":[
      "/transaction/abort"
   ],
   "message":"SELECIONADO: Credito Nubank "
}

After getting a status 3 (PROCESSING_CHARGE), the password must be typed on the pinpad.

If a request is sent to http://localhost:12030/api/transaction/status, the API will return the following message:

{
   "id":2,
   "status":3,
   "actions":[
      "/transaction/abort"
   ],
   "message":"SOLICITE A SENHA                "
}

Transaction end

The transaction will be processed and the API may return a successful or unsuccesful response. Keep track of the transaction status until the API return the status 0 (SUCCESS). That means the transaction was completed successfully and the transaction flow has finished. The API status should look similar to the examples below:

{
   "id":3,
   "status":3,
   "actions":[
      "/transaction/abort"
   ],
   "message":"  PROCESSANDO   ",
   "installmentInfo":null,
   "cardInfo":null,
   "clearDataResponseDTO":null
}

{
  "id":3,
  "status":3,
  "actions":[
     "/transaction/abort"
  ],
  "message":"     APROVADA    ",
  "installmentInfo":null,
  "cardInfo":null,
  "clearDataResponseDTO":null
}

 {
  "id":3,
  "status":0,
  "actions":[
     "/transaction/abort"
  ],
  "message":"RETIRE O CARTAO ",
  "installmentInfo":null,
  "cardInfo":null,
  "clearDataResponseDTO":null
}

Aborting an in-progress transaction

At some point after starting a transaction, the application may cancel the current operation by sending a GET request to http://localhost:12030/transaction/abort. This will abort the current operation and make the API return to it’s idle state. An example of the API’s response should look similar to the example below:

Note: In this case status 0(SUCCESS) means that the abort request was successful

{
   "id":88,
   "status":0,
   "actions":[

   ],
   "message":""
}

Getting the merchant and customer receipt

While calling http://localhost:12030/transaction/status, the Acqio Mais application may respond with a status 0 (SUCCESS). This means the transaction was completed successfully and the application can now make a GET request to http://localhost:12030/transaction/receipt/{id} to get the merchant and customer receipt. The id is the one the application received when it started the transaction. The receipt is a string with a line feed character at the end of each line. The API response should look similar to the example below:

Note: If no id is provided the Acqio Mais API will return the receipt of the last successful transaction.

{
   "transactionId":89,
   "status":0,
   "paymentStatus":"SUCCESS",
   "cardApplication":"CREDITO",
   "cardHiddenPan":"410863******3263",
   "authorizationCode":"372568",
   "cardProductName":"VISA",
   "nsu":"000314030029",
   "nsuOriginal":"000314030030",
   "merchant":"VISA\nVIA ESTAB.\nNOME ESTABELECIMENTO\nCNPJ 00.000.000/0001-00\nAV DA ALEGRIA 100\n11 99999-9999 \nCREDITO\n************1234\nR$0,03\nCREDITO A VISTA\n08/10/19 09:52 AUTO:123456\nAUTORIZADA MEDIANTE SENHA\nCV:07257591 7805\nEC:T5NON91IT0RAQ55\nTI:00000000\nAC:JR85E1BLASMR3JKC\nAID:5NON91IT0RAQ56\nTX:61406035\nSN:AA0000123\n",
   "client":"VISA\nVIA CLIENTE\nNOME ESTABELECIMENTO\nCNPJ 00.000.000/0001-00\nAV DA ALEGRIA 100\n11 99999-9999\nCREDITO\n************1234\nR$0,03\nCREDITO A VISTA\n08/10/19 09:52 AUTO:123456\nCV:072575917805\nEC:T5NON91IT0RAQ55\n TI:00000000\nAC:JR85E1BLASMR3JKC\nAID:5NON91IT0RAQ56\nTX:61406035\nSN:AA0000123\n",
   "merchantHtml":"...",
   "clientHtml":"..."
}

Note: The last transaction receipt may be a reversal receipt.

{
   "transactionId":89,
   "status":0,
   "paymentStatus":"CANCELED",
   "cardApplication":"CREDITO",
   "cardHiddenPan":"410863******3263",
   "authorizationCode":"372568",
   "cardProductName":"VISA",
   "nsu":"000314030029",
   "nsuOriginal":"000314030030",
   "merchant":"VISA\nVIA ESTAB.\nNOME ESTABELECIMENTO\nCNPJ 00.000.000/0001-00\nAV DA ALEGRIA 100\n11 99999-9999 \nCREDITO\n************1234\nVALOR CANCELADO\nR$0,03\nESTORNO CREDITO A VISTA\n08/10/19 12:07 AUTO:123456\nAUTORIZADA
 MEDIANTE SENHA\nCV:072575917805\nEC:T5NON91IT0RAQ55\nTI:00000000\nAC:JR85E1BLASMR3JKC\nAID:5NON91IT0RAQ56\nTX:61406035\nSN:AA0000123\nCV ORIG:072575917804\n",
   "client":"VISA\nVIA CLIENTE\nNOME ESTABELECIMENTO\nCNPJ 00.000.000/0001-00\nAV DA ALEGRIA 100\n11 99999-9999\n CREDITO\n************1234\nVALOR CANCELADO\nR$0,03\nESTORNO CREDITO A VISTA\n08/10/19 12:07 AUTO:123456\nCV:072575917805 \nEC:T5NON91IT0RAQ55\nTI:00000000\nAC:JR85E1BLASMR3JKC\nAID:5NON91IT0RAQ56\nTX:61406035\nSN:AA0000123\nCV ORIG:072575917 804\n",
   "merchantHtml":"...",
   "clientHtml":"..."
}

Note: If the id provided is incorret or could not be found in the database, the application will recieve a response similar to the example below:

{
   "transactionId":-1,
   "status":-2,
   "merchant":"",
   "client":""
}

Note: If no id is provided the Acqio Mais API will return the receipt of the last successful.

Reverting a successful transaction

This operation can only be performed on the same day the transaction ocurred. Trying to revert an operation on the next day or after will fail. To revert a transaction, the application should make GET request to http://localhost:12030/transaction/revert/{id}, where the id is the one the application received when it started the transaction. The reversal response should look similar to the examples below:

{
   "id":89,
   "status":1,
   "actions":[
      "/transaction/status",
      "/transaction/abort"
   ],
   "message":"INICIANDO CANCELAMENTO"
}

{
   "id":89,
   "status":1,
   "actions":[
      "/transaction/status",
      "/transaction/abort"
   ],
   "message":"INSIRA OU PASSE O CARTAO"
}

{
   "id":89,
   "status":1,
   "actions":[
      "/transaction/status",
      "/transaction/abort"
   ],
   "message":"DEBITO SELECIONADO"
}

{
   "id":89,
   "status":1,
   "actions":[
      "/transaction/status",
      "/transaction/abort"
   ],
   "message":"PROCESSANDO..."
}

{
   "id":89,
   "status":1,
   "actions":[
      "/transaction/status",
      "/transaction/abort"
   ],
   "message":"CANCELAMENTO APROVADO"
}

{
   "id":89,
   "status":0,
   "actions":[
      "/transaction/status",
      "/transaction/abort"
   ],
   "message":"RETIRE O CARTAO"
}

Note: The following response may be caused by a desconfigured or desconnected pinpad.

{
   "id": -1,
   "status": -1,
   "actions": [
      "/transaction/status",
      "/transaction/abort"
], "message": "Não foi possivel se comunicar com o Pinpad.[COMXX]" }

Status table

CODIGO	DESCRIÇÃO
-2	NOT FOUND
-1	INACTIVE
0	SUCCESS
1	PROCESSING
2	WAITING CHARGE
3	PROCESSING CHARGE
4	PROCESSING CLEAR DATA

Flowchart

Installment Simulation

The Acqio Mais API provides an endpoint to simulate installments. To consume it, make a POST request to http://localhost:12030/tenant/plan with the value as payload. The request should look similar to the example below:

{
   "value":100.00
}

The API will calculate the installments according to the tenant’s plan and respond with a JSON that should look similar to the example below:

{
   "tenantName":"YATTA SUSHI",
   "installmentInfoList":[
      {
         "cardBrand":"Visa",
         "cardApplication":"DEBITO",
         "installment":1,
         "installmentValue":100.00,
         "total":100.00
      },
      {
         "cardBrand":"Visa",
         "cardApplication":"CREDITO",
         "installment":1,
         "installmentValue":100.00,
         "total":100.00
      },
      {
         "cardBrand":"Visa",
         "cardApplication":"CREDITO",
         "installment":2,
         "installmentValue":50.00,
         "total":100.00
      },
      {
         "cardBrand":"Visa",
         "cardApplication":"CREDITO",
         "installment":3,
         "installmentValue":33.34,
         "total":100.02
      },
      {
         "cardBrand":"Visa",
         "cardApplication":"CREDITO",
         "installment":4,
         "installmentValue":26.50,
         "total":106.00
      },
      {
         "cardBrand":"Visa",
         "cardApplication":"CREDITO",
         "installment":5,
         "installmentValue":21.60,
         "total":108.00
      },
      {
         "cardBrand":"Visa",
         "cardApplication":"CREDITO",
         "installment":6,
         "installmentValue":18.33,
         "total":109.98
      },
      {
         "cardBrand":"Visa",
         "cardApplication":"CREDITO",
         "installment":7,
         "installmentValue":16.00,
         "total":112.00
      },
      {
         "cardBrand":"Visa",
         "cardApplication":"CREDITO",
         "installment":8,
         "installmentValue":14.25,
         "total":114.00
      },
      {
         "cardBrand":"Visa",
         "cardApplication":"CREDITO",
         "installment":9,
         "installmentValue":12.88,
         "total":115.92
      },
      {
         "cardBrand":"Visa",
         "cardApplication":"CREDITO",
         "installment":10,
         "installmentValue":11.80,
         "total":118.00
      },
      {
         "cardBrand":"Visa",
         "cardApplication":"CREDITO",
         "installment":11,
         "installmentValue":10.90,
         "total":119.90
      },
      {
         "cardBrand":"Visa",
         "cardApplication":"CREDITO",
         "installment":12,
         "installmentValue":10.16,
         "total":121.92
      },
      {
         "cardBrand":"Mastercard",
         "cardApplication":"DEBITO",
         "installment":1,
         "installmentValue":100.00,
         "total":100.00
      },
      {
         "cardBrand":"Mastercard",
         "cardApplication":"CREDITO",
         "installment":1,
         "installmentValue":100.00,
         "total":100.00
      },
      {
         "cardBrand":"Mastercard",
         "cardApplication":"CREDITO",
         "installment":2,
         "installmentValue":50.00,
         "total":100.00
      },
      {
         "cardBrand":"Mastercard",
         "cardApplication":"CREDITO",
         "installment":3,
         "installmentValue":33.34,
         "total":100.02
      },
      {
         "cardBrand":"Mastercard",
         "cardApplication":"CREDITO",
         "installment":4,
         "installmentValue":26.50,
         "total":106.00
      },
      {
         "cardBrand":"Mastercard",
         "cardApplication":"CREDITO",
         "installment":5,
         "installmentValue":21.60,
         "total":108.00
      },
      {
         "cardBrand":"Mastercard",
         "cardApplication":"CREDITO",
         "installment":6,
         "installmentValue":18.33,
         "total":109.98
      },
      {
         "cardBrand":"Mastercard",
         "cardApplication":"CREDITO",
         "installment":7,
         "installmentValue":16.00,
         "total":112.00
      },
      {
         "cardBrand":"Mastercard",
         "cardApplication":"CREDITO",
         "installment":8,
         "installmentValue":14.25,
         "total":114.00
      },
      {
         "cardBrand":"Mastercard",
         "cardApplication":"CREDITO",
         "installment":9,
         "installmentValue":12.88,
         "total":115.92
      },
      {
         "cardBrand":"Mastercard",
         "cardApplication":"CREDITO",
         "installment":10,
         "installmentValue":11.80,
         "total":118.00
      },
      {
         "cardBrand":"Mastercard",
         "cardApplication":"CREDITO",
         "installment":11,
         "installmentValue":10.90,
         "total":119.90
      },
      {
         "cardBrand":"Mastercard",
         "cardApplication":"CREDITO",
         "installment":12,
         "installmentValue":10.16,
         "total":121.92
      },
      {
         "cardBrand":"Hipercard",
         "cardApplication":"CREDITO",
         "installment":1,
         "installmentValue":100.00,
         "total":100.00
      },
      {
         "cardBrand":"Hipercard",
         "cardApplication":"CREDITO",
         "installment":2,
         "installmentValue":50.00,
         "total":100.00
      },
      {
         "cardBrand":"Hipercard",
         "cardApplication":"CREDITO",
         "installment":3,
         "installmentValue":33.34,
         "total":100.02
      },
      {
         "cardBrand":"Hipercard",
         "cardApplication":"CREDITO",
         "installment":4,
         "installmentValue":26.50,
         "total":106.00
      },
      {
         "cardBrand":"Hipercard",
         "cardApplication":"CREDITO",
         "installment":5,
         "installmentValue":21.60,
         "total":108.00
      },
      {
         "cardBrand":"Hipercard",
         "cardApplication":"CREDITO",
         "installment":6,
         "installmentValue":18.33,
         "total":109.98
      },
      {
         "cardBrand":"Hipercard",
         "cardApplication":"CREDITO",
         "installment":7,
         "installmentValue":16.00,
         "total":112.00
      },
      {
         "cardBrand":"Hipercard",
         "cardApplication":"CREDITO",
         "installment":8,
         "installmentValue":14.25,
         "total":114.00
      },
      {
         "cardBrand":"Hipercard",
         "cardApplication":"CREDITO",
         "installment":9,
         "installmentValue":12.88,
         "total":115.92
      },
      {
         "cardBrand":"Hipercard",
         "cardApplication":"CREDITO",
         "installment":10,
         "installmentValue":11.80,
         "total":118.00
      },
      {
         "cardBrand":"Hipercard",
         "cardApplication":"CREDITO",
         "installment":11,
         "installmentValue":10.90,
         "total":119.90
      },
      {
         "cardBrand":"Hipercard",
         "cardApplication":"CREDITO",
         "installment":12,
         "installmentValue":10.16,
         "total":121.92
      },
      {
         "cardBrand":"EloCredit",
         "cardApplication":"DEBITO",
         "installment":1,
         "installmentValue":100.00,
         "total":100.00
      },
      {
         "cardBrand":"EloCredit",
         "cardApplication":"CREDITO",
         "installment":1,
         "installmentValue":100.00,
         "total":100.00
      },
      {
         "cardBrand":"EloCredit",
         "cardApplication":"CREDITO",
         "installment":2,
         "installmentValue":50.00,
         "total":100.00
      },
      {
         "cardBrand":"EloCredit",
         "cardApplication":"CREDITO",
         "installment":3,
         "installmentValue":33.34,
         "total":100.02
      },
      {
         "cardBrand":"EloCredit",
         "cardApplication":"CREDITO",
         "installment":4,
         "installmentValue":26.50,
         "total":106.00
      },
      {
         "cardBrand":"EloCredit",
         "cardApplication":"CREDITO",
         "installment":5,
         "installmentValue":21.60,
         "total":108.00
      },
      {
         "cardBrand":"EloCredit",
         "cardApplication":"CREDITO",
         "installment":6,
         "installmentValue":18.33,
         "total":109.98
      },
      {
         "cardBrand":"EloCredit",
         "cardApplication":"CREDITO",
         "installment":7,
         "installmentValue":16.00,
         "total":112.00
      },
      {
         "cardBrand":"EloCredit",
         "cardApplication":"CREDITO",
         "installment":8,
         "installmentValue":14.25,
         "total":114.00
      },
      {
         "cardBrand":"EloCredit",
         "cardApplication":"CREDITO",
         "installment":9,
         "installmentValue":12.88,
         "total":115.92
      },
      {
         "cardBrand":"EloCredit",
         "cardApplication":"CREDITO",
         "installment":10,
         "installmentValue":11.80,
         "total":118.00
      },
      {
         "cardBrand":"EloCredit",
         "cardApplication":"CREDITO",
         "installment":11,
         "installmentValue":10.90,
         "total":119.90
      },
      {
         "cardBrand":"EloCredit",
         "cardApplication":"CREDITO",
         "installment":12,
         "installmentValue":10.16,
         "total":121.92
      },
      {
         "cardBrand":"Hiper",
         "cardApplication":"CREDITO",
         "installment":1,
         "installmentValue":100.00,
         "total":100.00
      },
      {
         "cardBrand":"Hiper",
         "cardApplication":"CREDITO",
         "installment":2,
         "installmentValue":50.00,
         "total":100.00
      },
      {
         "cardBrand":"Hiper",
         "cardApplication":"CREDITO",
         "installment":3,
         "installmentValue":33.34,
         "total":100.02
      },
      {
         "cardBrand":"Hiper",
         "cardApplication":"CREDITO",
         "installment":4,
         "installmentValue":26.50,
         "total":106.00
      },
      {
         "cardBrand":"Hiper",
         "cardApplication":"CREDITO",
         "installment":5,
         "installmentValue":21.60,
         "total":108.00
      },
      {
         "cardBrand":"Hiper",
         "cardApplication":"CREDITO",
         "installment":6,
         "installmentValue":18.33,
         "total":109.98
      },
      {
         "cardBrand":"Hiper",
         "cardApplication":"CREDITO",
         "installment":7,
         "installmentValue":16.00,
         "total":112.00
      },
      {
         "cardBrand":"Hiper",
         "cardApplication":"CREDITO",
         "installment":8,
         "installmentValue":14.25,
         "total":114.00
      },
      {
         "cardBrand":"Hiper",
         "cardApplication":"CREDITO",
         "installment":9,
         "installmentValue":12.88,
         "total":115.92
      },
      {
         "cardBrand":"Hiper",
         "cardApplication":"CREDITO",
         "installment":10,
         "installmentValue":11.80,
         "total":118.00
      },
      {
         "cardBrand":"Hiper",
         "cardApplication":"CREDITO",
         "installment":11,
         "installmentValue":10.90,
         "total":119.90
      },
      {
         "cardBrand":"Hiper",
         "cardApplication":"CREDITO",
         "installment":12,
         "installmentValue":10.16,
         "total":121.92
      },
      {
         "cardBrand":"CabalCredit",
         "cardApplication":"CREDITO",
         "installment":1,
         "installmentValue":100.00,
         "total":100.00
      },
      {
         "cardBrand":"CabalCredit",
         "cardApplication":"CREDITO",
         "installment":2,
         "installmentValue":50.00,
         "total":100.00
      },
      {
         "cardBrand":"CabalCredit",
         "cardApplication":"CREDITO",
         "installment":3,
         "installmentValue":33.34,
         "total":100.02
      },
      {
         "cardBrand":"CabalCredit",
         "cardApplication":"CREDITO",
         "installment":4,
         "installmentValue":26.50,
         "total":106.00
      },
      {
         "cardBrand":"CabalCredit",
         "cardApplication":"CREDITO",
         "installment":5,
         "installmentValue":21.60,
         "total":108.00
      },
      {
         "cardBrand":"CabalCredit",
         "cardApplication":"CREDITO",
         "installment":6,
         "installmentValue":18.33,
         "total":109.98
      },
      {
         "cardBrand":"CabalCredit",
         "cardApplication":"CREDITO",
         "installment":7,
         "installmentValue":16.00,
         "total":112.00
      },
      {
         "cardBrand":"CabalCredit",
         "cardApplication":"CREDITO",
         "installment":8,
         "installmentValue":14.25,
         "total":114.00
      },
      {
         "cardBrand":"CabalCredit",
         "cardApplication":"CREDITO",
         "installment":9,
         "installmentValue":12.88,
         "total":115.92
      },
      {
         "cardBrand":"CabalCredit",
         "cardApplication":"CREDITO",
         "installment":10,
         "installmentValue":11.80,
         "total":118.00
      },
      {
         "cardBrand":"CabalCredit",
         "cardApplication":"CREDITO",
         "installment":11,
         "installmentValue":10.90,
         "total":119.90
      },
      {
         "cardBrand":"CabalCredit",
         "cardApplication":"CREDITO",
         "installment":12,
         "installmentValue":10.16,
         "total":121.92
      },
      {
         "cardBrand":"VisaElectron",
         "cardApplication":"DEBITO",
         "installment":1,
         "installmentValue":100.00,
         "total":100.00
      },
      {
         "cardBrand":"Maestro",
         "cardApplication":"DEBITO",
         "installment":1,
         "installmentValue":100.00,
         "total":100.00
      },
      {
         "cardBrand":"EloDebit",
         "cardApplication":"DEBITO",
         "installment":1,
         "installmentValue":100.00,
         "total":100.00
      },
      {
         "cardBrand":"CabalDebit",
         "cardApplication":"DEBITO",
         "installment":1,
         "installmentValue":100.00,
         "total":100.00
      }
   ]
}

Getting transactions list

You can get all transactions by submitting a GET request to http://localhost:12030/transaction/receipt/all.

{
   "content":[
      {
         "transactionId":1,
         "paymentStatus":"FAILED",
         "cardApplication":"CREDITO"
      },
      {
         "transactionId":2,
         "paymentStatus":"FAILED",
         "cardApplication":"CREDITO"
      },
      {
         "transactionId":3,
         "paymentStatus":"FAILED",
         "cardApplication":"CREDITO"
      },
      {
         "transactionId":4,
         "paymentStatus":"FAILED",
         "cardApplication":"CREDITO"
      },
      {
         "transactionId":5,
         "paymentStatus":"FAILED",
         "cardApplication":"CREDITO"
      },
      {
         "transactionId":6,
         "paymentStatus":"FAILED",
         "cardApplication":"CREDITO"
      },
      {
         "transactionId":7,
         "paymentStatus":"FAILED",
         "cardApplication":"CREDITO"
      },
      {
         "transactionId":8,
         "paymentStatus":"FAILED",
         "cardApplication":"CREDITO"
      },
      {
         "transactionId":9,
         "paymentStatus":"FAILED",
         "cardApplication":"CREDITO"
      },
      {
         "transactionId":10,
         "paymentStatus":"FAILED",
         "cardApplication":"CREDITO"
      }
   ],
   "pageable":{
      "sort":{
         "sorted":true,
         "unsorted":false,
         "empty":false
      },
      "offset":0,
      "pageSize":10,
      "pageNumber":0,
      "paged":true,
      "unpaged":false
   },
   "last":false,
   "totalPages":2,
   "totalElements":16,
   "size":10,
   "number":0,
   "sort":{
      "sorted":true,
      "unsorted":false,
      "empty":false
   },
   "numberOfElements":10,
   "first":true,
   "empty":false
}

All transactions are divided by pages. A GET request to http://localhost:12030/transaction/receipt/all will fetch the first page with ten transactions by default. You can access other pages by submitting a GET request to http://localhost:12030/transaction/receipt/all?page=1 where the number after page= is the page you want to access. However, there are three things you must be aware of: the first one is the page numbering (the first page is the page zero, the second page is page one, the third page is the page two, and so on), the second thing is which page you want to fetch (by the end of the response, there is a field named totalPages which says how many pages you can access. If you enter a number greater than or equal to totalPages, no transactions will be brought) and the last thing is in case you don’t enter any number (the first page will be fetched - page zero).

Example of submitting a request to http://localhost:12030/transaction/receipt/all?page=1 (fetching page two).

{
   "content":[
      {
         "transactionId":11,
         "paymentStatus":"SUCCESS",
         "nsu":"000049465298",
         "cardHiddenPan":"523421******1836",
         "authorizationCode":"445286",
         "cardProductName":"MASTERCARD",
         "cardApplication":"CREDITO"
      },
      {
         "transactionId":12,
         "paymentStatus":"FAILED",
         "cardApplication":"CREDITO"
      },
      {
         "transactionId":13,
         "paymentStatus":"CANCELED",
         "nsu":"000049465605",
         "nsuOriginal":"000049465298",
         "cardHiddenPan":"523421******1836",
         "authorizationCode":"445286",
         "cardProductName":"MASTERCARD",
         "cardApplication":"CREDITO"
      },
      {
         "transactionId":14,
         "paymentStatus":"FAILED",
         "cardApplication":"CREDITO"
      },
      {
         "transactionId":15,
         "paymentStatus":"FAILED",
         "cardApplication":"CREDITO"
      },
      {
         "transactionId":16,
         "paymentStatus":"FAILED",
         "cardApplication":"CREDITO"
      }
   ],
   "pageable":{
      "sort":{
         "sorted":true,
         "unsorted":false,
         "empty":false
      },
      "offset":10,
      "pageSize":10,
      "pageNumber":1,
      "paged":true,
      "unpaged":false
   },
   "last":true,
   "totalPages":2,
   "totalElements":16,
   "size":10,
   "number":1,
   "sort":{
      "sorted":true,
      "unsorted":false,
      "empty":false
   },
   "numberOfElements":6,
   "first":false,
   "empty":false
}

Example of submitting a request to http://localhost:12030/transaction/receipt/all?page=3 (trying to access a page which its number is greater than or equal to totalPages value).

{
   "content":[

   ],
   "pageable":{
      "sort":{
         "unsorted":false,
         "sorted":true,
         "empty":false
      },
      "offset":30,
      "pageSize":10,
      "pageNumber":3,
      "paged":true,
      "unpaged":false
   },
   "last":true,
   "totalPages":2,
   "totalElements":16,
   "size":10,
   "number":3,
   "sort":{
      "unsorted":false,
      "sorted":true,
      "empty":false
   },
   "numberOfElements":0,
   "first":false,
   "empty":true
}

Example of submitting a request to http://localhost:12030/transaction/receipt/all?page= (not entering a number).

{
   "content":[
      {
         "transactionId":1,
         "paymentStatus":"FAILED",
         "cardApplication":"CREDITO"
      },
      {
         "transactionId":2,
         "paymentStatus":"FAILED",
         "cardApplication":"CREDITO"
      },
      {
         "transactionId":3,
         "paymentStatus":"FAILED",
         "cardApplication":"CREDITO"
      },
      {
         "transactionId":4,
         "paymentStatus":"FAILED",
         "cardApplication":"CREDITO"
      },
      {
         "transactionId":5,
         "paymentStatus":"FAILED",
         "cardApplication":"CREDITO"
      },
      {
         "transactionId":6,
         "paymentStatus":"FAILED",
         "cardApplication":"CREDITO"
      },
      {
         "transactionId":7,
         "paymentStatus":"FAILED",
         "cardApplication":"CREDITO"
      },
      {
         "transactionId":8,
         "paymentStatus":"FAILED",
         "cardApplication":"CREDITO"
      },
      {
         "transactionId":9,
         "paymentStatus":"FAILED",
         "cardApplication":"CREDITO"
      },
      {
         "transactionId":10,
         "paymentStatus":"FAILED",
         "cardApplication":"CREDITO"
      }
   ],
   "pageable":{
      "sort":{
         "unsorted":false,
         "sorted":true,
         "empty":false
      },
      "offset":0,
      "pageSize":10,
      "pageNumber":0,
      "paged":true,
      "unpaged":false
   },
   "last":false,
   "totalPages":2,
   "totalElements":16,
   "size":10,
   "number":0,
   "sort":{
      "unsorted":false,
      "sorted":true,
      "empty":false
   },
   "numberOfElements":10,
   "first":true,
   "empty":false
}

You can also choose how many transactions you want per page. Just submit a GET request to http://localhost:12030/transaction/receipt/all?size=8 where the number after size= is the amount of transactions per page. The default number is ten.

Example of submitting a request to http://localhost:12030/transaction/receipt/all?size=8 (requesting eight transactions per page).

{
   "content":[
      {
         "transactionId":1,
         "paymentStatus":"FAILED",
         "cardApplication":"CREDITO"
      },
      {
         "transactionId":2,
         "paymentStatus":"FAILED",
         "cardApplication":"CREDITO"
      },
      {
         "transactionId":3,
         "paymentStatus":"FAILED",
         "cardApplication":"CREDITO"
      },
      {
         "transactionId":4,
         "paymentStatus":"FAILED",
         "cardApplication":"CREDITO"
      },
      {
         "transactionId":5,
         "paymentStatus":"FAILED",
         "cardApplication":"CREDITO"
      },
      {
         "transactionId":6,
         "paymentStatus":"FAILED",
         "cardApplication":"CREDITO"
      },
      {
         "transactionId":7,
         "paymentStatus":"FAILED",
         "cardApplication":"CREDITO"
      },
      {
         "transactionId":8,
         "paymentStatus":"FAILED",
         "cardApplication":"CREDITO"
      }
   ],
   "pageable":{
      "sort":{
         "sorted":true,
         "unsorted":false,
         "empty":false
      },
      "offset":0,
      "pageSize":8,
      "pageNumber":0,
      "paged":true,
      "unpaged":false
   },
   "last":false,
   "totalPages":2,
   "totalElements":16,
   "size":8,
   "number":0,
   "sort":{
      "sorted":true,
      "unsorted":false,
      "empty":false
   },
   "numberOfElements":8,
   "first":true,
   "empty":false
}

Example of submitting a request to http://localhost:12030/transaction/receipt/all?size= (not entering a number).

{
   "content":[
      {
         "transactionId":1,
         "paymentStatus":"FAILED",
         "cardApplication":"CREDITO"
      },
      {
         "transactionId":2,
         "paymentStatus":"FAILED",
         "cardApplication":"CREDITO"
      },
      {
         "transactionId":3,
         "paymentStatus":"FAILED",
         "cardApplication":"CREDITO"
      },
      {
         "transactionId":4,
         "paymentStatus":"FAILED",
         "cardApplication":"CREDITO"
      },
      {
         "transactionId":5,
         "paymentStatus":"FAILED",
         "cardApplication":"CREDITO"
      },
      {
         "transactionId":6,
         "paymentStatus":"FAILED",
         "cardApplication":"CREDITO"
      },
      {
         "transactionId":7,
         "paymentStatus":"FAILED",
         "cardApplication":"CREDITO"
      },
      {
         "transactionId":8,
         "paymentStatus":"FAILED",
         "cardApplication":"CREDITO"
      },
      {
         "transactionId":9,
         "paymentStatus":"FAILED",
         "cardApplication":"CREDITO"
      },
      {
         "transactionId":10,
         "paymentStatus":"FAILED",
         "cardApplication":"CREDITO"
      }
   ],
   "pageable":{
      "sort":{
         "unsorted":false,
         "sorted":true,
         "empty":false
      },
      "offset":0,
      "pageSize":10,
      "pageNumber":0,
      "paged":true,
      "unpaged":false
   },
   "last":false,
   "totalPages":2,
   "totalElements":16,
   "size":10,
   "number":0,
   "sort":{
      "unsorted":false,
      "sorted":true,
      "empty":false
   },
   "numberOfElements":10,
   "first":true,
   "empty":false
}

You can put page and size in the same request. Just add the symbol & between both of them (it doesn’t matter which one comes first).

Example of submitting a request to http://localhost:12030/transaction/receipt/all?size=8&page=0.

{
   "content":[
      {
         "transactionId":1,
         "paymentStatus":"FAILED",
         "cardApplication":"CREDITO"
      },
      {
         "transactionId":2,
         "paymentStatus":"FAILED",
         "cardApplication":"CREDITO"
      },
      {
         "transactionId":3,
         "paymentStatus":"FAILED",
         "cardApplication":"CREDITO"
      },
      {
         "transactionId":4,
         "paymentStatus":"FAILED",
         "cardApplication":"CREDITO"
      },
      {
         "transactionId":5,
         "paymentStatus":"FAILED",
         "cardApplication":"CREDITO"
      },
      {
         "transactionId":6,
         "paymentStatus":"FAILED",
         "cardApplication":"CREDITO"
      },
      {
         "transactionId":7,
         "paymentStatus":"FAILED",
         "cardApplication":"CREDITO"
      },
      {
         "transactionId":8,
         "paymentStatus":"FAILED",
         "cardApplication":"CREDITO"
      }
   ],
   "pageable":{
      "sort":{
         "sorted":true,
         "unsorted":false,
         "empty":false
      },
      "offset":0,
      "pageSize":8,
      "pageNumber":0,
      "paged":true,
      "unpaged":false
   },
   "last":false,
   "totalPages":2,
   "totalElements":16,
   "size":8,
   "number":0,
   "sort":{
      "sorted":true,
      "unsorted":false,
      "empty":false
   },
   "numberOfElements":8,
   "first":true,
   "empty":false
}

If you want to check only the successful transactions, submit a GET request to http://localhost:12030/transaction/receipt/success (you can apply the page and size filter the same way it was explained previously).

Example of submitting a request to http://localhost:12030/transaction/receipt/success.

{
   "content":[
      {
         "transactionId":11,
         "paymentStatus":"SUCCESS",
         "nsu":"000049465298",
         "cardHiddenPan":"523421******1836",
         "authorizationCode":"445286",
         "cardProductName":"MASTERCARD",
         "cardApplication":"CREDITO"
      }
   ],
   "pageable":{
      "sort":{
         "unsorted":false,
         "sorted":true,
         "empty":false
      },
      "offset":0,
      "pageSize":10,
      "pageNumber":0,
      "paged":true,
      "unpaged":false
   },
   "last":true,
   "totalPages":1,
   "totalElements":1,
   "size":10,
   "number":0,
   "sort":{
      "unsorted":false,
      "sorted":true,
      "empty":false
   },
   "numberOfElements":1,
   "first":true,
   "empty":false
}

If you want to check only the canceled transactions, submit a GET request to http://localhost:12030/transaction/receipt/canceled (you can apply the page and size filter the same way it was explained previously).

Example of submitting a request to http://localhost:12030/transaction/receipt/canceled.

{
   "content":[
      {
         "transactionId":13,
         "paymentStatus":"CANCELED",
         "nsu":"000049465605",
         "nsuOriginal":"000049465298",
         "cardHiddenPan":"523421******1836",
         "authorizationCode":"445286",
         "cardProductName":"MASTERCARD",
         "cardApplication":"CREDITO"
      }
   ],
   "pageable":{
      "sort":{
         "unsorted":false,
         "sorted":true,
         "empty":false
      },
      "offset":0,
      "pageSize":10,
      "pageNumber":0,
      "paged":true,
      "unpaged":false
   },
   "last":true,
   "totalPages":1,
   "totalElements":1,
   "size":10,
   "number":0,
   "sort":{
      "unsorted":false,
      "sorted":true,
      "empty":false
   },
   "numberOfElements":1,
   "first":true,
   "empty":false
}

By the end of each response, you will see some information about the response. Some of them are explained below:

• size: quantity of transactions per page (it is always equal to pageSize).
• number: number of the page (it is always equal to pageNumber).
• last: if it’s true, it means that that page is the last page. If it’s false, it means that that page is not the last page.
• totalPages: total of pages.
• totalElements: total of transactions.
• numberOfElements: number of transactions in the page you requested.

Clear data requesting flow

The clear data requesting flow works apart from the transaction flow. Therefore, it’s only possible to ask the user for data when there is no transaction going on and it’s only possible to start a transaction when no clear data is being requested. If you attempt to request any data during a transaction, or start a transaction while data is being requested, the API will return a message saying that there’s a request being processed.

{
   "status":1,
   "actions":[

   ],
   "message":"JÁ EXISTE UMA REQUISIÇÃO SENDO PROCESSADA"
}

Clear data requesting flowchart

Initiating the clear data requesting flow

Send a POST request to http://localhost:12030/requestClearData/start to ask for the user’s data. You have to specify on
the request body:

• The data type (Personal Id, birthday, etc).
• The minimum size of the data.
• The maximum size of the data.
• The time out (the time in seconds the user has to provide the data).

Example of a request to http://localhost:12030/requestClearData/start.

{
   "messageType":"SOLICITAR_DOCUMENTO_CPF",
   "minSize":11,
   "maxSize":11,
   "timeOut":30
}

There are predefined words to set in messageType (it’s not possible to set any kind of text). The predefined words are indicated below:

• SOLICITAR_DDD
• REDIGITE_DDD
• SOLICITAR_TELEFONE
• REDIGITE_TELEFONE
• SOLICITAR_TELEFONE_COM_DDD
• REDIGITAR_TELEFONE_COM_DDD
• SOLICITAR_DOCUMENTO_CPF
• REDIGITE_DOCUMENTO_CPF
• SOLICITAR_DOCUMENTO_RG
• REDIGITE_DOCUMENTO_RG
• SOLICITAR_ULTIMOS_4_DIGITOS
• SOLICITAR_CVV
• SOLICITAR_DOCUMENTO_CNPJ
• REDIGITE_DOCUMENTO_CNPJ
• SOLICITAR_DATA_DDMMAAAA
• SOLICITAR_DATA_DDMMAA
• SOLICITAR_DATA_DDMM
• SOLICITAR_DIA
• SOLICITAR_MES
• SOLICITAR_ANO_AA
• SOLICITAR_ANO_AAAA
• SOLICITAR_DATA_NASCIMENTO_DDMMAAAA
• SOLICITAR_DATA_NASCIMENTO_DDMMAA
• SOLICITAR_DATA_NASCIMENTO_DDMM
• SOLICITAR_DATA_NASCIMENTO_DD
• SOLICITAR_DATA_NASCIMENTO_MM
• SOLICITAR_DATA_NASCIMENTO_AA
• SOLICITAR_DATA_NASCIMENTO_AAAA
• SOLICITAR_IDENTIFICACAO
• SOLICITAR_CODIGO_FIDELIDADE
• SOLICITAR_IDENTIFICACAO_DA_MESA
• SOLICITAR_QUANTIDADE_DE_PESSOAS
• SOLICITAR_QUANTIDADE
• SOLICITAR_IDENTIFICACAO_DA_BOMBA
• SOLICITAR_IDENTIFICACAO_DA_VAGA
• SOLICITAR_IDENTIFICACAO_DO_GUICHE
• SOLICITAR_IDENTIFICACAO_DO_VENDEDOR
• SOLICITAR_IDENTIFICACAO_DO_GARCOM
• SOLICITAR_NOTA_DO_ATENDIMENTO
• SOLICITAR_NUMERO_DA_NOTA_FISCAL
• SOLICITAR_NUMERO_DA_COMANDA
• SOLICITAR_PLACA_DO_VEICULO
• SOLICITAR_QUILOMETRAGEM
• SOLICITAR_QUILOMETRAGEM_INICIAL
• SOLICITAR_QUILOMETRAGEM_FINAL
• SOLICITAR_PORCENTAGEM
• SOLICITAR_PESQUISA_DE_SATISFACAO
• SOLICITAR_AVALIACAO_DO_ATENDIMENTO
• SOLICITAR_TOKEN
• SOLICITAR_NUMERO_DO_CARTAO
• SOLICITAR_NUMERO_DE_PARCELAS
• SOLICITAR_CODIGO_DO_PLANO
• SOLICITAR_CODIGO_DO_PRODUTO

The API response will return the following message after you’ve sent a requisition to http://localhost:12030/requestClearData/start:

{
   "status":4,
   "actions":[
      "/requestClearData/getData",
      "/requestClearData/end"
   ],
   "message":"DIGITE O CPF"
}

• The status field shows the current flow code.
• The actions field shows what other endpoints you can access (you can access those endpoints even when the user is entering some data on the pinpad).
• The message field contains the text that will be displayed on the pinpad and it changes according to the value in messageType field.

Getting the data

Send a GET request to http://localhost:12030/requestClearData/getData to check what the user has entered on the pinpad. You may get different responses from the API depending on the moment you’ve sent this request:

• If you send a request to http://localhost:12030/requestClearData/getData while the user is entering some data on the pinpad, the API will return the same response as when you send a request to http://localhost:12030/requestClearData/start.

Response of a GET request to http://localhost:12030/requestClearData/getData while the user is entering data on the pinpad.

{
   "status":4,
   "actions":[
      "/requestClearData/getData",
      "/requestClearData/end"
   ],
   "message":"DIGITE O CPF"
}

• If you send a request to http://localhost:12030/requestClearData/getData after the user has entered the data on the pinpad, the API response will contain the data entered by the user (on the filed data).

Response of a GET request to http://localhost:12030/requestClearData/getData after the user has entered the data on the pinpad.

{
   "status":4,
   "actions":[
      "/requestClearData/request",
      "/requestClearData/end"
   ],
   "message":"OK",
   "clearDataResponseDTO":{
      "data":"12345678901",
      "responseCode":0
   }
}

• If you send a request to http://localhost:12030/requestClearData/getData after the requisition time is up, the API response will contain a message saying that the request timed out.

Response of a GET request to http://localhost:12030/requestClearData/getData after the requisition time is up.

{
   "status":4,
   "actions":[
      "/requestClearData/request",
      "/requestClearData/end"
   ],
   "message":"Esgotado o tempo máximo estipulado para a operação.",
   "clearDataResponseDTO":{
      "data":"",
      "responseCode":12
   }
}

• If you send a request to http://localhost:12030/requestClearData/getData after the user pressed the canceling button on the pinpad, the API response will contain a message saying that the user canceled the operation.

Response of a GET request to http://localhost:12030/requestClearData/getData after the user preesed the canceling button on the pinpad*.

{
   "status":4,
   "actions":[
      "/requestClearData/request",
      "/requestClearData/end"
   ],
   "message":"Operação cancelada pelo operador.",
   "clearDataResponseDTO":{
      "data":"",
      "responseCode":13
   }
}

Requesting more data

Send a POST request to http://localhost:12030/requestClearData/request to ask the user for more data. You have to specify the same fields as you would when sending a request to http://localhost:12030/requestClearData/start.

Example of a request to http://localhost:12030/requestClearData/request.

{
   "messageType":"SOLICITAR_DOCUMENTO_CPF",
   "minSize":11,
   "maxSize":11,
   "timeOut":30
}

Keep in mind: a requisition is sent to http://localhost:12030/requestClearData/start only in the beginning of the flow, when no other requisition was sent. If you need more than one data from the user, then send a requisition to http://localhost:12030/requestClearData/request for each new data. If you try to send a request to http://localhost:12030/requestClearData/start again, the API response will contain a message saying that there’s a requisition being processed already.

{
   "status":4,
   "actions":[

   ],
   "message":"JÁ EXISTE UMA REQUISIÇÃO SENDO PROCESSADA"
}

Finishing the clear data requesting flow

Send a GET request to http://localhost:12030/requestClearData/end to end the flow. The API will return the following message:

{
   "status":-1,
   "actions":[

   ],
   "message":"ACQIO MAIS "
}

• You can send a requisition to http://localhost:12030/requestClearData/end to end the flow or to interrupt the operation, even if the user is entering some data on the pinpad.