Oferecer Ame como meio de pagamento para seus clientes é muito fácil. A API Transaction é responsável por todo nosso fluxo de Vendas utilizando nossa Carteira digital, ou seja, com ela será possível oferecer múltiplos meios de forma de pagamento para o comprador que utilize a Carteira digital da Ame. Além de outras vantagens que oferecemos, como por exemplo: A possibilidade de ofertar campanhas de Cashback
Documentação Técnica API Transaction
A documentação técnica abaixo fornece informações detalhadas sobre como integrar a API Transaction da Ame. Esta documentação aborda os ambientes disponíveis, os recursos oferecidos pela API e os procedimentos necessários para realizar a integração com sucesso.Recursos da API
A API Transaction oferece os seguintes recursos:Collection
Você pode fazer o download das Collections desta API através do arquivo disponível no seguinte link:Clique aqui para fazer o download.
Ambientes
A integração com a API Transaction da Ame pode ser realizada em dois ambientes diferentes:Ambiente | Descrição | URL do Sandbox |
---|---|---|
Homologação | Ambiente destinado a realizar todos os testes necessários antes da implementação em produção. | https://api-amedigital.sensedia.com/hml/transactions/v1 |
Produção | Ambiente produtivo onde as vendas reais ocorrerão após a validação da integração. | https://api-amedigital.sensedia.com/transactions/v1 |
IMPORTANTE: Os dois ambientes (Homologação e Produção) seguem o mesmo fluxo e oferecem os mesmos retornos. Certifique-se de que sua integração esteja funcionando corretamente no ambiente de homologação antes de migrar para o ambiente de produção.
Overview sobre ordens
As ordens são eventos que permitem a execução de diversas funcionalidades relacionadas às transações dentro da Ame. Por exemplo, a criação de uma transação é realizada através da criação de uma ordem de compra.
Confira quais são as ações relacionadas às ordens:
- Obtendo o token de acesso
- Criação da ordem de compra
- Cancelamento de uma Ordem de Compra
- Callback - Aviso de pagamento
- Cancelando um pagamento
- Capturando um pagamento
- Estornando um pagamento
- Buscando um pagamento
Como criar uma ordem de compra?
A criação de uma ordem de compra dentro da Ame depende da interação com a plataforma de venda. Ou seja, a Ame Digital e o cliente que irá realizar a compra no nosso aplicativo.
Nesta criação tem duas etapas:
- Criação da ordem com base nas informações passadas pelo Sistema Parceiro;
- Pagamento da ordem de compra através da leitura do QR Code pelo cliente com o APP Ame Digital.
Uma coisa importante, se o sistema parceiro realizar a solicitação da criação da ordem e apresentar o QR Code e o cliente não fizer a leitura e confirmar o pagamento, a criação da ordem não vai se concretizar e não pode ser consultada.
1 - Obtendo o token de acesso
Antes de qualquer interação com as ordens, é imperativo obter um Token de Acesso. Este processo é fundamental para garantir a autenticação e autorização nas operações subsequentes, conforme explicado nos fluxos a seguir.
Url de Produção e Homologação
Produção:
Homologação:
Passos para Obtenção do Token de Acesso:
1. Autenticaçao: Utilize seu Username e Password para efetuar uma requisição ao endpoint apropriado e gerar um novo token
Parâmetros Necessários:
Header:
"Authorization: Basic {encode64(client_id:client_secret)}"
Body:
"(application/x-www-form-urlencoded): grant_type={client_credentials}"
2. Credenciais em Base64: As credenciais fornecidas devem ser codificadas em Base64 e inseridas no header da requisição. Essas credenciais correspondem ao Client ID e Client Secret.3. Token de Acesso Gerado: Após a requisição bem-sucedida, um Access Token será gerado. Este token é essencial e deve ser armazenado com segurança, pois será utilizado nas etapas subsequentes das operações.
Importante a Lembrar:
O token de acesso expira conforme o valor de "expires_in" e deve ser armazenado com atenção, sendo renovado a cada 43 minutos para garantir a continuidade das requisições bem-sucedidas.
Atenção ao Limite de Renovações: Caso o token seja renovado mais de 38 vezes em um único dia, ele será bloqueado. Nesse caso, será necessário gerar um novo token. É fundamental monitorar o uso e evitar o esgotamento das renovações diárias. Em caso de bloqueio, a geração de novas credenciais ou aguardar 24 horas são as opções disponíveis para reativar o acesso.
Certifique-se de seguir essas diretrizes rigorosamente para garantir a segurança e a continuidade das operações que dependem do Token de Acesso na integração com a plataforma da Ame.
2 - Criação da ordem de compra
IMPORTANTE: O primeiro passo antes da criação de ordem de compra é realizar o login! Sem isso você não conseguirá prosseguir. Detalhes de como fazê-lo aqui.
No fluxo de criação de ordem, a primeira etapa é de responsabilidade do Sistema Parceiro. É necessário passar os parâmetros para que a Ame retorne a URL de renderização do QR Code.
Uma dica, sugerimos que a plataforma renderize o QR Code na tela para o cliente. seguindo os padrões e informações que disponibilizamos nessa página.
Para compras realizadas pelo celular, iremos retornar o deepLink para que o cliente seja direcionado automaticamente para o aplicativo AME Digital.
Produção:
Homologação:
Parâmetros Necessários:
Header:
Authorization: Bearer + access_token
Request:
{ "title":"Minha Loja.com", "description":"Pedido X", "amount":3000, "type":"PAYMENT", "attributes":{ "transactionChangedCallbackUrl":"https://webhook.site/8c285cf1-504e-4a69-8018-9dca72dd1958", "items":[ { "ean":"22475411", "sku":"None", "amount":1000, "quantity":1, "description":"CAFE 180ML" }, { "ean":"22475400", "sku":"None", "amount":1000, "quantity":1, "description":"REFRIGERANTE 350ML" }, { "ean":"22475450", "sku":"None", "amount":1000, "quantity":1, "description":"AGUA S/ GAS 500ML" } ], "customPayload":{ "isFrom":"MINHALOJA" "versaoPlataforma":"1.5" }, "address":[ { "postalCode":"86047610", "street":"Rua Sete de Setembro", "number":"3", "complement":"APTO 2", "neighborhood":"Centro", "city":"Londrina", "state":"PR", "country":"BRA", "type":"BILLING" }, { "postalCode":"86047610", "street":"Rua Sete de Setembro", "number":"3", "complement":"APTO 2", "neighborhood":"Centro", "city":"Londrina", "state":"PR", "country":"BRA", "amountValue":0, "type":"DELIVERY" } ], "paymentOnce":true, "riskHubProvider":"SYNC", "origin":"ECOMMERCE" } }
cURL exemplo do Request:
curl --location --request POST 'https://api-amedigital.sensedia.com/hml/auth/v1/orders' \ --header 'Authorization: Bearer {Access_Token}' \ --header 'Content-Type: application/json' \ --data-raw '{ "title": "Pedido teste", "description": "Gera pedido teste 1", "amount": 140, "type": "PAYMENT", "attributes": { "transactionChangedCallbackUrl": "https://webhook.site/", "items": [ { "ean": "22123321", "sku": "ABC", "amount": 100, "quantity": 1, "description": "ITEM 1" }, { "ean": "22123333", "sku": "DEF", "amount": 100, "quantity": 1, "description": "ITEM 2" }, { "ean": "22123333", "sku": "GHI", "amount": 100, "quantity": 1, "description": "ITEM 2" } ], "customPayload": { "isFrom": "Plataforma", "versaoPlataforma":"1.5" }, "address": [ { "postalCode": "86047610", "street": "Rua Sete de Setembro", "number": "3", "complement": "APTO 2", "neighborhood": "Centro", "city": "SAO PAULO", "state": "SP", "country": "BRA", "type": "BILLING" }, { "postalCode": "86047610", "street": "Rua Sete de Setembro", "number": "3", "complement": "APTO 2", "neighborhood": "Centro", "city": "SAO PAULO", "state": "SP", "country": "BRA", "amountValue": 100, "type": "DELIVERY" } ], "paymentOnce": true, "riskHubProvider": "SYNC", "origin": "ECOMMERCE" } }'
Response:
{ "id":"a11927a7-9d6c-4b6e-bfb4-5c6c249ad8a8", "title":"Minha Loja.com", "description":"Pedido X", "amount":3000, "type":"PAYMENT", "attributes":{ "cashbackAmountValue":370, "transactionChangedCallbackUrl":"https://webhook.site/8c285cf1-504e-4a69-8018-9dca72dd1958", "items":[ { "description":"CAFE BR MANIA CAPPUCCINO 180ML", "amount":1000, "quantity":1, "sku":"None" }, { "description":"REFRI COCA COLA LT 350ML", "amount":1000, "quantity":1, "sku":"None" }, { "description":"Abastecimento - Gasolina Aditivada", "amount":1000, "quantity":1, "sku":"None" } ], "customPayload":{ "isFrom":"MINHALOJA" "versaoPlataforma":"1.5" }, "address":[ { "country":"BRA", "number":"3", "city":"Londrina", "street":"Rua Sete de Setembro", "postalCode":"86047610", "neighborhood":"Centro", "state":"PR", "complement":"APTO 2", "type":"BILLING" }, { "country":"BRA", "number":"3", "city":"Londrina", "street":"Rua Sete de Setembro", "postalCode":"86047610", "neighborhood":"Centro", "state":"PR", "complement":"APTO 2", "type":"DELIVERY", "amountValue":0 } ], "paymentOnce":true, "riskHubProvider":"SYNC", "origin":"ECOMMERCE" }, "qrCodeLink":"https://api.hml.amedigital.com/api/qrcode?qrcode=eyJ0eXBlIjoiUEFZTUVOVCIsIm9yZGVyX2lkIjoiYTExOTI3YTctOWQ2Yy00YjZlLWJmYjQtNWM2YzI0OWFkOGE4In0=", "deepLink":"amedigital://payment?qrcode=eyJ0eXBlIjoiUEFZTUVOVCIsIm9yZGVyX2lkIjoiYTExOTI3YTctOWQ2Yy00YjZlLWJmYjQtNWM2YzI0OWFkOGE4In0=" }
Atenção: o pagamento da ordem de compra deve ser feito exclusivamente através do aplicativo de homologação que disponibilizamos durante a fase de integração. Clique aqui para maiores informações sobre como obter o aplicativo de homologação.
3 - Cancelamento de uma Ordem de Compra
Com esta operação, conseguimos realizar o cancelamento de um QR Code se ele ainda não foi pago.
Mas atenção: esta API possui dois tipos de cancelamentos, este em específico (DELETE/ordens), permite que seja cancelada uma ordem que ainda não foi paga. Ainda temos o DELETE/pagamentos, que permite cancelar o pagamento de uma ordem que foi paga, mas ainda não capturada. Deu para entender?
Produção:
Homologação:
Parâmetros Necessários:
Header:
Authorization: Bearer + access_token
Response:
{ "id": "9df12f86-3c09-4c98-aca3-bfa99c75d8a9", "ownerId": "2eae9f27-0f2f-4192-b575-37b91f9270e6", "creditWalletId": "b0c458fd-51cb-4ae0-bd85-0c0d476721ae", "date": "2021-05-31T11:46:34.545", "title": "Pedido - Loja X", "description": "Pedido X", "amount": 1000, "currency": "BRL", "type": "PAYMENT", "attributes": { "cashbackAmountValue": 100, "transactionChangedCallbackUrl": "https://webhook.site/", "items": [ { "description": "Itens do Pedido", "amount": 1000, "quantity": 1, "sku": "1234322" } ], "customPayload": { "isFrom": "Plataforma" }, "address": [ { "country": "BRA", "number": "338", "city": "Campinas", "street": "Avenida Presidente Vargas", "postalCode": "14801000", "neighborhood": "Jardim Califórnia", "state": "SP", "type": "BILLING" }, { "country": "BRA", "number": "338", "city": "Campinas", "street": "Avenida Presidente Vargas", "postalCode": "14801000", "neighborhood": "Jardim Califórnia", "state": "SP", "type": "DELIVERY", "amountValue": 5 } ], "paymentOnce": true, "riskHubProvider": "SYNC", "origin": "ECOMMERCE" }, "planTypes": [ "BSC", "PLS" ] }
Esse ownerId equivale ao custumerId que será utilizado no próximo passo.
Request:
Produção:
Homologação:
Parâmetros Necessários:
Header:
Authorization: Bearer + access_token
Response:
{}
O response body é vazio.
4 - Callback - Aviso de pagamento
Após a ordem ser paga pelo cliente, é enviado um aviso de confirmação de pagamento para a URL de callback informada no campo "transactionChangedCallbackUrl" na criação da ordem de compra.
Confira um exemplo de chamada de callback:
{ "id":"ab48af16-e2c4-40ca-8254-07609b27a183", "date":[ 2021, 2, 10, 17, 20, 14, 801275000 ], "operationType":"DEBIT", "name":"Compra on-line", "title":"Minha Loja.com", "description":"Pedido X", "status":"AUTHORIZED", "type":"PAYMENT", "currency":"BRL", "cashType":"CASH", "amount":3000, "amountRefunded":0, "splits":[ { "id":"c299a433-c4a6-431d-ac9d-fcb6e57455c0", "date":[ 2021, 2, 10, 17, 20, 14, 801288000 ], "status":"AUTHORIZED", "cashType":"CASH", "amount":3000, "installments":null, "cardMasked":null, "cardBrand":null } ], "attributes":{ "cashbackAmountValue":300, "transactionChangedCallbackUrl":"https://webhook.site/8c285cf1-504e-4a69-8018-9dca72dd1958", "items":[ { "description":"CAFE 180ML", "amount":1000, "quantity":1, "ean":null, "sku":"1234322" }, { "description":"REFRIGERANTE 350ML", "amount":1000, "quantity":1, "ean":"1234567890128", "sku":null }, { "description":"AGUA S/ GAS 500ML", "amount":1000, "quantity":1, "ean":null, "sku":"128982" } ], "customPayload":{ "isFrom":"MINHALOJA" }, "address":[ { "country":"BRA", "number":"3", "city":"Londrina", "street":"Rua Sete de Setembro", "postalCode":"86047610", "neighborhood":"Centro", "state":"PR", "complement":"APTO 2", "type":"BILLING" }, { "country":"BRA", "number":"3", "city":"Londrina", "street":"Rua Sete de Setembro", "postalCode":"86047610", "neighborhood":"Centro", "state":"PR", "complement":"APTO 2", "type":"DELIVERY", "amountValue":0 } ], "paymentOnce":true, "riskHubProvider":"SYNC", "origin":"ECOMMERCE", "orderId":"83dc8e33-d368-4566-a541-0ec72f6b7805" }, "operationReference":null, "peer":null, "nsu":"662414801293", "debitWalletId":"7f522584-d6dd-419e-ba06-6fa658ed1278" }
5 - Cancelando um pagamento
Produção:
Homologação:
Se for realizada uma chamada de cancelamento de pagamento, o sistema parceiro pode cancelar uma ordem que já foi autorizada, mas ainda não foi capturada. Feito o cancelamento, o saldo da compra que havia sido capturado da carteira do cliente após a criação da ordem será liberado.
É importante lembrar de cancelar uma ordem que não vai ser capturada, caso contrário, o saldo vai ser capturado da carteira do cliente.
Parâmetro | Descrição |
---|---|
id (PATH PARAM) | ID de pagamento da ordem, que foi recebido na URL de Callback após o pagamento ter sido efetuado Atenção: aqui não deve ser utilizado o ID de criação da ordem |
Após o cancelamento da ordem, ela poderá assumir o seguinte status:
Status | Descrição |
---|---|
CANCELLED | Ordem foi cancelada com sucesso |
Atenção
Uma ordem só pode ser cancelada caso ainda não tenha sido capturada e seu status seja AUTHORIZED. Para reverter ordens já capturadas cujo status é SUCCESS, verifique a página de estorno de ordem.
Parâmetros Necessários:
Header:
Authorization: Bearer + access_token
Response:
{ "id": "4e0aff26-0cbc-41ae-8417-dfb404d86c02", "date": "2020-06-29T15:39:15.515929", "operationType": "DEBIT", "name": "Compra on-line", "title": "titulo da ordem de teste", "description": "descrição da ordem", "status": "CANCELED", "type": "PAYMENT", "currency": "BRL", "cashType": "CASH", "amount": 600, "amountRefunded": 0, "splits": [ { "id": "f05f7856-5d66-4339-a767-016d34cb3bda", "date": "2020-06-29T15:39:15.516183", "status": "CANCELED", "cashType": "CASH", "amount": 600 } ], "attributes": { "orderId": "e9e65d7f-0a10-4d13-be7d-7aca5a4a4467", "paymentOnce": false, "riskHubProvider": "SYNC", "customPayload": { "isFrom": "MAGENTO", "billingAddress": { "billingAddress": { "country": "BRA", "number": "123", "city": "São Paulo", "street": "lorem ipsum", "postalCode": "01229010", "neighborhood": "bairro do limoeiro", "state": "SP", "complement": "cs 1" } } }, "items": [ { "amount": 100, "quantity": 6, "description": "item de teste - sku do produto OU item" } ], "transactionChangedCallbackUrl": "https://iapi.hml.amedigital.com/sua/url/de/callback" }, "peer": { "id": "d480e038-054c-4171-a406-b96805c96866", "name": "nome do merchant de teste, "type": "MERCHANT" }, "nsu": 56355516192 }
6 - Capturando um pagamento
A captura de um pagamento pode ser realizada para ordens que possuem o status AUTHORIZED. Se for bem-sucedida, o pagamento que estava provisionado na carteira do cliente será processado e o valor recebido é lançado na agenda do vendedor.
Nós aconselhamos que a captura seja feita automaticamente após a autorização de uma ordem. Para fazer isso, configure seu sistema para solicitar a captura de uma ordem assim que a Ame retornar o status AUTHORIZED.
IMPORTANTE: Caso o pagamento não seja capturado o saldo fica como AUTHORIZED durante 7 dias e se dentro dessa prazo a captura não for realizada a ordem será cancelada automaticamente e o valor devolvido a carteira do cliente.
Produção:
Homologação:
Parâmetros Necessários:
Header:
Authorization: Bearer + access_token
Body:
{ "idPagamento": "98f0fda5-a95c-4d9c-ae82-e369ad0e8ab1" }
Response:
{ "id": "98f0fda5-a95c-4d9c-ae82-e369ad0e8ab1", "date": "2020-06-29T18:21:06.642483", "operationType": "CREDIT", "name": "Compra on-line", "title": "titulo da ordem de teste", "description": "descrição da ordem", "status": "SUCCESS", "type": "PAYMENT", "currency": "BRL", "cashType": "MULTIPLE", "amount": 500, "amountRefunded": 0, "splits": [ { "id": "25461617-6bb8-4b4e-9ceb-0130e3872602", "date": "2020-06-29T18:21:06.642907", "status": "SUCCESS", "cashType": "CASH", "amount": 275 }, { "id": "dfa899c7-749d-43b1-91f0-1bfa937635a0", "date": "2020-06-29T18:21:06.643098", "status": "SUCCESS", "cashType": "CARD", "amount": 225, "installments": 1, "cardMasked": "449872######7549", "cardBrand": "VISA" } ], "attributes": { "orderId": "32059d60-46ab-4257-82f7-c85561dd2baa", "paymentOnce": false, "riskHubProvider": "SYNC", "customPayload": { "isFrom": "MAGENTO", "billingAddress": { "billingAddress": { "country": "BRA", "number": "123", "city": "São Paulo", "street": "lorem ipsum", "postalCode": "01229010", "neighborhood": "bairro do limoeiro", "state": "SP", "complement": "cs 1" } } }, "items": [ { "amount": 100, "quantity": 1, "description": "item de teste - sku do produto OU item" }, { "amount": 200, "quantity": 2, "description": "item de teste - sku do produto OU item" } ], "transactionChangedCallbackUrl": "https://iapi.hml.amedigital.com/sua/url/de/callback" }, "peer": { "id": "e7d3e610-7323-4ee7-bf3a-9154666191e2", "name": "Usuario de Testes", "type": "MERCHANT" }, "nsu": 666066647128 }
7 - Estornando um pagamento
Atenção
Só é possível realizar o estorno se o pagamento já foi realizado e seu status consta como SUCCESS. Se é necessário cancelar uma ordem que ainda não foi capturada e consta como AUTHORIZED, é necessário cancelar esta ordem.
Existem dois tipos de estorno, o integral, no qual o valor total é devolvido, ou o estorno parcial do valor.
É possível realizar vários estornos referentes a uma mesma ordem, porém é importante lembrar que a soma dos valores estornados não pode ser maior que o valor da venda.
Produção:
Homologação:
Parâmetros Necessários:
Header:
Authorization: Bearer + access_token
{ "amount": 100 }
Response:
{ "refundId": "ddef064b-5755-44c5-8637-36fa8ce2d6c3", "operationId": "d44b1e58-dde8-4b87-a90d-65d494ef66b7", "amount": 500, "status": "REFUNDED", "createdAt": "2020-06-30T17:01:09.553505", "refundedAt": "2020-06-30T17:01:09.617693" }
8 - Buscando um pagamento
Endpoint utilizado para buscar detalhes de um pagamento efetuado, independente do status (cancelado, estornado, autorizado ou capturado)
Produção:
Homologação:
Parâmetros Necessários:
Header:
Authorization: Bearer + access_token
Response:
{ "id": "41dcc952-fa81-4ebd-a36c-d92a4bb89920", "date": "2024-03-14T10:36:23.341539", "operationType": "DEBIT", "name": "Nome do usuário comprador", "title": "Pedido teste", "description": "Gera pedido teste 1", "status": "SUCCESS", "type": "PAYMENT", "currency": "BRL", "cashType": "CARD", "amount": 340, "calculatedAmount": 340, "calculatedAmountMdr": 0, "calculatedAmountAdvance": 0, "splits": [ { "id": "3579ad91-1eac-4766-9e85-1b84b9b3b768", "date": "2024-03-14T10:36:23.353586", "status": "SUCCESS", "cashType": "CARD", "amount": 340, "installments": 1, "cardMasked": "123456######0101", "cardBrand": "MASTERCARD", "takeRateAmountInCents": 0, "grossAmountInCents": 0, "netAmountInCents": 0, "walletId": "9c5743d9-db3b-4608-bf9f-a98cdaedf1a2", "interestRate": 0, "interestRateAmountInCents": 0 } ], "attributes": { "address": [ { "country": "BRA", "number": "3", "city": "SAO PAULO", "street": "Rua Sete de Setembro", "postalCode": "86047610", "neighborhood": "Centro", "state": "SP", "complement": "APTO 2", "type": "BILLING" }, { "country": "BRA", "number": "3", "amountValue": 100, "city": "SAO PAULO", "street": "Rua Sete de Setembro", "postalCode": "86047610", "neighborhood": "Centro", "state": "SP", "complement": "APTO 2", "type": "DELIVERY" } ], "orderId": "a08bf5cc-4fa1-4dee-80ed-d18c24aaf0e8", "origin": "ECOMMERCE", "paymentOnce": true, "riskHubProvider": "SYNC", "externalProvider": "Plataforma", "saleChannel": "DIGITAL", "installmentAllowed": true, "cashbackAmountValue": 0, "customPayload": { "isFromJulius": "true", "premmiaOptIn": false, "isFrom": "Plataforma", "OptInPremmia": false, "noCoupon": true, "versaoPlataforma": "1.5" }, "items": [ { "amount": 100, "quantity": 1, "ean": "22123321", "description": "ITEM 1", "sku": "ABC" }, { "amount": 100, "quantity": 1, "ean": "22123333", "description": "ITEM 2", "sku": "DEF" }, { "amount": 100, "quantity": 1, "ean": "22123333", "description": "ITEM 2", "sku": "GHI" } ], "allowedPaymentTypes": [ "CASH", "CASH_BACK", "CREDIT_CARD", "MULTIPLE" ] }, "peer": { "id": "0a5de79e-f980-425b-8a7c-af55d34b91d7", "ownerId": "c349aabd-eef0-4ce6-b675-b77314e2169d", "name": "Gustavo De Souza Bezerra", "nickname": "Gustavo Bezerra" }, "nsu": 248983341646, "referenceWalletUuid": "245e332c-24f4-4199-992d-ab25b4fba9e2", "refunded": false, "nsuPurchase": 248983341646, "sumSplitsValueCashAndCashback": 0 }