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:
- Homologação (https://api-amedigital.sensedia.com/hml/transactions/v1) - Para realizar todos testes necessários
- Produção (https://api-amedigital.sensedia.com/transactions/v1) - Onde será rodado a aplicação após finalizar a integração
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:
- Obtendo o token de acesso
- Solicitar a criação da ordem de compra
- Solicitar o cancelamento de uma Ordem de Compra
- Receber o callback - Aviso de pagamento
- Solicitar o cancelamento de um pagamento
- Solicitar a captura de um pagamento
- Solicitar o estorno de um pagamento
- Consultando uma Ordem de Compra
Fizemos um fluxo para ilustrar melhor essas ações:
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:
Homologação:
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.
A criação da ordem de compra (Padrão e de Split) é realizada através das URLs:
Produção:
Homologação:
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:
- A ordem deve ter subtipo “SPLIT”.
- Todas as lojas que irão receber algum valor devem ter conta ativa na ame.
- A funcionalidade de “Split” precisar estar habilitada para o Seller Principal.
- Para cada item da ordem deve-se informar o documento (recipient) do vendedor responsável pelo item.
- 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.
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:
{}
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.
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.
Produção:
Homologação:
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.
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:
Homologação:
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.
Ao realizar um estorno parcial de uma ordem com “split” de pagamentos deve-se atentar as validações:
- O valor de estorno solicitado não é maior que o valor da venda.
- No caso de estorno parcial (valor menor que o da venda) se ao menos um vendedor (sellers) foi informado.
- O vendedor informado participou da venda.
- O valor de estorno solicitado para um vendedor não é maior que o valor recebido quando a ordem foi criada.
- 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:
Homologação:
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.
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 :
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" ] }