API Transaction + Split

Collection

Você pode fazer o download das Collections desta API através do arquivo:

Clique aqui para fazer o download.



Ambientes

Temos atualmente dois ambientes para a API Transaction:


IMPORTANTE: Os dois ambientes seguem o mesmo fluxo e os mesmos retornos!



Visão geral

Ofertar Ame como meio de pagamento para seus clientes é muito fácil.

Utilizando a API Transactions é possível acessar todas as funcionalidades associadas a uma ordem dentro da Ame.

As ordens representam as transações. Por exemplo, a criação de uma transação é realizada através da criação de uma ordem de compra.

Na Ame nós temos 2 tipos de ordens:


Ordem Padrão:

Utilizadas para transações em um único Vendedor.


Envolvidos:

Uma ordem padrão envolve os seguintes participantes:

Participante Descrição
Seller Parceiro de negócios, possui uma relação comercial/jurídica com a Ame. É responsável por realizar a integração com nosso sistema e pelo carrinho de compras.
Cliente Final Realiza a compra e efetua o pagamento com Ame.
Ame Responsável pelo Fluxo transacional e por realizar a liquidação dos valores.


O Seller se integra a Ame e em cada transação informa os dados da compra, quais seus itens e valores.

Assim que o Cliente Final efetua o pagamento através do nosso app, a Ame agenda a liquidação de acordo com o prazo de liquidação do Seller.


Ordem de Split:

O Split de pagamento possibilita ao Cliente Final realizar uma compra (produtos ou serviços) que envolva mais de um Vendedor em um único lugar e efetuar o pagamento com Ame de forma unificada. O valor pago pelo Cliente Final é repassado para as partes envolvidas de acordo com a sua participação na venda.


Envolvidos:

Uma ordem de split envolve os seguintes participantes:

Participante Descrição
Seller Principal
(Marketplace, Lojas com vários centros de distribuição, entre outros)		 Parceiro de negócios, possui uma relação comercial/jurídica com a Ame. É responsável por realizar a integração com nosso sistema e pelo carrinho de compras, fornecendo os dados para a realização do Split.
Define a taxa a ser descontada de cada vendedor (Seller Secundário).
Pode também participar de uma venda com seus próprios produtos.
Seller Secundário
(Lojas que ofertam produtos no marketplace, centro de distribuição, entre outros)		 Participa da venda ofertando seus produtos.
Cliente Final Realiza a compra e efetua o pagamento com Ame.
Ame Responsável pelo Fluxo transacional e por realizar a liquidação dividindo os valores de acordo com os dados fornecidos pelo Seller Principal.

Todos os envolvidos precisam ter uma conta na Ame.



O Seller principal se integra a Ame e em cada transação informa os envolvidos e seus respectivos valores, ele também informa o valor de comissão a ser descontado de cada envolvido (se houver).

Assim que o Cliente Final efetua o pagamento através do nosso app, a Ame faz a divisão dos valores e agenda a liquidação de acordo com o prazo de cada envolvido.

Agora que você já conhece os conceitos de ordem, confira quais são as ações que você pode executar relacionadas às ela:

  1. Obtendo o token de acesso
  2. Solicitar a criação da ordem de compra
  3. Solicitar o cancelamento de uma Ordem de Compra
  4. Receber o callback - Aviso de pagamento
  5. Solicitar o cancelamento de um pagamento
  6. Solicitar a captura de um pagamento
  7. Solicitar o estorno de um pagamento
  8. Consultando uma Ordem de Compra

Fizemos um fluxo para ilustrar melhor essas ações:

ordem_compra

Fluxo macro da ordem de compra


Mas não se esqueça, para realizar as ações é necessário um Token de acesso.


1 - Obtendo o token de acesso

Para obter o Token de Acesso, basta fazer uma requisição a API responsável pela autenticação e validação dos acessos. Nesta etapa você deve utilizar seu Username e Password


Produção:
POST https://api-amedigital.sensedia.com/auth/v1/login
Homologação:
POST https://api-amedigital.sensedia.com/hml/auth/v1/login

Parâmetros Necessários:
Header:

