AME

This documentation describes the integration with AME through Carat Portal, using the CardSE via SiTef routing.

Registration information

The Carat must be configured to accept payments for the AME authorizer thru CardSE.

REST Payment

Flow

1. The merchant creates the transaction on Carat Portal passing some additional AME information and receives a NIT as a response.
2. The merchant calls the payment effectuation service and receives a QR code and a transaction with PEN (pending) status.
3. The merchant displays the QR code to the customer.
4. The customer scans the QR code with the AME app and goes through the payment confirmation procedures requested by the authorizer.
5. While the customer finishes the payment, Carat Portal will query the sale situation on the authorizer until the transaction ends.
6. The merchant, in turn, must query the transaction status on Carat Portal until it doesn't have the PEN status anymore.

Attention:

If the status remains pending (PEN) after 3 (three) minutes, Carat Portal will undo the transaction alongside AME.

Additional information when creating the transaction

For AME transactions, the authorizer_id = 446 must be used.

Below are the additional parameters that can be sent on AME transactions:

Parameter	Description	Format	Mandatory
additional_data.items[]
ean	EAN product code. Attention: if EAN and SKU are sent simultaneously, only EAN will be considered.	< 255 AN	NO
sku	SKU product code. Attention: if EAN and SKU are sent simultaneously, only EAN will be considered.	< 255 AN	NO
description	Product description.	< 30 AN	NO
quantity	Product quantity.	< 15 N	NO
quantity_type	Quantity type: u - Units g - Grams ml - Mililiters	< 2 AN	NO
unit_price	Unit price of the product in cents.	< 12 N	NO

Example:

Starting transaction

--request POST "https://esitef-homologacao.softwareexpress.com.br/e-sitef/api/v1/transactions"

--header "Content-Type: application/json"

--header "merchant_id: xxxxxxxx"

--header "merchant_key: xxxxxxxxxxx"

--data-raw '

{

"merchant_usn":"12042142155",

"order_id":"1651001767957",

"installments":"1",

"installment_type":"4",

"authorizer_id":"446",

"amount":"1000",

"additional_data": {

"items": [

{

"quantity": "1",

"quantity_type": "u",

"unit_price": "50000",

"ean": "9283746529385",

"description": "bola para jogar 1"

},

{

"quantity": "2",

"quantity_type": "u",

"unit_price": "25000",

"ean": "9283746529384",

"description": "bola para jogar 2"

}

]

}

}'

Payment effectuation request

When using AME, it won't be necessary to send any card data.

Example:

--request POST "https://esitef-homologacao.softwareexpress.com.br/e-sitef/api/v1/payments/1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr"

--header "Content-Type: application/json"

--header "merchant_id: xxxxxxxx"

--header "merchant_key: xxxxxxxxxxx"

--data-raw '

{

}'

Payment effectuation response with non-standard size

Parameter	Description	Format
authorization_number	Authorization number.	< 100 AN

Attention:

In case of a communication failure in this operation, it will be necessary to create another transaction.

Example:

"code": "0",

"message": "OK. Transaction successful.",

"payment": {

"authorizer_code": "000",

"status": "PEN",

"nit": "a479f7d0fc3e3bdfe22f489298b9ca56fa98c4c7c56e2529eb4fddb44c7a392c",

"order_id": "1651003189064",

"authorizer_id": "446",

"acquirer_id": "271",

"acquirer_name": "CardSE",

"authorizer_date": "26/04/2022T16:59",

"authorization_number": "111111111122222222223333333333444444444455555555556666666666 ",

"merchant_usn": "12042142155",

"esitef_usn": "220426096883310",

"sitef_usn": "265428",

"host_usn": "000000000 ",

"amount": "1000",

"payment_type": "O",

"authorizer_merchant_id": "084675745000140",

"terminal_id": "ES000041",

"payment_date": "26/04/2022T16:59",

"qr_code": "The quick brown fox jumps over the lazy dog"

}

}

HTML Payment

There are no flow differences to the merchant.

As in the REST Payment, additional parameters on the transaction creation can be sent, using the same format.

REST Cancel

Cancel request

When using AME, it won't be necessary to send any card data.

Example:

--request PUT "https://esitef-homologacao.softwareexpress.com.br/e-sitef/api/v1/cancellations/1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr"

--header "Content-Type: application/json"

--header "merchant_id: xxxxxxxxxxx"

--header "merchant_key: xxxxxxxxxxx"

--data-raw '{

}'

Cancel response parameters

{

"code": "0",

"message": "OK. Transaction successful.",

"cancellation": {

"authorizer_code": "000",

"authorizer_message": "Lojista OK",

"status": "CON",

"nit": "1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr",

"order_id": "1651003189064",

"customer_receipt": "=== COMPROVANTE ===",

"merchant_receipt": "=== COMPROVANTE ===",

"authorizer_id": "446",

"acquirer_id": "1271",

"acquirer_name": "CardSE",

"authorizer_date": "26/04/2022T17:12",

"authorization_number": "265429",

"merchant_usn": "12042142155",

"esitef_usn": "220426096883331",

"sitef_usn": "265429",

"host_usn": "00000000000004265429 ",

"amount": "1000",

"payment_type": "O",

"authorizer_merchant_id": "084675745000140",

"esitef_date": "26/04/2022T17:12",

"is_host_cancel": "false"

}

}

Generate payment link on the Merchant's Portal

It's also possible to make AME payments using the payment link functionality of the Merchant's Portal. However, additional AME information cannot yet be sent.