API de Transação V2

Collection

Aqui, na Ame disponibilizamos as Collections através do arquivo:

Clique aqui para fazer o download.



Ambientes

emos dois ambientes: o primeiro é o de homologação, que torna possível rodar todos os testes que você precisar. O segundo, é o ambiente produtivo.
Ah, vale lembrar que os dois ambientes seguem o mesmo fluxo e mesmos retornos, beleza?

Ambiente Base URI
Homologação http://api-amedigital.sensedia.com/hml/transacoes/v2
Produção http://api-amedigital.sensedia.com/transacoes/v2


Overview sobre ordens

As ordens são eventos que permitem a execução de diversas funcionalidades relacionadas às transações dentro da Ame, beleza? Por exemplo, a criação de uma transação é realizada através da criação de uma ordem de compra.

Dá uma olhada quais são as ações relacionadas às ordens:

  1. Criação da ordem de compra
  2. Cancelamento de uma Ordem de Compra
  3. Callback - Aviso de pagamento
  4. Cancelando um pagamento
  5. Capturando um pagamento
  6. Estornando 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, ok? Ou seja, a Ame Digital e o cliente que irá realizar a compra no nosso aplicativo.


Nesta criação tem duas etapas:

  1. Criação da ordem com base nas informações passadas pelo Sistema Parceiro;
  2. Pagamento da ordem de compra através da leitura do QR Code pelo cliente com o app Ame Digital.

Ah, 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 - Criação da ordem de compra

No fluxo de criação de ordem, a primeira etapa é de responsabilidade do Sistema Parceiro, ok? É 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.


POST /ordens
Parâmetros Necessários:
Header:

Authorization + Base64(client_id:client_secret)

Request:
{
   "title":"Minha Loja.com",
   "description":"Pedido X",
   "amount":3000,
   "type":"PAYMENT",
   "currency":"BRL",
   "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"
      },
      "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,
      "externalTransactionIdentifier":"9e3cf416-31b4-11ec-8d3d-0242ac130003",
      "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"
      },
      "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="
}


Se liga: 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.

2 - 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?


GET /ordens/orderID
Parâmetros Necessários:
Header:

Authorization + Base64(client_id:client_secret)

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


Request:
DELETE /ordens/orderID
Parâmetros Necessários:
Header:

Authorization + Base64(client_id:client_secret)

customerId:

O customerId é obtido no campo ownerId do GET/orderID (endpoint anterior).

Response:
{}

O response body é vazio.



3 - 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.

Dá uma olhada em 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"
}


4 - Cancelando um pagamento

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, beleza?

E não esqueça, sempre cancele uma ordem que não vai ser capturada, caso contrário, o saldo vai ser capturado da carteira do cliente.

Dá uma olhada em quais são os parâmetros disponíveis na chamada de cancelamento de ordem. Se você precisa de mais detalhes técnicos e de obrigatoriedades dos campos, é só olhar aqui.


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

Lembre-se

Uma ordem só pode ser cancelada caso 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 + Base64(client_id:client_secret)

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
}


5 - Capturando um pagamento

A captura de um pagamento pode ser realizada para ordens que possuem o status AUTHORIZED, ok? 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.

Uma dica, 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.

Dá uma olhada, aqui explicamos os parâmetros disponíveis na chamada de captura de ordem. Se você precisa de mais detalhes técnico e de obrigatoriedade dos campos, é só olhar aqui.


POST /pagamentos
Parâmetros Necessários:
Header:

Authorization + Base64(client_id:client_secret)

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


6 - Estornando um pagamento

Se o pagamento já foi realizado e seu status consta como SUCCESS é possível realizar seu estorno. Se é necessário cancelar uma ordem que ainda não foi capturada e consta como AUTHORIZED, é necessário cancelar esta ordem, ok?

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, mas atenção, a soma dos valores estornados não pode ser maior que o valor da venda.

Aqui, você encontra os parâmetros disponíveis na chamada de estorno de ordem, se você precisa de mais detalhes técnicos e de obrigatoriedade dos campos, dá uma olhadinha aqui.


PUT /pagamentos/:pagamentoId
Parâmetros Necessários:
Header:

Authorization + Base64(client_id:client_secret)

{
    "amount": 100,
    "refundId": "e53799a2-aee2-43c0-bcc8-ee61e904e887"
}
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"
}


Português, Brasil