"Authorization: Basic {encode64(client_id:client_secret)}"

Body:

"(application/x-www-form-urlencoded): grant_type={client_credentials}"

As credenciais enviadas correspondem ao Client ID e Client Secret em base64. Ao realizar a requisição passando as credenciais será gerado um Access Token que será utilizado nas outras etapas. É importante lembrar que esse token expira e então será necessário gerar um novo para que você consiga fazer as requisições com sucesso.


IMPORTANTE: O token expira de acordo com o expires_in e deve ser armazenado por 43 minutos, após esse período é necessário gerar um novo. Porém, caso ele seja renovado mais de 38 vezes por dia, o mesmo é bloqueado. É necessário ficar atento, pois se o token for bloqueado é necessário gerar novas credenciais ou aguardar 24 horas para que seja desbloqueado.


2 - Solicitar a 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.


A confirmação de uma ordem de compra tem duas etapas:

a. Criação da ordem com base nas informações passadas pelo Sistema Parceiro;
Essa é a primeira etapa e é de responsabilidade do Sistema Parceiro. É necessário informar os parâmetros para que a Ame retorne à 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.

b. Pagamento da ordem de compra através da leitura do QR Code pelo cliente com o APP Ame Digital.


Ao receber a confirmação do pagamento pelo Cliente Final a ordem é confirmada e seu status fica como “Authorized”.

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.

cria_ordem_compra

Fluxo de solicitação da criação da ordem de compra


A criação da ordem de compra (Padrão e de Split) é realizada através das URLs:

Produção:
POST https://api-amedigital.sensedia.com/transactions/v1/orders
Homologação:
POST https://api-amedigital.sensedia.com/hml/transactions/v1/orders

Parâmetros Necessários:
Header:

Authorization: Bearer + access_token

Order
Atributo Tipo Obrigatório ordem padrão Obrigatório ordem de split Descrição
title string Sim Sim Título da ordem
softDescription string Não Não
type string Não Não Tipo da ordem. Valor padrão: PAYMENT
Valores possíveis PAYMENT, TRANSFER
description string Não Não Descrição da ordem
amount number Sim Sim Valor da ordem em centavos
verifyAuthorization boolean Não Não
subType string Não Sim Subtipo da ordem.
attributes OrderAttribute Sim Sim Atributos da ordem

OrderAttribute
Atributo Tipo Obrigatório ordem padrão Obrigatório ordem de split Descrição
title string Sim Sim Título da ordem
softDescription string Não Não
type string Não Não Tipo da ordem. Valor padrão: PAYMENT
Valores possíveis PAYMENT, TRANSFER
description string Não Não Descrição da ordem
amount number Sim Sim Valor da ordem em centavos
verifyAuthorization boolean Não Não
subType string Não Sim Subtipo da ordem.
attributes OrderAttribute Sim Sim Atributos da ordem
OrderItem
Atributo Tipo Obrigatório Descrição
amount string Não Valor do item em centavos
quantity number Não Quantidade do item
description string Não Descrição do item
sku string Não Código SKU
cashbackAmountItem number Não Quantidade em centavos de cashback
ean string Não Código EAN
recipient string Não Documento do destinatário do item
AddressOrder
Atributo Tipo Obrigatório Descrição
number string Não Número do endereço
city string Não Cidade
street string Não Rua
postalCode string Não CEP
neighborhood string Não Bairro
state string Não Código do Estado
complement string Não Complemento
type string Não Tipo do endereço. Valores possiveis: BILLING, DELIVERY
amountValue number Não
Split
Atributo Tipo Obrigatório Descrição
recipients array<OrderSplitRecipient> Sim Lista dos participantes do split
OrderSplitRecipient
Atributo Tipo Obrigatório Descrição
id string Sim Número do documento do vendedor
commission number Não Comissão do vendedor
takeRateOwner boolean Não Define se o seller é responsável pelo pagamento da tarifa.
amount number Sim Valor em centavos
SellerAcquirer
Atributo Tipo Obrigatório Descrição
identifier string Não Indicador do vendedor
name string Não Nome do vendedor
ownerWalletUuid string Não Identificador UUID da carteira
customPayload object Não Objeto com formato chave e valor para Informações adicionais
MiniAppAttribute
Atributo Tipo Obrigatório Descrição
id string Não Identificador único
hasOrderDetails boolean Não Têm detalhes na ordem
ownerWalletUuid string Não Identificador UUID da carteira
customPayload object Não Objeto com formato chave e valor para Informações adicionais
MiniAppAttribute
Atributo Tipo Obrigatório Descrição
id string Não Identificador único
hasOrderDetails boolean Não Têm detalhes na ordem
RecurrenceAttribute
Atributo Tipo Obrigatório Descrição
enabled boolean Não A recorrência está habilitada?
TicketAttribute
Atributo Tipo Obrigatório Descrição
eventName string Não Nome evento
eventVenue string Não Local do evento
eventVenueLocation string Não Localização evento
numberOfTickets number Não Número de ingressos
eventDate number Não Data evento
eventCategory string Não Categoria evento
SellerAttribute
Atributo Tipo Obrigatório Descrição
groupId string Não ID do grupo
merchantId string Não ID do comerciante
userId string Sim ID usuário
numberOfTickets number Não Número de ingressos
eventDate number Não Data evento
eventCategory string Não Categoria evento
TrustWalletAttribute
Atributo Tipo Obrigatório Descrição
enabled boolean Não Trust Wallet habilitada
ExternalOrderAttribute
Atributo Tipo Obrigatório Descrição
id string Não Identificador ordem
url string Não
deeplink string Não
goToStoreButtonLabel string Não

