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

sequenceDiagram
    participant C as Customer
    participant L as Merchant
    participant E as Online Payment
    participant A as Authorizer
    C->>+L: Checkout
    L->>+E: 1. Creates Transaction
    E-->>-L: nit
    L->>+E: 2. Performs payment(nit)
    E-->>-L: PEN status, QR code
    L-->>-C: 3. Displays QR code
    C->>+A: 4. Scans QR code
    A-->>-C: Payment Confirmation
    E->>+A: 5. Query payment
    A-->>-E: Payment confirmed
    L->>+E: 6. Query transaction
    E-->>-L: CON status

The merchant creates the transaction on Carat Portal passing some additional AME information and receives a NIT as a response.
The merchant calls the payment effectuation service and receives a QR code and a transaction with PEN (pending) status.
The merchant displays the QR code to the customer.
The customer scans the QR code with the AME app and goes through the payment confirmation procedures requested by the authorizer.
While the customer finishes the payment, Carat Portal will query the sale situation on the authorizer until the transaction ends.
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.

Updated 15 days ago