Create payment with network token via external integration

Create payment using brand token created outside Cielo

ℹ️

Learn more about this feature in the documentation.

If the merchant uses a gateway or another partner that already offers the network token solution, it is necessary to send some specific parameters in the request to the Cielo E-commerce API so that the card network receives the token data.

  • Payment.CreditCard.Cryptogram: this is the token cryptogram generated by the card network for each transaction and associates the token with a specific transaction;
  • Payment.IssuerTransactionId: this is the card network's identifier for transactions in a series of recurrences (stored credentials). It is important to send the Payment.IssuerTransactionId with each transaction so that the card brand and issuer can identify that there is a previous transaction with that token (and improve the chances of approval).

Warning

We always recommend sending the cryptogram; if the cryptogram is not sent, the merchant must send the Payment.IssuerTransactionId.

Check out the example request for using a card token with external integration:

Request

EnvironmentMethodEndpoint
Sandboxhttps://apisandbox.cieloecommerce.cielo.com.br/
Productionhttps://api.cieloecommerce.cielo.com.br/

Header parameters

ParameterDescriptionTypeSizeRequired
Content-TypeMedia type accepted by the resource.String40Yes
MerchantIdStore identifier in Cielo.String36Yes
MerchantKeyPublic key for dual authentication in Cielo.String40Yes
RequestIdRequest identifier, used when the store uses different servers for each GET/POST/PUT.String36No

Body Parameters

Check the standard credit card request to verify all mandatory fields. The table below presents the exclusive parameters for tokenization via external integration.

ParameterTypeSizeRequiredDescription
Payment.CreditCard.CardNumberText19YesToken generated by the brand (DPAN). Indication that the CardNumber should be filled with the DPAN in case of brand tokenization
Payment.CreditCard.HolderText25YesBuyer's Name printed on the card.
Payment.CreditCard.CryptogramText28ConditionalCryptogram generated by the brand. Must be sent if tokenization is done by the brand (external integration).
Payment.CreditCard.ExpirationDateText7YesExpiration date of the token generated by the brand.
Payment.CreditCard.SecurityCodeText4NoSecurity code printed on the back of the card - See Attachment.
Payment.CreditCard.SaveCardBoolean***No (Default false)Boolean that identifies if the card will be saved to generate the CardToken. Learn more about Tokenization.
Payment.CreditCard.BrandText10YesCard brand (Visa / Master / Amex / Elo / Aura / JCB / Diners / Discover / Hipercard).

*Must be sent if tokenization is done by the brand (external integration).


Example of the request

{
  "MerchantOrderId": "Loja123456",
  "Customer": {
    "Name": "Comprador Teste",
    "Email": "[email protected]",
    "Birthdate": "1991-01-02",
    "Address": {
      "Street": "Rua Teste",
      "Number": "123",
      "Complement": "AP 123",
      "ZipCode": "12345987",
      "City": "Rio de Janeiro",
      "State": "RJ",
      "Country": "BRA"
    },
    "DeliveryAddress": {
      "Street": "Rua Teste",
      "Number": "123",
      "Complement": "AP 123",
      "ZipCode": "12345987",
      "City": "Rio de Janeiro",
      "State": "RJ",
      "Country": "BRA"
    }
  },
  "Payment": {
    "Type": "CreditCard",
    "Amount": 15700,
    "Currency": "BRL",
    "Country": "BRA",
    "ServiceTaxAmount": 0,
    "Installments": 1,
    "Interest": "ByMerchant",
    "Capture": true,
    "Authenticate": false,
    "SoftDescriptor": "123456789ABCD",
    "CreditCard": {
      "CardNumber": "1234123412341231",
      "Holder": "Teste Holder",
      "Cryptogram": "abcdefghijklmnopqrstuvw==",
      "ExpirationDate": "12/2030",
      "SecurityCode": "123",
      "SaveCard": "true",
      "Brand": "Visa"
    }
  }
}

Response

{
    "MerchantOrderId": "Loja123456",
    "Customer": {
        "Name": "Comprador Teste",
        "Identity":"11225468954",
        "IdentityType":"CPF",
        "Email": "[email protected]",
        "Birthdate": "1991-01-02",
        "Address": {
            "Street": "Rua Teste",
            "Number": "123",
            "Complement": "AP 123",
            "ZipCode": "12345987",
            "City": "Rio de Janeiro",
            "State": "RJ",
            "Country": "BRA"
        },
        "DeliveryAddress": {
            "Street": "Rua Teste",
            "Number": "123",
            "Complement": "AP 123",
            "ZipCode": "12345987",
            "City": "Rio de Janeiro",
            "State": "RJ",
            "Country": "BRA"
        }
    },
    "Payment": {
        "ServiceTaxAmount": 0,
        "Installments": 1,
        "Interest": "ByMerchant",
        "Capture": true,
        "Authenticate": false,
        "CreditCard": {
            "CardNumber": "455187******0183",
            "Holder": "Teste Holder",
            "ExpirationDate": "12/2030",
            "SaveCard": true,
            "CardToken": "d37bf475-307d-47be-b50a-8dcc38c5056c",
            "Brand": "Visa"
        },
        "ProofOfSale": "674532",
        "Tid": "0305020554239",
        "AuthorizationCode": "123456",
        "SoftDescriptor":"123456789ABCD",
        "PaymentId": "24bc8366-fc31-4d6c-8555-17049a836a07",
        "Type": "CreditCard",
        "Amount": 15700,
        "CapturedAmount": 15700,
        "Country": "BRA",
        "ExtraDataCollection": [],
        "Status": 2,
        "ReturnCode": "6",
        "ReturnMessage": "Operation Successful",
        "Links": [
            {
                "Method": "GET",
                "Rel": "self",
                "Href": "https://apiquerysandbox.cieloecommerce.cielo.com.br/1/sales/{PaymentId}"
            }
            {
                "Method": "PUT",
                "Rel": "void",
                "Href": "https://apisandbox.cieloecommerce.cielo.com.br/1/sales/{PaymentId}/void"
            }
        ]
    }
}

Response property

ParâmetroDescriçãoTipoTamanhoFormato
ProofOfSaleAuthorization number, identical to NSU.Text6Alphanumeric text
TidTransaction ID at the acquirer.Text20Alphanumeric text
AuthorizationCodeAuthorization code.Text6Alphanumeric text
SoftDescriptorText to be printed on the cardholder's bank statement - available only for VISA/MASTER - does not allow special charactersText13Alphanumeric text
PaymentIdPayment identification number, required for operations such as Query, Capture, and Cancellation.GUID36xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
ECIElectronic Commerce Indicator. Represents how secure a transaction is.Text2Example: 7
StatusTransaction Status.Byte***2
ReturnCodeAcquirer return code.Text32Alphanumeric text
ReturnMessageAcquirer return message.Text512Alphanumeric text
CardtokenCard identification token.GUID36xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx