### Request Access Token - Shell Example Source: https://docs.cielo.com.br/ecommerce-cielo/docs/integrando-com-o-sop This snippet demonstrates how to make a POST request to the Cielo E-commerce API to obtain an access token. It includes the necessary endpoint, headers for content type, merchant ID, and authorization, along with verbose output for debugging. ```shell --request POST "https://transactionsandbox.pagador.com.br/post/api/public/v2/accesstoken" --header "Content-Type: application/json" --header "MerchantId: XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX" --header "Authorization: Bearer faSYkjfiod8ddJxFTU3vti_ ... _xD0i0jqcw" --data-binary --verbose ``` -------------------------------- ### Card On File Usage Example (JSON) Source: https://docs.cielo.com.br/ecommerce-cielo/docs/card-on-file-1 Example JSON structure for the CardOnFile node, specifying its usage ('First' or 'Used') and reason ('Recurring' or 'Subscription'). This is crucial for differentiating initial stored card transactions from subsequent ones. ```json { "CardOnFile":{ "Usage": "Used", "Reason":"Recurring" } } ``` -------------------------------- ### Implementing Events Source: https://docs.cielo.com.br/ecommerce-cielo/docs/integrando-com-o-sop Information about the events that can be implemented to handle script outcomes. ```APIDOC ## Implementing Events ### Description Details the three events provided by the Cielo script for handling transaction outcomes. ### Events - **onSuccess**: Event for successful transactions. Returns the `PaymentToken` and card data if card verification was requested. The `PaymentToken` is single-use and invalidated after processing. - **onError**: Event for transaction errors. Returns the error code and description. - **onInvalid**: Event for invalid data input. Returns details about fields with errors. Error messages are available in Portuguese (default), English, and Spanish. ``` -------------------------------- ### ABU Response Example - JSON Source: https://docs.cielo.com.br/ecommerce-cielo/docs/automatic-billing-updater-abu Example of a recurring credit transaction response with 'CardBrandStatus' and 'NewCard' fields. This JSON structure indicates the status of the card and provides updated card details if available. ```json { "Payment":{ "CardBrandStatus":"VALID", "NewCard": { "CardNumber": "40000000000000000", "ExpirationDate": "10/2032", "SaveCard": true, "Brand": "Master" } } } ``` -------------------------------- ### Authorizing with PaymentToken Source: https://docs.cielo.com.br/ecommerce-cielo/docs/integrando-com-o-sop Instructions on how to use a PaymentToken for payment authorization via the Cielo E-commerce API. ```APIDOC ## Authorizing with PaymentToken ### Description Guides on how to perform payment authorization using a `PaymentToken` obtained from the Cielo script, replacing card details with the token. ### Credit Card Authorization - To submit a credit transaction, send the parameter `Payment.CreditCard.PaymentToken` instead of `Payment.CreditCard`. - Learn more in the API Cielo E-commerce manual. ### Debit Card Authorization - To submit a debit transaction, send the parameter `Payment.DebitCard.PaymentToken` instead of `Payment.DebitCard`. - Learn more in the API Cielo E-commerce manual. ### Request Example (Conceptual) ```json { "Payment": { "CreditCard": { "PaymentToken": "YOUR_PAYMENT_TOKEN_HERE" } } } ``` ### Response Example (Conceptual Success) ```json { "status": "authorized", "paymentId": "some-payment-id" } ``` ``` -------------------------------- ### Payment Tokenization Source: https://docs.cielo.com.br/ecommerce-cielo/docs/integrando-com-o-sop Details on how card tokenization works and its impact on the token returned by the script. ```APIDOC ## Payment Tokenization ### Description Explains the behavior of the `CardToken` and `PaymentToken` based on the `enableTokenize` script parameter. ### Parameters #### Script Parameters - **enableTokenize** (boolean) - If set to `true`, the script will return a `CardToken` instead of a `PaymentToken`. ### Additional Information - Learn more about `CardToken` at: https://docs.cielo.com.br/ecommerce-cielo/docs/tokenizando-cartoes - `PaymentToken` can be used for a single authorization and/or within a 20-minute period. After processing, it will be invalidated. ``` -------------------------------- ### POST /v2/accesstoken - Obtain SOP Access Token Source: https://docs.cielo.com.br/ecommerce-cielo/docs/integrando-com-o-sop Create the Silent Order Post (SOP) AccessToken by sending a POST request. This token is used in the subsequent script execution. ```APIDOC ## POST /v2/accesstoken - Obtain SOP Access Token ### Description Create the Silent Order Post (SOP) AccessToken by sending a POST request. This token is used in the subsequent script execution. ### Method POST ### Endpoint - Sandbox: `https://transactionsandbox.pagador.com.br/post/api/public/v2/accesstoken` - Production: `https://transaction.pagador.com.br/post/api/public/v2/accesstoken` ### Parameters #### Headers - **Authorization** (string) - Required - `"Bearer {access_token}"` where `{access_token}` is the OAuth2 token obtained from the previous step. ### Request Example ```shell POST https://transactionsandbox.pagador.com.br/post/api/public/v2/accesstoken Authorization: Bearer {access_token} ``` ### Response *The response structure for this endpoint is not provided in the input text.* ``` -------------------------------- ### Access Token Response JSON Example Source: https://docs.cielo.com.br/ecommerce-cielo/docs/integrando-com-o-sop This JSON structure represents a successful response from the Cielo E-commerce API when requesting an access token. It includes the Merchant ID, the generated Access Token, and the issuance and expiration times for the token. ```json { "MerchantId": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX", "AccessToken": "MzA5YWIxNmQtYWIzZi00YmM2LWEwN2QtYTg2OTZjZjQxN2NkMDIzODk5MjI3Mg==", "Issued": "2023-08-05T08:50:04", "ExpiresIn": "2023-08-05T09:10:04" } ``` -------------------------------- ### Cielo Script JSON Return Example Source: https://docs.cielo.com.br/ecommerce-cielo/docs/integrando-com-o-sop This JSON object represents the typical return structure from the Cielo e-commerce script. It includes a `PaymentToken` for authorization and detailed card information such as brand, last four digits, and issuer, particularly when BIN query is enabled. ```json { "PaymentToken": "366f8470-54d0-43cb-95f5-c80a502afc27", "ForeignCard": false, "BinQueryReturnCode": "00", "BinQueryReturnMessage": "Analise autorizada", "Brand": "Visa", "VerifyCardStatus": 1, "VerifyCardReturnCode": "00", "VerifyCardReturnMessage": "Transacao autorizada", "CardBin": "453202", "CardLast4Digits": "4044", "CardType": "Multiple", "Issuer": "Banco Santander", "IssuerCode": "033", "Prepaid": false } ``` -------------------------------- ### Exemplo de Implementação de Script de Autenticação em HTML Source: https://docs.cielo.com.br/ecommerce-cielo/docs/implementando-script Este snippet demonstra a estrutura básica de um arquivo HTML para implementar um script de autenticação. Inclui campos ocultos para configuração de autenticação, detalhes do pedido, informações de pagamento com cartão e opções de recorrência. A função `sendOrder` é responsável por iniciar o processo de autenticação chamando `bpmpi_authenticate`. ```html Sample

