API Acqio Mais
Este documento abordará os conceitos básicos de como receber um pagamento usando a API Acqio Mais.
Requisitos
Você precisará de um computador com Windows 7+ conectado à Internet, o software Acqio Mais instalado e um pinpad corretamente conectado e configurado.
Iniciando uma transação
Para iniciar uma transação, verifique se o aplicativo Acqio Mais está em funcionamento e envie uma requisição POST para http://localhost:12030/api/transaction/start contendo um JSON semelhante aos exemplos abaixo:
{
"installment": 3,
"cardApplication": "CREDITO",
"value": 0.03,
"tenantPlanMode": "DISABLED",
"qrApplication": "NENHUM"
}
{
"installment": 1,
"cardApplication": "DEBITO",
"value": 0.03,
"tenantPlanMode": "DISABLED",
"qrApplication": "NENHUM"
}
- installment: quantidade de parcelas da transação. Transações de débito sempre terão o valor do “installment” igual a 1. O valor do “installment” não pode ser zero.
- cardApplication: definição se a transação será de DEBITO ou CREDITO.
- value: valor da transação. Usar o ponto (.) como separador decimal.
- tenantPlanMode: indica qual se a transação terá algum acréscimo. O preenchimento deste campo é obrigatório e deve ser preenchido com um dos valores abaixo:
- DISABLED: Desativar a função de cálculo de acréscimo.
- TENANT: O cálculo será feito com base no plano “Lojista e Portador”.
- MDR_0: O cálculo será feito de forma que o custo da transação seja repassado ao portador do cartão.
- qrApplication: indica se a transação será paga por Qr Code ou por Pix.
- Para pagar utilizando Qr Code, preencha com ELO_BRCODE_DEBITO para transações de débito ou ELO_BRCODE_CREDITO para transações de crédito.
- Para pagar utilizando Pix, preencha com PIX_DEBITO.
- Parar pagar utilizando cartão, preencha com NENHUM.
O aplicativo iniciará a transação, retornará o status 1 (PROCESSING) junto ao ID da transação e cuidará de toda a comunicação entre o pinpad e o host do adquirente. Um exemplo da resposta da API deve ser semelhante ao exemplo abaixo:
{
"id": 1,
"status": 1,
"actions": [
"/transaction/status",
"/transaction/abort"
],
"message": "ACQIO MAIS"
}
Se já houver uma transação em andamento, a resposta da API deverá ser semelhante ao exemplo abaixo:
{
"status": -1,
"actions": [
"/transaction/status",
"/transaction/abort"
],
"message": "JÁ EXISTE UMA TRANSAÇÃO SENDO PROCESSADA"
}
Se o pinpad não estiver configurado ou estiver desconectado, a resposta da API deverá ser semelhante ao exemplo abaixo:
{
"id":1,
"status":1,
"actions":[
"/transaction/status",
"/transaction/abort"
],
"message":"NÃO FOI POSSIVEL SE COMUNICAR COM O PINPAD.[COMXX]"
}
Acompanhando uma transação em andamento
O aplicativo que consome a API agora deve fazer requisições GET em loop ao endpoint http://localhost:12030/api/transaction/status para acompanhar o fluxo da transação até obter uma resposta com status 2 (WAITING CHARGE). A resposta da API para essa requisição deve ser semelhante aos exemplos abaixo:
Status da transação igual a 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
}
Status da transação igual a 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"
}
}
Solicitação da senha
Quando a API retornar o status 2 (WAITING CHARGE), envie uma requisição GET para http://localhost:12030/api/transaction/charge/{installment} onde o parâmetro {installment} deve ser substituído pelo número de parcelas da transação (mesmo número informado no campo installment quando a requisição POST para http://localhost:12030/api/transaction/start foi feita).
Exemplo de requisição para http://localhost:12030/api/transaction/start.
{
"installment": 3,
"cardApplication": "CREDITO",
"value": 0.03,
"tenantPlanMode": "DISABLED",
"qrApplication": "NENHUM"
}
Logo, a requisição deve ser feita para http://localhost:12030/api/transaction/charge/3.
Após você enviar uma requisição para http://localhost:12030/api/transaction/charge/{installment}, a API irá retornar uma resposta com o status 3 (PROCESSING_CHARGE). A resposta da API a essa requisição deve ser semelhante ao exemplo abaixo:
{
"id":2,
"status":3,
"actions":[
"/transaction/abort"
],
"message":"SELECIONADO: Credito Nubank "
}
Nesse momento, a senha estará sendo solicitada pelo pinpad.
Uma requisição para http://localhost:12030/api/transaction/status retornará uma resposta da API semelhante ao exemplo abaixo:
{
"id":2,
"status":3,
"actions":[
"/transaction/abort"
],
"message":"SOLICITE A SENHA "
}
Fim da transação
Após a senha ser inserida, a transação será processada e a API poderá retornar uma resposta de sucesso ou de erro. Acompanhe o status da transação até que a API retorne uma resposta com o status 0 (SUCCESS) que significa que a transação foi concluída com sucesso e o fluxo transacional se encerrou. Segue abaixo as respostas que a API retorna após a senha ser inserida no pinpad:
{
"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
}
Interromper uma transação em andamento
Em algum momento após o início de uma transação, o aplicativo pode decidir cancelar a operação atual enviando uma requisição GET para http://localhost:12030/transaction/abort, isso interromperá a operação atual e fará com que a API retorne ao estado inativo. Um exemplo da resposta da API deve ser semelhante ao exemplo abaixo:
Observação: Nesse caso, o status 0 (SUCESSO) significa que a requisição de cancelamento foi bem-sucedida.
{
"id":1,
"status":0,
"actions":[
],
"message":" CANCELADO PELO OPERADOR "
}
Obtendo do recibo do comerciante e do cliente
Enquanto a aplicação estiver fazendo requisições GET para http://localhost:12030/transaction/status, o Acqio Mais pode responder com um status 0 (SUCCESS), isso significa que a transação foi concluída com êxito e o aplicativo agora pode fazer uma requisição GET para http://localhost:12030/transaction/receipt/{id} para obter o recibo do comerciante e do cliente. O ID é aquele que a aplicação recebeu quando iniciou a transação. O recibo é uma texto delimitado com quebra de linha no final de cada informação. A resposta da API deve ser semelhante ao exemplo abaixo:
Observação: Se nenhum ID for fornecido, a API Acqio Mais retornará o recibo da última transação bem-sucedida.
{
"transactionId": 89,
"status": 0,
"paymentStatus": "SUCCESS",
"cardApplication": "CREDITO",
"cardHiddenPan": "410863******3263", "authorizationCode": "372568", "cardProductName": "VISA", "nsu": "000314030029", "nsuOriginal": "000314030030", //OPTIONAL "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:072575917805\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\nTI:00000000\nAC:JR85E1BLASMR3JKC\nAID:5NON91IT0RAQ56\nTX:61406035\nSN:AA0000123\n",
"merchantHtml": "...", "clientHtml": "..."
}
Observação: O último recebimento da transação pode ser um recibo de estorno.
{
"transactionId": 89,
"status": 0,
"paymentStatus": "CANCELED",
"cardApplication": "CREDITO",
"cardHiddenPan": "410863******3263", "authorizationCode": "372568", "cardProductName": "VISA", "nsu": "000314030029", "nsuOriginal": "000314030030", //OPTIONAL "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\nCREDITO\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:072575917804\n",
"merchantHtml": "...", "clientHtml": "..."
}
Observação: Se o ID fornecido estiver incorreto ou não puder ser encontrado no banco de dados, o aplicativo receberá uma resposta semelhante ao exemplo abaixo.
{
"transactionId": -1,
"status": -2,
"merchant": "",
"client": ""
}
Observação: Se nenhum ID for fornecido, a API Acqio Mais retornará o recibo da última transação bem-sucedida.
Cancelando uma transação bem-sucedida
Esta operação só pode ser executada no mesmo dia em que a transação ocorreu, se for realizada uma tentativa de cancelamento de uma operação no dia seguinte a realização da transação, esta operação resultara em falha. Para reverter uma transação, o aplicativo deve fazer uma requisição GET para http://localhost:12030/transaction/revert/{id}, em que o ID é aquele que o aplicativo recebeu quando iniciou a transação. A resposta do cancelamento deve ser semelhante aos exemplos abaixo:
{
"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: A mensagem abaixo pode aparacer quando o pinpad estiver desconectado ou quando o pinpad não estiver apropriadamente configurado no Acqio Mais.
{
"id": -1,
"status": -1,
"actions": [
"/transaction/status",
"/transaction/abort"
],
"message": "Não foi possivel se comunicar com o Pinpad.[COMXX]"
}
Tabela de status
| CODIGO | DESCRIÇÃO |
|---|---|
| -2 | NOT FOUND |
| -1 | INACTIVE |
| 0 | SUCCESS |
| 1 | PROCESSING |
| 2 | WAITING CHARGE |
| 3 | PROCESSING CHARGE |
| 4 | PROCESSING CLEAR DATA |
Fluxograma de Transação
Simulador de parcelamento
A API Acqio Mais fornece um endpoint para simular o parcelamento. Para consumi-lo, faça uma requisição POST para http://localhost:12030/tenant/plan. A solicitação deve ser semelhante ao exemplo abaixo:
{
"value": 100.00
}
A API calculará as parcelas de acordo com o plano do cliente e responderá com um JSON que deve ser semelhante ao exemplo abaixo:
{
"tenantName":"YATTA SUSHI",
"InstallmentInfooList":[
{
"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
}
]
}
Obtendo lista das transações
É possível obter todas as transações enviando uma requisição GET para 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
}
As transações estão divididas por páginas. Por padrão, a requisição GET para http://localhost:12030/transaction/receipt/all retornará sempre a primeira página contendo dez transações. Logo, é possível acessar outras páginas enviando uma requisição GET para http://localhost:12030/transaction/receipt/all?page=1 onde o número depois do page= é o número da página que você quer acessar. Porém, há três pontos de atenção: o primeiro é a numeração das páginas (a primeira página é a página zero, a segunda página e a página um, a terceira página é a página dois, assim por diante), o segundo é qual página você quer buscar (no final da resposta, existe um campo chamado totalPages que mostra quantas páginas você consegue acessar. Se você digitar um número maior ou igual ao número do totalPages, não será trazido nenhuma transação) e o terceiro é caso você não informe o número da página (será trazido a primeira página - página zero).
Exemplo de resultado da requisição http://localhost:12030/transaction/receipt/all?page=1 (buscando página dois).
{
"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
}
Exemplo de resultado da requisição http://localhost:12030/transaction/receipt/all?page=3 (tentando acessar uma página que é maior ou igual ao totalPages).
{
"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
}
Exemplo de resultado da requisição http://localhost:12030/transaction/receipt/all?page= (não informando a número da página que você quer acessar).
{
"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
}
Além de trazer uma página específica, é possível escolher a quantidade de transações por página que você quer. Basta enviar uma requisição GET para http://localhost:12030/transaction/receipt/all?size=8 onde o número após o size= é a quantidade de transações por página. Caso você não informar o quantidade de transações por página, a quantidade padrão é dez.
Exemplo de resultado da requisição http://localhost:12030/transaction/receipt/all?size=8 (requisitando apenas oito transações por página).
{
"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
}
Exemplo de resultado da requisição http://localhost:12030/transaction/receipt/all?size= (não informando a quantidade de transações por página).
{
"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
}
Você consegue colocar page e size numa mesma requisição. Apenas adicione o símbolo & entre os dois (Você pode colocar tanto o page quanto o size na ordem que você quiser).
Exemplo de resultado da requisição 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
}
Para trazer apenas as transações que deram certo, envie uma requisição GET para http://localhost:12030/transaction/receipt/success (você pode aplicar o page e o size da mesma forma como foi explicado anteriormente).
Exemplo de resultado da requisição http://localhost:12030/transaction/receipt/success (trazer apenas transações que deram certo).
{
"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
}
Para trazer apenas as transações que foram canceladas, envie uma requisição GET
para http://localhost:12030/transaction/receipt/canceled (você pode aplicar o page e o size da mesma forma como foi explicado anteriormente).
Exemplo de resultado da requisição http://localhost:12030/transaction/receipt/canceled (trazer apenas transações que foram canceladas).
{
"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
}
No fim de cada resposta, você vai encontrar alguns campos com informações sobre o resultado. Abaixo está listado os mais importantes:
- size: quantidade de transações da página (será sempre igual ao pageSize).
- number: número da página (será sempre igual ao pageNumber).
- last: se for true, significa que essa é a última página. Se for false, significa que é não é a última página.
- totalPages: quantidade total de páginas.
- totalElements: quantidade total de transações.
- numberOfElements: quantidade de transações que têm na página que você requisitou.
Fluxo de solicitação de dados através do pinpad
O fluxo de solicitação de dados é separado do fluxo de transação. Logo, só é possível pedir dados para o usuário quando nenhuma transação estiver sendo processada e só é possível transacionar quando não estiver sendo solicitado nenhum dado para o usuário. Caso você solicite algum dado para o usuário enquanto uma transação estiver acontecendo, ou tente iniciar uma transação durante o fluxo de solicitação de dados, a API irá retornar uma mensagem dizendo que já existe uma requisição sendo processada.
{
"status": 1,
"actions": [],
"message": "JÁ EXISTE UMA REQUISIÇÃO SENDO PROCESSADA"
}
Fluxograma da solicitação de dados através do pinpad
Iniciando fluxo
Para solicitar um dado ao usuário, envie uma requisição POST para http://localhost:12030/requestClearData/start. No corpo da requisição, você precisa especificar:
- Tipo do dado (CPF, CNPJ, data de nascimento, etc).
- Tamanho mínimo do dado que o usuário tem que fornecer.
- Tamanho máximo do dado que o usuário tem que fornecer.
- Time out da requisição (tempo, em segundos, que o usuário tem para inserir o dado).
Exemplo do corpo da requisição para http://localhost:12030/requestClearData/start (solicitando CPF)
{
"messageType":"SOLICITAR_DOCUMENTO_CPF",
"minSize":11,
"maxSize":11,
"timeOut":30
}
Existem palavras pré-definidas para serem colocadas em messageType (a API não aceita qualquer tipo de texto). As palavras pré-definidas estão indicadas abaixo:
- 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
Ao enviar uma requisição para http://localhost:12030/requestClearData/start, a API retornará a seguinte resposta:
{
"status":4,
"actions":[
"/requestClearData/getData",
"/requestClearData/end"
],
"message":"DIGITE O CPF"
}
- O campo status mostra o código do fluxo atual;
- O campo actions mostra quais outros endpoints você pode acessar (não é necessário esperar o usuário entrar com um dado para você acessar esses endpoints);
- O campo message é o mesmo texto que aparecerá no pinpad e ele muda de acordo com o valor do messageType da requisição.
Coletando a informação digitada pelo usuário
Para pegar a informação que o usuário digitou no pinpad, envie uma requisição GET para http://localhost:12030/requestClearData/getData. Você pode receber diferentes respostas da API dependendo do momento que você enviar essa requisição:
- Caso você envie uma requisição para http://localhost:12030/requestClearData/getData enquanto o usuário digita o dado no pinpad, a resposta vai ser a mesma de quando você enviou uma requisição POST para http://localhost:12030/requestClearData/start.
Resposta da API ao enviar uma requisição GET para http://localhost:12030/requestClearData/getData enquanto o usuário digita o dado no pinpad.
{
"status":4,
"actions":[
"/requestClearData/getData",
"/requestClearData/end"
],
"message":"DIGITE O CPF"
}
- Caso você envie uma requisição para http://localhost:12030/requestClearData/getData depois que o usuário tiver digitado o dado no pinpad, a resposta vai conter a informação digitada no pinpad (no campo data).
Resposta da API ao enviar uma requisição GET para http://localhost:12030/requestClearData/getData depois que o usuário digita o dado no pinpad.
{
"status":4,
"actions":[
"/requestClearData/request",
"/requestClearData/end"
],
"message":"OK",
"clearDataResponseDTO":{
"data":"12345678901",
"responseCode":0
}
}
- Caso você envie uma requisição para http://localhost:12030/requestClearData/getData após acabar o tempo de entrada de dados no pinpad (time out), a resposta vai conter uma mensagem falando que o tempo foi excedido.
Resposta da API ao enviar uma requisição GET para http://localhost:12030/requestClearData/getData caso o tempo que o usuário tem para inserir o dado no pinpad exceder.
{
"status":4,
"actions":[
"/requestClearData/request",
"/requestClearData/end"
],
"message":"Esgotado o tempo máximo estipulado para a operação.",
"clearDataResponseDTO":{
"data":"",
"responseCode":12
}
}
- Caso você envie uma requisição para http://localhost:12030/requestClearData/getData após o usuário apertar o botão de cancelar no pinpad, a resposta vai conter uma mensagem falando que o usuário cancelou a operação.
Resposta da API ao enviar uma requisição GET para http://localhost:12030/requestClearData/getData caso o usuário cancelar a operação pelo pinpad.
{
"status":4,
"actions":[
"/requestClearData/request",
"/requestClearData/end"
],
"message":"Operação cancelada pelo operador.",
"clearDataResponseDTO":{
"data":"",
"responseCode":13
}
}
Solicitando mais dados
Para solicitar mais dados para o usuário, envie uma requisição POST para http://localhost:12030/requestClearData/request. No corpo da requisição, é necessário preencher os mesmos campos de uma requisição para http://localhost:12030/requestClearData/start.
Exemplo do corpo de uma requisição para http://localhost:12030/requestClearData/request.
{
"messageType":"SOLICITAR_DOCUMENTO_CPF",
"minSize":11,
"maxSize":11,
"timeOut":30
}
Observação: você só pode enviar uma requisição para http://localhost:12030/requestClearData/start no começo do fluxo, quando não foi feita nenhuma requisição para API ainda. Caso você queira solicitar mais dados para o usuário, faça requisições POST para http://localhost:12030/requestClearData/request. Caso você faça uma requisição para http://localhost:12030/requestClearData/start, a resposta da API vai conter a seguinte mensagem:
{
"status":4,
"actions":[
],
"message":"JÁ EXISTE UMA REQUISIÇÃO SENDO PROCESSADA"
}
Finalizando o fluxo
Para encerrar o fluxo, envie uma requisição GET para http://localhost:12030/requestClearData/end. A resposta da API vai conter a seguinte mensagem:
{
"status":-1,
"actions":[
],
"message":"ACQIO MAIS "
}
- Você pode enviar uma requisição para http://localhost:12030/requestClearData/end em qualquer momento do fluxo para terminar ou interromper a operação, mesmo se o usuário estiver digitando um dado no pinpad.