What is Checkout?

Checkout is the final stage of the purchasing process in an online store. It refers to the last part during the customer's browsing stage. This is the time when the customer needs to enter their personal details to make the payment, such as their card number and CPF (Cadastro Nacional de Pessoa Física): Brazilian Individual Taxpayer’s Identification Number (equivalent to Social Security Number USA).

Note that cart abandonment can occur at this stage. This occurs when the buyer decides to abandon the purchase when it comes time to make the payment. This can happen for various reasons. If a website is not well structured, the chances of losing the sale increase significantly. When buying online, consumers don't have to leave the house and queue for hours. All it takes is a few clicks for the purchase to be completed and the goods to arrive in a few days.

Today, e-commerce is one of the easiest and simplest ways to buy a product. It is therefore essential to ensure that this process is safe, agile and efficient. For this, the page where the checkout takes place needs to have a good system, so that the customer can complete the purchase quickly and without any major setbacks. Since there's no point in attracting customers to your e-commerce, but having a checkout process that leaves the customer confused when it comes to concluding the purchase.

Overview – Adiq Checkout

The purpose of this documentation is to guide the developer on how to integrate with the Adiq Ecommerce API, describing the functionalities and methods to be used, listing information to be sent and received and providing examples.

In this manual you will find references to all the operations related to creation, consultation and webhook. These operations must be performed using your specific key on the respective environment endpoints:

Attention: Transactions pre-authorized by the checkout must be captured in PUT /v1/payments/(paymentId)/capture, please follow this link.

In order to perform an operation, combine the environment's base URL with the URL of the desired operation and send it using the HTTP verb as described in the operation.

Adiq Checkout Navigation Flow

Start Screen

Presents the order items and the customer's personal details.

Address Screen

Presents the addresses to be confirmed for the purchase.

Payment Method Selection Screen

Presents debit, credit and pix payment methods.

Registered Card Screen

The customer must provide their card details.

Registered Card Screen

The customer must provide their card details.

Pix Selection Screen

Customers will see the value and expiry time of the Pix.

Pix Payment Screen via QR Code

Customers must follow the instructions to pay for the pix via the QR Code.

Pix Expiration Screen

Screen with instructions related to expired pix.

Receipt Screen – Payment performed

Presents a receipt that the transaction has been authorized.

Payment Failure Screen when Payment Method is Denied

Presents the message that the payment was not authorized and will be asked to make a new attempt with the payment methods offered.

Checkout will be blocked

Checkout may be blocked for the following reasons:

• Exceed payment attempts by a maximum of 5 or less, depending on how it was configured when creating the checkout via the POST v1/checkout.
• Rejected by the anti-fraud process.

Access to a Non-Existing or Expired Checkout

Presents the screen with the alert that the checkout does not exist or is expired.

Access to a Checkout that has Already been Paid For

Presents the purchase receipt screen with the order data.

Customization of the Checkout Layout

Customization of the layout offers several options for adapting the appearance of your store to your specific preferences and needs. You can change the colors, allowing the color scheme to reflect your brand's visual identity. You can also modify the fonts, choosing type styles that best match the tone and personality of your business.

In addition to the colors and fonts, it is also possible to add your store's logo, ensuring that the brand identity is clearly visible throughout the layout. Other customizable aspects include the layout of the pages, where you can organize and reorganize sections such as headers and navigation menus and content areas to improve the user experience and usability of the site.

With all these customization options, you can create a layout that not only meets your functional needs, but also reflects your brand's personality and values, providing an engaging and memorable experience for your store's visitors.

In order to customize your layout, please contact us at atendimento@adiq.com.br

Create a Checkout

Authentication

The APIs listed in this documentation use Basic Auth authentication, which means that in all requests it is mandatory to enter an access token that will be obtained through authentication with your Client ID and Client Secret

Generation of the access token

In order to create an access token, you need to send a Request using HTTP Basic Authentication via the POST method as shown in the example:

Request

                    
                        
{
    "grantType": "client_credentials"
}	
                        
                    

                

Response

                    
                        
{
    "accessToken": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1bmlxdWVfbmFtZSI6WyJBRElRIiwiQURJUQ",
    "tokenType": "Bearer",
    "expiresIn": "36000",
    "scope": "GatewayEcommerce"
}
                        			
                    
                

Payment with Credit/Debit Card and Pix

Request

                    
                        
{
    "view": "modal",
    "payment": {
        "checkoutOrderNumber": "12345646546456456456",
        "softDescriptor": "PAG*TESTE",
        "successPostUrl": "https://empresa.com.br/sucesso/12345646546456456456",
        "failPostUrl": "https://empresa.com.br/falha/12345646546456456456",
        "expireInMinutes": 4320,
        "captureType": "ac",
        "cardAttemps": 2,
        "types": [
            "credit",
            "debit",
            "pix"
            ],
        "maxInstallment": 1,
        "returnSuccessUrl": "https://empresa.com.br/sucesso/12345646546456456456",
        "returnFailUrl": "https://empresa.com.br/falha/12345646546456456456",
    },
    "customer": {
        "firstName": "Josh",
        "lastName": "Joe",
        "cpfCnpj": "43538559058",
        "email": "customer@empresa.com",
        "phone": "5511911112222"
    },
    "billTo": {
        "address": "rua expedito",
        "number": "12454",
        "neighborhood": "vila clementina",
        "complement": "",
        "city": "São Paulo",
        "state": "SP",
        "zipCode": "45454545",
        "country": "BR"
    },
    "shipTo": {
        "address": "rua expedito",
        "number": "12454",
        "neighborhood": "vila clementina",
        "complement": "",
        "city": "São Paulo",
        "state": "SP",
        "zipCode": "45454545",
        "country": "BR",
        "firstName": "Josh",
        "lastName": "Joe",
        "phone": "5511911112222"
    },
    "threeDs": {
        "urlSite": "lojavirtual.com.br",
        "creditEnabled": true
    },
    "antifraud": {
        "checkDocBearer": false
    },
    "shipping": {
        "description": "Sedex",
        "type": "delivery",
        "price": 1549
    },
    "lineItems": [
        {
            "code": "012121",
            "sku": "CALCALCAL42",
            "name": "t-shirt",
            "qty": 1,
            "unitPrice": 5900
        },
        {
            "code": "012155",
            "sku": "PANPAN51",
            "name": "pants",
            "qty": 2,
            "unitPrice": 9900
        }
    ]
}	
                        
                    
                

Response Status Code 200

                    
                        
{
    "url": "https://checkout.adiq.io/37ccd769-a4f5-4201-bcb7-f45c5d0b1ebc",
    "checkoutId": "37ccd769-a4f5-4201-bcb7-f45c5d0b1ebc",
    "checkoutOrderNumber": "12345646546456456456",
    "status": "created",
    "totalProductAmount": 257,
    "shippingPrice": 15.49,
    "expiredAt": "2024-06-22T10:27:01.7429831-03:00"
}
                        
                    
                

Response Status Code 400

                    
                        
[
    {
    "tag": "Campo",
    "description": "Não pode ser nulo ou vazio"
    }
]
                        
                    
                

Consult a Checkout

The consultation will tell you if it has already been paid, expired, blocked, being processed or checked.

Provides a history of the events that have occurred in the customer's actions on the checkout.

Request

                    
                        
{
    "status": "paid",
    "checkoutOrderNumber": "TESTE-123472",
    "transaction": {
        "pix": { 
            "status": "Pago", 
            "amount": 400,  
            "qrCode": "00020126420014br.gov.bcb.pix0120adiqplus@adiq.com.br520400005303986540510.005802BR5908ADIQPLUS600", 
            "qrCodeId": "xRC35GjYIcz+ATVq90Q6mib+VQPD23xExYPY0UzinIY=",	 
            "endToEndId":"E245475545454654754654545P", 
            "orderNumber": "c72fcad9-bfa7-4316-b48a-31c11cea303e", 
            "posTransactionId": "05c5eacd-5712-49b5-b4b5-3feb6aa90119", 
            "paymentDate": "2024-07-15T15:43:07.8291734-03:00", 
            “payer”: { 
                     “name”: “Joe Doe”, 
                     “documentType”: “cpf”, 
                     “document”: “79319845018” 
            } 
        }
        "card": {
            "numberMasked": "40000000****1091",
            "returnCode": "0",
            "description": "Sucesso",
            "authorizationCode": "953715",
            "orderNumber": "5175d8c9ed2d4",
            "amount": 400,
            "releaseAt": "2024-06-19T18:40:15.7046589-03:00",
            "installment": 1,
            "captureType": "ac",
            "transactionType": "credit",
            "threeDs": {
                "status": "Challenge",
                "eci": "05",
                "threeDsversion": "2.1.0",
                "paresStatus": "Y",
                "threeDsStatus": "AUTHENTICATION_SUCCESSFUL"
            }
        }
    },
    "transactionHistory": [
        {
            "transactionDate": "2024-06-19T18:39:57.2044224-03:00",
            "paymentType": "credit",
            "transactionOrderNumber": "5175d8c9ed2d4",
            "code": "status awaiting treatment",
            "description": "Challenge transaction"
        },
        {
            "transactionDate": "2024-06-19T18:40:12.3969634-03:00",
            "paymentType": "credit",
            "transactionOrderNumber": "5175d8c9ed2d4",
            "code": "0",
            "description": "Sucesso"
        },
        {
            "transactionDate": "2024-06-19T18:38:12.3969634-03:00",
            "paymentDate" "2024-06-19T18:41:12.3969634-03:00",
            "paymentType": "pix",
            "transactionOrderNumber": "d1bcf03b429e437ab29262f0315cc73a",
            "status": "success"
        }
    ]
}
                        
                    
                

Webhook

In order to be notified of payment attempt events and completed checkouts, facilitating processing on the store side, follow these steps: Whenever you receive a success notification, the store system must look up more details of the checkout in the API GET /v1/checkout/authorization/(checkoutId). This instruction is mandatory for the store to make sure that the transaction has actually taken place.

Recurrence of Attempts

The webhook is configured to attempt to communicate with the specified success or failure URL up to five times.

Below is a simulation of the communication attempts, including the number of each attempt and the corresponding time:

Payment Successfully Executed

This webhook indicates that the checkout was successful.

Request

                    
                        
{
    "PaymentId": "020046766206211937370002243237650000000000",
    "OrderNumber": "eF9nSlwD2yUVJ",
    "CheckoutOrderNumber": "19349946456456456999991",
    "StatusDescription": "Sucesso",
    "StatusCode": "00", 
    "Date": "2024-06-22T15:45:26.9969839-03:00",
    "PaymentMethod": "Checkout"
}
                        
                    
                

Response Status Code 200

Indicates that it was successfully received.

Response Status Code Others

Indicates that it has failed and a new webhook attempt will be made later.

Events in Checkout

This webhook indicates that there have been some events in Checkout

Request

                    
                        
{
    "CheckoutOrderNumber": "19349946456456456999991",
    "StatusDescription": "Checkout had a transaction denied.",
    "StatusCode": "01", 
    "Date": "2024-06-22T15:45:26.9969839-03:00",
    "PaymentMethod": "Checkout"
}
                        
                    
                

Response Status Code 200

Indicates that it was successfully received.

Response Status Code Others

Indicates that it has failed and a new webhook attempt will be made later.

Domain