Para realizar a criação de uma ordem de split deve-se atentar aos requisitos a seguir:

  1. A ordem deve ter subtipo “SPLIT”.
  2. Todas as lojas que irão receber algum valor devem ter conta ativa na ame.
  3. A funcionalidade de “Split” precisar estar habilitada para o Seller Principal.
  4. Para cada item da ordem deve-se informar o documento (recipient) do vendedor responsável pelo item.
  5. Todos os vendedores que têm ao menos um item associado deve estar listado no atributo “attributes.split.recipients”.

2.1 - Exemplo de criação da ordem de compra Padrão

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

}

Possíveis Respostas

Status Tipo Motivo Corpo
201 Sucesso OK
403 Erro Credencial inválida. Revisar parâmetros autenticação enviados {
"tipo": "falha na comunicação",
"descricao": "Seu app encontra-se sem permissao de acesso configurada"
}
400 Erro Requisição inválida. Parâmetro obrigatório não informado. {
"error": "validation_error",
"error_description": "O atributo [<nomeAtributo>] é um parâmetro obrigatório."
}
goToStoreButtonLabel string Não

2.2 - Exemplo de criação da ordem de compra de Split

No exemplo abaixo é criada uma ordem de 10,00 reais, com divisão de 6,00 reais para o primeiro vendedor (Item 1) e 4,00 reais para segundo vendedor (Item 2).



Parâmetros Necessários:
Header:

Authorization: Bearer + access_token

Possiveis respostas

Status Tipo Motivo Corpo
201 Sucesso OK
400 Erro Requisição inválida {
"error": "Erro de validação",
"error_description": "Ocorreu um erro na validação"
}
403 Erro Funcionalidade não habilitada para o vendedor/seller. Entre em contato com a equipe comercial ou com o SAC para realizar a habilitação {
"error": "customer-not-allowed",
"error_description": "A funcionalidade de Split não está habilitada para o vendedor/seller"
}
400 Erro O recebedor de algum dos itens não foi declarado na lista de recebedores “attributes.split.recipients” {
"error": "validation-error",
"error_description": "O recebedor do item não consta nos recebedores do split"
}
400 Erro Valor de comissão informado para o recebedor não pode ser maior que a soma dos valores dos itens na ordem {
"error": "validation-error",
"error_description": "A comissão do recebedor é maior que a soma dos seus itens"
}

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.

Após o pagamento da ordem, ela irá assumir o seguinte status:

Status Descrição
AUTHORIZED Ordem foi autorizada com sucesso

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

cancela_ordem_compra

