Collection

You can download the collection for this API at the following link:

Download API Collection

Environment

We have two environments for development:

  1. Developer Environment: https://api-amedigital.sensedia.com/hml/transactions/v1

    This environment is for testing scenarios before going to production.

  2. Production Environment: https://api-amedigital.sensedia.com/transactions/v1

    This is the official integration environment.

Overview

The orders are the most important components in the process; they allow you to perform different functionalities within Ame. For example, the creation of a transaction is realized through creating an order.

The events for the orders are:

  1. Create a Test Account and Client Key
  2. Get Access Token
  3. Create Order
  4. Consult Order
  5. Cancel Order
  6. Callback – Payment Notice
  7. Cancel Payment
  8. Capture of Payment
  9. Refund of Payment

Get Started

1. Create a Test Account and Client Key

For creating a test account, you need to send an email to amedigitaldx@sensedia.com. We will create a test account and provide you with the credentials for the connection in the homologation environment.

2. Get Access Token

To use our API, the first step is authentication. For this, you need to provide the credentials and request the URL below:

Method Environment URL
POST Production https://api-amedigital.sensedia.com/hml/auth/v1/login
POST Developer https://api-amedigital.sensedia.com/hml/auth/v1/login

Request Parameters:

The credentials sent are the Client Id and Client Secret in base64.

Header "Authorization: Basic {encode64(client_id:client_secret)}"
Body "(application/x-www-form-urlencoded): grant_type={client_credentials}"

Important: The token expires in 43 minutes, so you need to request it again after expiry.

3. Create Order

In creating an order, you send us a request with the parameters necessary for the creation of the order, and we send you a response with the information so that you can generate the QRCODE for the payment.

After creating the order and generating the QRCODE, the next step is the payment of the order made by the user in the AME app. When this occurs, we send you a callback with the confirmation of the payment and update the status of the order to "Authorized."

Create Order URL:

Method Environment URL
POST Production https://api-amedigital.sensedia.com/hml/transactions/v1/orders
POST Developer https://api-amedigital.sensedia.com/hml/transactions/v1/orders

Parameters:

Header Authorization Bearer + access_token

Body Parameters:

Parameters Type Required Description
title string Yes Title of order
softDescription string No -
type string No Type Of Order. Default:PAYMENT
description string No Description Of order
amount number Yes Total Amount of order
verifyAuthorization boolean No -
subType string No Subtype of order ( not use)
attributes OrderAttribute Yes -

OrderAttribute

Atributo Type Required Description
deliveryAddress string No Delivery Address
transactionChangedCallbackUrl String No URL for sending you a callback
items array<OrderItem> No Itens the order
origin string No Origin the transaction (example: Ecommerce, POS, PDV, Service, Miniapp, ticket)
externalOrder ExternalOrderAttribute No -

OrderItem

Atributo Type Required Description
deliveryAddress string No Delivery Address
transactionChangedCallbackUrl String No URL for sending you a callback
items array<OrderItem> No Itens the order
origin string No Origin the transaction (example: Ecommerce, POS, PDV, Service, Miniapp, ticket)
externalOrder ExternalOrderAttribute No

Possible Response

Status Type Motive Body
201 Success OK
403 Error Credencial invalid. { "tipo": "falha na comunicação", "descricao": "Seu app encontra-se sem permissao de acesso configurada" }
400 Error Request Invalid inválida. One or more parameter required is not sending. { "error": "validation_error", "error_description": "O atributo [] é um parâmetro obrigatório." }

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

Example Response

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

4. Consult Orders

For the consult order you need to request of the Url

Method Environment URL
GET Production https://api-amedigital.sensedia.com/transactions/v1/orders/{orderId}
GET Developer https://api-amedigital.sensedia.com/hml/transactions/v1/orders/{orderId}

Parameters:

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

5. Cancel Order

When the payment is not made you can use the request URL for the cancel Order.

Method Environment URL
DELETE Production https://api-amedigital.sensedia.com/transactions/v1/orders/{orderId}
DELETE Developer https://api-amedigital.sensedia.com/hml/transactions/v1/orders/{orderId}

Possible Response

Status Type Motive Body
200 Success OK
403 Error Credencial invalid. { "tipo": "falha na comunicação", "descricao": "Seu app encontra-se sem permissao de acesso configurada" }
404 Error Order doesn’t exist { "error": "order_not_found", "error_description": "Pedido não encontrado" }

6. Callback – Payment Notice

After the payment of the order, we send to you the callback with the information about the same.

Important: We try to send three times, if we are unable to deliver we cancel the order, so it is important that you always check that the callback url sent in the order (transactionChangedChangedCallbackUrl field) is working.

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

7.Cancel Payment

After the payment realized and not captured you can use the url for the Cancel Payment, this endpoint is important because if you do not capture the payment the amount will reserve in the wallet of the final user.

Method Environment URL
POST Production https://api-amedigital.sensedia.com/transactions/v1/payments/{paymentId}/cancela>
POST Developer https://api-amedigital.sensedia.com/hml/transactions/v1/orders/{orderId}

Paymentid will be send to you in callback ( Step 6).

After the cancel to payment the status of the order will be : Cancelled

Possible Response

Status Type Motive Body
200 Success OK
400 Error The Payment cann’t cancel because the same is status: captured { "error": "wallet_api", "error_description": "A order [], ja esta capturada nao pode ser realizado o cancelamento" }
401 Error Bearer token is invalid. { "status": "Unauthorized", "result": "Invalid token or invalid request token structure." }
500 Error { "error": "wallet_api", "error_description": "Ocorreu um erro interno contate o administrador do sistema." }

8. Capture Payment

For the confirmation of the payment is necessary that after the receive callback you send to us the requisition of the capture of payment.

Important: After 7 days if not received the requisition of capture the order will be cancelled automatically.

Method Environment URL
POST Production https://api-amedigital.sensedia.com/transactions/v1/payments/{paymentId}/capture>
POST Developer https://api-amedigital.sensedia.com/hml/transactions/v1/orders/{orderId}/capture

Parameters:

Header Authorization Bearer + access_token
Parameters Type Required Description
IdPagamento string Yes Id of the Payment

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
}

9. Refund Payment

For the refund of the payment, we have two forms for this

Method Environment URL
POST Production https://api-amedigital.sensedia.com/transactions/v1/payments/{paymentId}/refunds/UUID>
POST Developer https://api-amedigital.sensedia.com/hml/transactions/v1/orders/{orderId}/refunds/UUID

Parameters:

Header Authorization Bearer + access_token

Parameters:

Parameters Type Required Description
Ammount string Yes Id of the Payment

If the Ammount is not send the refund will be total.

English