Sample

Gift Card
``` -------------------------------- ### IssuerTransactionId Response Example Source: https://docs.cielo.com.br/ecommerce-cielo/docs/identificadores-da-bandeira Example of a credit card transaction response including the IssuerTransactionId. ```APIDOC ## GET /any/endpoint ### Description This endpoint returns an example response for a credit card transaction, demonstrating the `IssuerTransactionId` field. ### Method GET ### Endpoint /any/endpoint ### Parameters #### Path Parameters None #### Query Parameters None #### Request Body None ### Request Example ```json { "example": "No request body for this example" } ``` ### Response #### Success Response (200) - **MerchantOrderId** (string) - Order identification number. - **Payment.Type** (string) - Type of payment method. - **Payment.Amount** (number) - Order amount (in cents). - **Payment.Installments** (number) - Number of installments. - **Payment.Capture** (boolean) - Indicates if the authorization should be with automatic capture or later capture. - **Payment.IssuerTransactionId** (string) - Issuer authentication identifier for recurring credit and debit transactions. - **Payment.Recurrent** (boolean) - Indicates if the transaction is of the recurring type. - **CreditCard.CardNumber** (string) - Card number. - **CreditCard.Holder** (string) - Cardholder name. - **CreditCard.ExpirationDate** (string) - Card expiration date. - **CreditCard.SaveCard** (string) - Indicates if the card should be saved. - **CreditCard.Brand** (string) - Card brand. - **CreditCard.CardOnFile.Usage** (string) - Indicates the usage of the card on file. - **CreditCard.CardOnFile.Reason** (string) - Indicates the reason for using the card on file. #### Response Example ```json { "MerchantOrderId": "2014111701", "Payment": { "Type": "CreditCard", "Amount": 15700, "Capture": true, "Recurrent": "true", "IssuerTransactionId": "580027442382078", "Installments": 1, "CreditCard": { "CardNumber": "1234123412341231", "Holder": "Teste Holder", "ExpirationDate": "12/2030", "SaveCard": "false", "Brand": "Visa", "CardOnFile": { "Usage": "Used", "Reason": "Recurring" } } } } ``` ``` -------------------------------- ### JavaScript Braspag MPI 3DS2.0 Configuration and Event Handlers Source: https://docs.cielo.com.br/ecommerce-cielo/docs/implementando-script This JavaScript code configures the Braspag MPI 3DS2.0 authentication. It defines an `bpmpi_config` function that returns an object with various event handlers for authentication success, failure, unenrolled status, disabled status, errors, and unsupported brands. It also handles environment configuration based on query parameters and includes a helper function `getQueryString`. ```javascript var env = getQueryString("env"); function bpmpi_config() { return { onReady: function () { // Evento indicando quando a inicialização do script terminou. document.getElementById("btnSendOrder").disabled = false; }, onSuccess: function (e) { // Cartão elegível para autenticação, e portador autenticou com sucesso. var cavv = e.Cavv; var xid = e.Xid; var eci = e.Eci; var version = e.Version; var referenceId = e.ReferenceId; }, onFailure: function (e) { // Cartão elegível para autenticação, porém o portador finalizou com falha. var xid = e.Xid; var eci = e.Eci; var version = e.Version; var referenceId = e.ReferenceId; }, onUnenrolled: function (e) { // Cartão não elegível para autenticação (não autenticável). var xid = e.Xid; var eci = e.Eci; var version = e.Version; var referenceId = e.ReferenceId; }, onDisabled: function () { // Loja não requer autenticação do portador (classe "bpmpi_auth" false -> autenticação desabilitada). }, onError: function (e) { // Erro no processo de autenticação. var xid = e.Xid; var eci = e.Eci; var returnCode = e.ReturnCode; var returnMessage = e.ReturnMessage; var referenceId = e.ReferenceId; }, onUnsupportedBrand: function (e) { // Bandeira não suportada para autenticação. var returnCode = e.ReturnCode; var returnMessage = e.ReturnMessage; }, Environment: env ? env : "SDB", Debug: true, }; } function getQueryString(field) { var href = window.location.href; var reg = new RegExp("[?&]" + field + "=([^&#]*)", "i"); var string = reg.exec(href); return string ? string[1] : null; } ``` -------------------------------- ### Exemplo de Retorno do Script de Autenticação 3DS Source: https://docs.cielo.com.br/ecommerce-cielo/docs/implementando-script Demonstra os formatos de retorno esperados do script de autenticação 3DS em diferentes cenários: sucesso, falha geral e quando a bandeira do cartão não é suportada. Estes retornos contêm informações cruciais para o processamento da transação. ```json { "Cavv": "Y2FyZGluYWxjb21tZXJjZWF1dGg=", "Xid": null, "Eci": "01", "Version": "2.2.0", "ReferenceId": "973cf83d-b378-43d5-84b6-ce1531475f2a" } ``` ```json { "Xid": null, "Eci": null, "ReturnCode": "231", "ReturnMessage": "Unexpected error ocurred", "ReferenceId": null } ``` ```json { "Xid": null, "Eci": null, "ReturnCode": "MPI600", "ReturnMessage": "Brand not supported for authentication", "ReferenceId": null } ``` -------------------------------- ### Cielo E-commerce API Response Example Source: https://docs.cielo.com.br/ecommerce-cielo/docs/conversor-moedas-3ds This is an example of a successful response from the Cielo E-commerce API after confirming currency conversion. It includes transaction details, status codes, and links for further actions. ```json { "Status": 2, "ReasonCode": 0, "ReasonMessage": "Successful", "ProviderReturnCode": "6", "ProviderReturnMessage": "Transacao capturada com sucesso", "ReturnCode": "6", "ReturnMessage": "Transacao capturada com sucesso", "Tid": "28FGHJKTIOLPDSD28GM88FC", "ProofOfSale": "027113", "AuthorizationCode": "025930", "Links": [ { "Method": "GET", "Rel": "self", "Href": "https://apiquery.cieloecommerce.cielo.com.br/1/sales/cedbc48e-81ba-47eb-ba5d-609955d344ee" }, { "Method": "PUT", "Rel": "void", "Href": "https://api.cieloecommerce.cielo.com.br/1/sales/cedbc48e-81ba-47eb-ba5d-609955d344ee/void" } ] } ``` -------------------------------- ### Enabling Alelo Voucher Functionality Source: https://docs.cielo.com.br/ecommerce-cielo/docs/voucher Information on how to enable Alelo voucher payments for your establishment. ```APIDOC ## Enabling Alelo Voucher Functionality ### Description Before an establishment (EC) can accept Alelo voucher payments via the Cielo E-commerce API, this functionality must be pre-enabled. The enablement request must be made directly with Alelo. ### Process 1. **Request Enablement from Alelo**: Contact Alelo directly to request the enablement of their voucher functionality. 2. **Confirmation**: After Alelo enables the brand, merchants can proceed with the integration development with the Cielo API. 3. **Verification**: To check if the Alelo brand is enabled, visit the Cielo website in the "fees and plans" section. ``` -------------------------------- ### Marcação de Recorrência Programada Cielo em Transação Source: https://docs.cielo.com.br/ecommerce-cielo/docs/recorrencia Exibe a estrutura JSON necessária para configurar uma 'Recorrência Programada Cielo'. Inclui detalhes como o período de cobrança e a data final, permitindo que a Cielo gerencie o ciclo de pagamentos automaticamente. A chave `RecurrentPayment` é fundamental para este tipo de recorrência. ```json { "RecurrentPayment": { "Interval": "monthly", "EndDate": "2024-12-31" } } ``` -------------------------------- ### User Account Information Source: https://docs.cielo.com.br/ecommerce-cielo/docs/mapeando-classes This section outlines the parameters related to user account details, including guest status and account activity timestamps. ```APIDOC ## User Account Parameters ### Description Parameters related to user account details, including guest status and account activity timestamps. ### Parameters #### Request Body - **bpmpi_useraccount_guest** (boolean) - Recommended - Indicates if the buyer is a guest buyer (true/false). - **bpmpi_useraccount_createddate** (string) - Recommended - The date the buyer's account was created (YYYY-MM-DD). - **bpmpi_useraccount_changeddate** (string) - Recommended - The date of the last change to the buyer's account (YYYY-MM-DD). - **bpmpi_useraccount_passwordchangeddate** (string) - Recommended - The date of the last password change for the buyer's account (YYYY-MM-DD). - **bpmpi_useraccount_authenticationmethod** (string) - Recommended - The buyer's authentication method in the store (e.g., '01' - No authentication, '02' - Store login, '03' - Federated ID login, '04' - FIDO authenticator login). - **bpmpi_useraccount_authenticationprotocol** (string) - Recommended - The login protocol used in the store (alphanumeric, up to 2048 characters). - **bpmpi_useraccount_authenticationtimestamp** (string) - Recommended - The date and time the login was performed in the store (YYYY-MM-DDTHH:mm:SS). - **bpmpi_merchant_newcustomer** (boolean) - Recommended - Identifies if the buyer is a new customer to the store (true/false). ### Request Example ```json { "bpmpi_useraccount_guest": false, "bpmpi_useraccount_createddate": "2023-01-15", "bpmpi_useraccount_changeddate": "2023-10-20", "bpmpi_useraccount_passwordchangeddate": "2023-09-01", "bpmpi_useraccount_authenticationmethod": "02", "bpmpi_useraccount_authenticationprotocol": "OAuth2", "bpmpi_useraccount_authenticationtimestamp": "2023-10-26T10:30:00", "bpmpi_merchant_newcustomer": false } ``` ### Response #### Success Response (200) (No specific success response body defined for this section, assumes success based on request validation) #### Response Example (No specific response example provided for this section) ``` -------------------------------- ### Authentication API Source: https://docs.cielo.com.br/ecommerce-cielo/docs/token-acesso This section details how to authenticate with the Cielo BR E-commerce API to obtain an access token. It includes information on the request body, success responses, and error handling. ```APIDOC ## POST /oauth/token ### Description Obtains an access token for authenticating 3DS requests. A new token must be obtained for each authentication. ### Method POST ### Endpoint /oauth/token ### Parameters #### Request Body - **client_id** (string) - Required - The client ID obtained during registration. - **client_secret** (string) - Required - The client secret obtained during registration. - **grant_type** (string) - Required - Should be set to `client_credentials` for this endpoint. ### Request Example ```json { "client_id": "YOUR_CLIENT_ID", "client_secret": "YOUR_CLIENT_SECRET", "grant_type": "client_credentials" } ``` ### Response #### Success Response (200) - **access_token** (string) - The access token required for authentication. - **token_type** (string) - The type of token, typically 'bearer'. - **expires_in** (string) - The time in seconds until the token expires. #### Response Example ```json { "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJjbGllbnRfbmFtZSI6IlFBXzNEU19BdXRoZW50aWNhdG9yIiwiY2xpZW50X2lkIjoiZGJhM2E4ZGItZmE1NC00MGUwLThiYWItN2JmYjliNmYyZTJlIiwic2NvcGVzIjoie1wiU2NvcGVcIjpcIjNEU0F1dGhlbnRpY2F0b3JcIixcIkNsYWltc1wiOlt7XCJOYW1lXCI6XCJNZXJjaGFudE5hbWVcIixcIlZhbHVlc1wiOFwiVmFsdWVzXCI6W1wiNTU1NVwiXX0se1wiTmFtZVwiOlwiUmVmZXJlbmNlSWRcIixcIlZhbHVlc1wiOltcImY3MjE1YmQ3LWM0OTQtNGQ5Yi1NzEyfQ.daMqXko3dZOV0TzNFQ2vSsVSKqOsrwuswg7RB82ecAASSSSSSSSSSSSFFFFFFFFFFFFFGGGGGGGGGGGGGGGGGGGGGGGG", "token_type": "bearer", "expires_in": "86399" } ``` > ⚠️ Attention > - For each 3DS authentication, a new access token must be obtained and provided. > - When testing in a sandbox environment via Postman, enter the `ClientId` and `ClientSecret` directly. Postman will automatically Base64 encode these credentials for authentication. ```