Fluxo de solicitação de cancelamento de ordem de compra


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:
DELETE https://api-amedigital.sensedia.com/transactions/v1/orders/orderId
Homologação:
DELETE https://api-amedigital.sensedia.com/hml/transactions/v1/orders/orderId

Parâmetros Necessários:
Header:

Authorization: Bearer + access_token

Response:
{}
  • O response body é vazio.

    • Possíveis Repostas

    Status Tipo Motivo Corpo
    200 Sucesso OK
    403 Erro Credencial inválida. Revisar parâmetros autenticação enviados {
    "tipo": "falha na comunicação",
    "descricao": "Seu app encontra-se sem permissao de acesso configurada"
    }
    404 Erro Não existe uma ordem para a combinação do orderId e customerId informado ou a ordem já foi cancelada. {
    "error": "order_not_found",
    "error_description": "Pedido não encontrado"
    }

    Após o cancelamento da ordem, ela irá assumir o seguinte status:

    Status Descrição
    CANCELLED Ordem foi cancelada com sucesso

    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.

    callback

    Fluxo de envio de callback


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

    IMPORTANTE

    No call-back você recebe o ID do pagamento que poderá ser utilizados em outras operações, como captura, cancelamento..

    Respostas esperadas do Parceiro

    Status Tipo Motivo
    200 Sucesso Significa que o Parceiro recebeu o Callback e podemos continuar com a ordem.
    XXX Erro Qualquer mensagem diferente de 200 prosseguiremos com o cancelamento da ordem.

    5 - Cancelando um pagamento

    É possível solicitar o cancelamento de uma ordem que já foi autorizada, mas ainda não foi capturada. Feito o cancelamento, o saldo da compra que havia sido provisionado 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.

    cancela_pagamento

    Fluxo de solicitação de cancelamento de pagamento


    Produção:
    POST https://api-amedigital.sensedia.com/transactions/v1/payments/paymentId/cancel
    Homologação:
    POST https://api-amedigital.sensedia.com/hml/transactions/v1/payments/paymentId/cancel
    Parâmetro Descrição Motivo
    paymentId (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 Significa que o Parceiro recebeu o Callback e podemos continuar com a ordem.

    IMPORTANTE

    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
}

    Após o cancelamento da ordem, ela poderá assumir o seguinte status:

    Status Descrição
    CANCELLED Ordem foi cancelada com sucesso

    Possíveis Respostas

    Status Tipo Motivo Corpo
    200 Sucesso OK
    400 Erro Não é possível realizar o cancelamento de um pagamento caso o mesmo tenha sido capturado. Após a captura somente é possível solicitar o estorno. {
    "error": "wallet_api",
    "error_description": "A order [<orderId>], ja esta capturada nao pode ser realizado o cancelamento"
    }
    401 Erro Bearer token inválido ou não informado. {
    "status": "Unauthorized",
    "result": "Invalid token or invalid request token structure."
    }
    500 Erro Certifique-se que o paymentId informado está correto. Caso o problema persista entre em contato com o SAC. {
    "error": "wallet_api",
    "error_description": "Ocorreu um erro interno contate o administrador do sistema."
    }

    6 - Solicitar a captura de 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.

    captura

    Fluxo de captura de pagamento



    IMPORTANTE: Caso o pagamento não seja capturado o saldo fica como AUTHORIZED durante 7 dias e se dentro desse prazo a captura não for realizada a ordem será cancelada automaticamente e o valor devolvido a carteira do cliente.


    Produção:
    POST https://api-amedigital.sensedia.com/transactions/v1/payments/paymentId/capture
    Homologação:
    POST https://api-amedigital.sensedia.com/hml/transactions/v1/payments/paymentId/capture

    Parâmetro Descrição
    paymentId (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
    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
}

    Após a captura da ordem, ela irá assumir o seguinte status:

    Status Descrição
    CAPTURED Ordem foi capturada com sucesso

    Possíveis Respostas:

    Status Tipo Motivo Corpo
    200 Sucesso OK
    404 Erro Caso uma ordem tenha sido cancelada não é possível realizar a captura do pagamento. {
    "error": "wallet_api",
    "error_description": "A order [<orderId>], ja esta cancelada nao pode ser realizado a captura"
    }
    401 Erro Bearer token inválido ou não informado. {
    "status": "Unauthorized",
    "result": "Invalid token or invalid request token structure."
    }
    500 Erro Certifique-se que está informando um paymentId válido. Caso o problema persista entre em contato com o SAC. {
    "error": "wallet_api",
    "error_description": "Ocorreu um erro interno contate o administrador do sistema."
    }

    7 - Solicitar o estorno de 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.

    estorna_compra

    Fluxo de solicitação de estorno de pagamento


    Ao realizar um estorno parcial de uma ordem com “split” de pagamentos deve-se atentar as validações:

    1. O valor de estorno solicitado não é maior que o valor da venda.
    2. No caso de estorno parcial (valor menor que o da venda) se ao menos um vendedor (sellers) foi informado.
    3. O vendedor informado participou da venda.
    4. O valor de estorno solicitado para um vendedor não é maior que o valor recebido quando a ordem foi criada.
    5. A soma dos valores de estorno de todos os vendedores é igual ao valor de estorno total solicitado.

    No caso de um estorno total é opcional o envio dos dados de vendedores, os valores serão estornados de acordo com a participação de cada envolvido na venda.

    IMPORTANTE

    O prazo para solicitação do estorno de uma transação é de 7 dias para vendas em lojas físicas e 30 dias para vendas em e-commerce.


    Produção:
    POST https://api-amedigital.sensedia.com/transactions/v1/payments/{paymentId}/refunds/{UUID}
    Homologação:
    POST https://api-amedigital.sensedia.com/hml/transactions/v1/payments/{paymentId}/refunds/{UUID}

    7.1 - Exemplo de estorno de uma ordem Padrão

    Parâmetros Necessários:
    Header:

    Authorization: Bearer + access_token

    Parâmetro Descrição
    paymentId (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 
    {
    "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"
}
    Status Tipo Motivo Corpo
    200 Sucesso Ok
    400 Erro Não é possível realizar um estorno maior que o valor do pagamento. {
    "error": "refund_amount_exceeded",
    "error_description": "O valor solicitado é superior ao valor disponível para o estorno."
    }
    401 Erro Bearer token inválido ou não informado. {
    "status": "Unauthorized",
    "result": "Invalid token or invalid request token structure."
    }

    7.2 - Exemplo de estorno de uma ordem de SPLIT

    No exemplo a seguir é gerado um estorno parcial de 5,00 reais, sendo 3,00 reais de estorno referente ao primeiro vendedor e 2,00 reais para o segundo.

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

    Authorization: Bearer + access_token

    Possíveis Respostas

    Status Tipo Motivo Corpo
    200 Sucesso OK
    400 Erro Requisição inválida {
    "error": "Erro de validação",
    "error_description": "Ocorreu um erro na validação"
    }
    400 Erro Valor de estorno maior que o valor da compra {
    "error": "refund-validation-error",
    "error_description": "O valor de estorno não pode ser maior que o valor da ordem de venda"
    }
    400 Erro Estorno parcial sem informar o sellers {
    "error": "refund-validation-error",
    "error_description": "Para realizar um estorno parcial deve ser informado os vendedores"
    }
    400 Erro Valor total não corresponde a soma dos valores de estorno para cada vendedor {
    "error": "refund-validation-error",
    "error_description": "O valor total dos vendedores não é igual ao valor total do estorno"
    }
    400 Erro Valor de estorno do vendedor maior que o valor recebido {
    "error": "refund-validation-error",
    "error_description": " O valor de estorno está acima do permitido para esse pedido. "
    }

    8- Consultando uma Ordem de Compra

    Para realizar consultas nas ordensd e compra criada ( verificar Status, ou caso queira confirmar as informações enviadas ) basta você realizar através dos endpoints :

    GEThttps://api-amedigital.sensedia.com/transactions/v1/orders/orderId
    GEThttps://api-amedigital.sensedia.com/hml/transactions/v1/orders/orderId
    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"
    ]
}
    Undefined