});

Authorization with Authentication

After authentication is completed, the transaction undergoes the authorization process by submitting the authentication data in the “external authentication” (node ExternalAuthentication). This procedure is also valid for establishments that performed authentication outside Cielo (External MPI).

For more details about 3DS 2.0, please visit: https://braspag.github.io//en/manualp/emv3ds

See example below, describing the submission of authentication data from the Pagador API authorization request.

Request

{
   "MerchantOrderId":"2017051002",
   "Customer":
   {
     (...)
   },
   "Payment":
   {
     (...)
     "Provider":"Cielo30",
     "Authenticate":true,
     "ReturnUrl":"http://www.loja.com.br",
     "CreditCard":{
         "CardNumber":"4000000000001000",
         "Holder":"Nome do Portador",
         "ExpirationDate":"12/2021",
         "SecurityCode":"123",
         "Brand":"Visa",
         "SaveCard":"false"
     },
     "ExternalAuthentication":{
       "Cavv":"AAABB2gHA1B5EFNjWQcDAAAAAAB=",
       "Xid":"Uk5ZanBHcWw2RjRCbEN5dGtiMTB=",
       "Eci":"5",
       "Version":"2",
       "ReferenceID":"a24a5d87-b1a1-4aef-a37b-2f30b91274e6"
     }
   }
}
curl
--request POST "https://apisandbox.braspag.com.br/v2/sales"
--header "Content-Type: application/json"
--header "MerchantId: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
--header "MerchantKey: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
--data-binary
--verbose
{
   "MerchantOrderId":"2017051002",
   "Customer":
   {
     (...)
   },
   "Payment":
   {
     (...)
     "Provider":"Cielo30",
     "Authenticate":true,
     "ReturnUrl":"http://www.loja.com.br",
     "CreditCard":{
         "CardNumber":"4000000000001000",
         "Holder":"Nome do Portador",
         "ExpirationDate":"12/2021",
         "SecurityCode":"123",
         "Brand":"Visa",
         "SaveCard":"false"
     },
     "ExternalAuthentication":{
       "Cavv":"AAABB2gHA1B5EFNjWQcDAAAAAAB=",
       "Xid":"Uk5ZanBHcWw2RjRCbEN5dGtiMTB=",
       "Eci":"5",
       "Version":"2",
       "ReferenceID":"a24a5d87-b1a1-4aef-a37b-2f30b91274e6"
     }
   }
}
Field Description Type/Size Required
Payment.Provider Name of payment method provider: Cielo30, Getnet or Rede Text / 15 Yes
Payment.Authenticate Defines if the buyer will be directed to the issuing Bank for card authentication Boolean (true or false) Yes, when authentication was a success
Payment.ExternalAuthentication.ReturnUrl Return URL only applicable if version is “1” Alphanumeric [1024 positions] Yes
Payment.ExternalAuthentication.Cavv Signature that is returned in successful authentication scenarios Text Yes, when authentication was a success
Payment.ExternalAuthentication.Xid XID returned in authentication process Text Yes, when the 3DS version is “1”
Payment.ExternalAuthentication.Eci E-commerce Indicator Returned in Authentication Process Numeric [1 position] Yes
Payment.ExternalAuthentication.Version 3DS version used in authentication process Alphanumeric [1 position] Yes, when the version of 3DS is “2”
Payment.ExternalAuthentication.ReferenceID RequestID Returned in Authentication Process GUID [36 positions] Yes, when the version of 3DS is “2”

Response

See response at API REST Integration Guide

Authorization for Data Only Transactions

After the authentication step in Data Only model is completed (field bpmpi_auth_notifyonly set as “true”), the transaction undergoes the authorization process by sending the authentication data in the “external authentication” model (node ExternalAuthentication). See example below, describing the submission of authentication data from the Pagador API authorization request, using POST:

Request

{  
   "MerchantOrderId":"2017051002",
   "Customer":
   {  
     (...)
   },
   "Payment":
   {  
     (...)
     "Authenticate":false,
     "ReturnUrl":"http://www.loja.com.br",
     "CreditCard":{  
         "CardNumber":"4000000000001000",
         "Holder":"Nome do Portador",
         "ExpirationDate":"12/2021",
         "SecurityCode":"123",
         "Brand":"Visa",
         "SaveCard":"false"
     },
     "ExternalAuthentication":{
       "Eci":"4",
       "ReferenceID":"a24a5d87-b1a1-4aef-a37b-2f30b91274e6",
       "dataonly":true
     }
   }
}
--request POST "https://apisandbox.cieloecommerce.cielo.com.br/1/sales"
--header "Content-Type: application/json"
--header "MerchantId: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
--header "MerchantKey: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
--data-binary
--verbose
{  
   "MerchantOrderId":"2017051002",
   "Customer":
   {  
     (...)
   },
   "Payment":
   {  
     (...)
     "Authenticate":false,
     "ReturnUrl":"http://www.loja.com.br",
     "CreditCard":{  
         "CardNumber":"4000000000001000",
         "Holder":"Nome do Portador",
         "ExpirationDate":"12/2021",
         "SecurityCode":"123",
         "Brand":"Visa",
         "SaveCard":"false"
     },
     "ExternalAuthentication":{
       "Eci":"4",
       "ReferenceID":"a24a5d87-b1a1-4aef-a37b-2f30b91274e6",
       "dataonly":true
     }
   }
}
FIELD DESCRIPTION TYPE/SIZE REQUIRED
Payment.Authenticate Defines if the buyer will be directed to the issuing Bank for card authentication Boolean (true or false) Yes. For Data Only transactions the value must be “false”
Payment.ExternalAuthentication.Eci E-commerce Indicator returned in authentication process Numeric [1 position] Yes
Payment.ExternalAuthentication.ReferenceId RequestID returned in authentication process GUID [36 positions] Yes
Payment.ExternalAuthentication.DataOnly Defines if transaction is Data Only Boolean (true or false) Yes. For Data Only transactions the value must be “true”

Response

See API Rest Integration Guide for detailed examples of Authorization with Authentication response.

ECI Table

BRAND ECI TRANSACTION MEANING
Visa 06 Authenticated by the card brand – chargeback risk is held by the issuer
Visa 05 Authenticated by the issuer – chargeback risk is held by the issuer
Visa Different from 05 and 06 Non-authenticated – chargeback risk is held by the merchant
Mastercard 01 Authenticated by the card brand – chargeback risk is held by the issuer
Mastercard 02 Authenticated by the issuer – chargeback risk is held by the issuer
Mastercard 03 Non-authenticated, Data Only transaction – chargeback risk is held by the merchant
Mastercard Different from 01, 02, and 04 Non-authenticated – chargeback risk is held by the merchant