Facilitadores de Pagamento

Todos os clientes de e-commerce que são Facilitadores de Pagamento, por obrigatoriedade das bandeiras e do Banco Central devem enviar campos específicos na mensageria transacional. A Cielo transmitirá as informações para as bandeiras por meio da mensageria transacional no momento da autorização.

Os campos específicos estão contidos dentro do nó PaymentFacilitator. Além dos campos deste nó, os facilitadores também precisam enviar obrigatoriamente o campo SoftDescriptor do nó Payment. Veja a seguir o exemplo do envio e da resposta.


⚠️

Atenção

  • As bandeiras, ao identificarem inconformidade devido ao não envio dos dados obrigatórios na mensageria transacional, aplicarão multas à Cielo as quais serão repassadas ao Facilitador responsável pelo envio dos dados transacionais.
  • A bandeira Visa, desde 15 de abril de 2023, atualizou as regras para marketplace e todos os merchants que atuam como Facilitadores de Pagamentos e que tenham clientes que operam como Marketplace Estrangeiro precisam, obrigatoriamente, enviar o indicador de varejo estrangeiro para evitar multa pela bandeira. O parâmetro específico é o Payment.PaymentFacilitator.SubEstablishment.CountryCode, que indica o código do país.

Requisição

AmbienteMétodoEndpoint
Sandboxhttps://apisandbox.cieloecommerce.cielo.com.br/1/sales
Produçãohttps://api.cieloecommerce.cielo.com.br/1/sales

{
  "MerchantOrderId": "2222222222",
  "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": {
    "Type": "CreditCard",
    "Amount": 157000,
    "Currency": "BRL",
    "Country": "BRA",
    "Provider": "Cielo",
    "ServiceTaxAmount": 0,
    "Installments": 1,
    "Interest": "ByMerchant",
    "Capture": false,
    "Authenticate": false,
    "Recurrent": false,
    "SoftDescriptor": "123456789ABCD",
    "CreditCard": {
      "CardNumber": "4024007197692931",
      "Holder": "Teste Holder",
      "ExpirationDate": "12/2021",
      "SecurityCode": "123",
      "SaveCard": "false",
      "Brand": "Visa"
    },
    "PaymentFacilitator": {
      "EstablishmentCode": "1234",
      "SubEstablishment": {
        "EstablishmentCode": "1234",
        "Identity": "11111111000100",
        "Mcc": "1234",
        "Address": "Alameda Grajau, 512",
        "City": "Barueri",
        "State": "SP",
        "CountryCode": "076",
        "PostalCode": "06455914",
        "PhoneNumber": "1155855585"
      }
    }
  }
}
PropriedadeTipoTamanhoObrigatórioDescrição
Payment.PaymentFacilitator.EstablishmentCodetexto11Obrigatório para facilitadoresCódigo do estabelecimento do Facilitador. "Facilitator ID” (Cadastro do facilitador com as bandeiras)
O código é diferente por bandeira, podendo variar inclusive o tamanho do campo:
Bandeira Mastercard –06 dígitos
Bandeira Visa –08 dígitos
Bandeira ELO –de 04 à 05 dígitos
Bandeira Hipercard –06 dígitos
Para demais bandeiras, como Amex e JCB, o campo pode ser preenchido com “0” zeros.
Payment.PaymentFacilitator.SubEstablishment.EstablishmentCodetexto15Obrigatório para facilitadoresCódigo do estabelecimento do sub Merchant. “Sub-Merchant ID” (Cadastro do subcredenciado com o facilitador)
Payment.PaymentFacilitator.SubEstablishment.Identitytexto14Obrigatório para facilitadoresCNPJ ou CPF do sub-merchant.
Payment.PaymentFacilitator.SubEstablishment.Mcctexto4Obrigatório para facilitadoresMCC do sub Merchant.
Payment.PaymentFacilitator.SubEstablishment.Addresstexto22Obrigatório para facilitadoresEndereço do sub Merchant.
Payment.PaymentFacilitator.SubEstablishment.Citytexto13Obrigatório para facilitadoresCidade do sub Merchant.
Payment.PaymentFacilitator.SubEstablishment.Statetexto2Obrigatório para facilitadoresEstado do sub Merchant.
Payment.PaymentFacilitator.SubEstablishment.PostalCodetexto9Obrigatório para facilitadoresCódigo postal do sub Merchant.
Payment.PaymentFacilitator.SubEstablishment.CountryCodetexto3Obrigatório para facilitadoresCódigo país do sub-merchant com base no ISO 3166
Ex: código ISO 3166 do Brasil é o 076. Lista completa online.
Payment.PaymentFacilitator.SubEstablishment.PhoneNumbertexto13Obrigatório para facilitadoresNúmero de telefone do sub Merchant.
Payment.Softdescriptortexto13Obrigatório para facilitadoresTexto impresso na fatura bancaria comprador. Deve ser preenchido de acordo com os dados do sub Merchant.

❗️

Não use acentos pois eles são considerados como dois caracteres


⚠️

Atenção

Os campos não devem ser enviados com espaçamento a esquerda. Sujeito a rejeição na liquidação das transações.

Resposta

{
  "MerchantOrderId": "2014111701",
  "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": 0,
    "Capture": false,
    "Authenticate": false,
    "Recurrent": false,
    "CreditCard": {
      "CardNumber": "402400******2931",
      "Holder": "Teste Holder",
      "ExpirationDate": "12/2021",
      "SaveCard": false,
      "Brand": "Visa"
    },
    "Tid": "1223092935684",
    "ProofOfSale": "2935684",
    "AuthorizationCode": "065158",
    "SoftDescriptor": "123456789ABCD",
    "Provider": "Simulado",
    "IsQrCode": false,
    "PaymentFacilitator": {
      "EstablishmentCode": "1234",
      "SubEstablishment": {
        "EstablishmentCode": "1234",
        "Identity": "11111111000100",
        "Mcc": "1234",
        "Address": "Alameda Grajau, 512",
        "City": "Barueri",
        "State": "SP",
        "CountryCode": "076",
        "PostalCode": "06455914",
        "PhoneNumber": "1155855585"
      }
    },
    "Amount": 157000,
    "ReceivedDate": "2019-12-23 09:29:34",
    "Status": 1,
    "IsSplitted": false,
    "ReturnMessage": "Operation Successful",
    "ReturnCode": "4",
    "PaymentId": "365c3a0d-fd86-480b-9279-4ba3da21333c",
    "Type": "CreditCard",
    "Currency": "BRL",
    "Country": "BRA",
    "Links": [
      {
        "Method": "GET",
        "Rel": "self",
        "Href": "https://apiquerysandbox.cieloecommerce.cielo.com.br/1/sales/365c3a0d-fd86-480b-9279-4ba3da21333c"
      },
      {
        "Method": "PUT",
        "Rel": "capture",
        "Href": "https://apisandbox.cieloecommerce.cielo.com.br/1/sales/365c3a0d-fd86-480b-9279-4ba3da21333c/capture"
      },
      {
        "Method": "PUT",
        "Rel": "void",
        "Href": "https://apisandbox.cieloecommerce.cielo.com.br/1/sales/365c3a0d-fd86-480b-9279-4ba3da21333c/void"
      }
    ]
  }
}
PropriedadeTipoTamanhoObrigatórioDescrição
Payment.PaymentFacilitator.EstablishmentCodetexto11Obrigatório para facilitadoresCódigo do estabelecimento do Facilitador. "Facilitator ID” (Cadastro do facilitador com as bandeiras)
O código é diferente por bandeira, podendo variar inclusive o tamanho do campo:
Bandeira Mastercard –06 dígitos
Bandeira Visa –08 dígitos
Bandeira ELO –de 04 à 05 dígitos
Bandeira Hipercard –06 dígitos
Para demais bandeiras, como Amex e JCB, o campo pode ser preenchido com “0” zeros.
Payment.PaymentFacilitator.SubEstablishment.EstablishmentCodetexto15Obrigatório para facilitadoresCódigo do estabelecimento do sub Merchant. “Sub-Merchant ID” (Cadastro do subcredenciado com o facilitador)
Payment.PaymentFacilitator.SubEstablishment.Identitytexto14Obrigatório para facilitadoresCNPJ ou CPF do sub-merchant.
Payment.PaymentFacilitator.SubEstablishment.Mcctexto4Obrigatório para facilitadoresMCC do sub Merchant.
Payment.PaymentFacilitator.SubEstablishment.Addresstexto22Obrigatório para facilitadoresEndereço do sub Merchant.
Payment.PaymentFacilitator.SubEstablishment.Citytexto13Obrigatório para facilitadoresCidade do sub Merchant.
Payment.PaymentFacilitator.SubEstablishment.Statetexto2Obrigatório para facilitadoresEstado do sub Merchant.
Payment.PaymentFacilitator.SubEstablishment.PostalCodetexto9Obrigatório para facilitadoresCódigo postal do sub Merchant.
Payment.PaymentFacilitator.SubEstablishment.CountryCodetexto3Obrigatório para facilitadoresCódigo país do sub-merchant com base no ISO 3166.
Ex: código ISO 3166 do Brasil é o 076. Lista completa online
Payment.PaymentFacilitator.SubEstablishment.PhoneNumbertexto13Obrigatório para facilitadoresNúmero de telefone do sub Merchant.
Payment.Softdescriptortexto13Obrigatório para facilitadoresTexto impresso na fatura bancaria comprador. Deve ser preenchido de acordo com os dados do sub Merchant.

*Evite utilizar acentos pois eles são considerados como dois caracteres.

Novos campos obrigatórios para facilitadores

A partir de 11 de abril de 2025, todas as transações de facilitadores de pagamentos deverão informar os seguintes dados:

Razão social do sub-comerciante, no parâmetro Payment.PaymentFacilitator.SubEstablishment.CompanyName (máximo de 40 caracteres, não é permitido enviar caractere especial)
CNPJ/CPF do sub-comerciante, no parâmetro Payment.PaymentFacilitator.SubEstablishment.Identity (campo já existente).

O Banco Central do Brasil (BCB) definiu uma regra obrigatória para os arranjos de meios de pagamentos, visando reforçar medidas preventivas à lavagem de dinheiro no Brasil, conforme disposto na Circular BCB nº 3.978/2020. Com essa nova regra, a Cielo passará a compartilhar os dados de razão social e CNPJ/CPF do sub-comerciante com as áreas de PLD das instituições envolvidas no processo transacional de compra (bancos emissores, bandeiras, credenciadores e BCB). Esses dados serão compartilhados única e exclusivamente com a finalidade de prevenção à lavagem de dinheiro.

Veja a seguir como um exemplo do nó PaymentFacilitator com todos os campos que devem ser enviados a partir de 11 de abril de 2025:

{
    "PaymentFacilitator": {
        "EstablishmentCode": "1234",
        "SubEstablishment": {
            "EstablishmentCode": "1234",
            "Identity": "11111111000100",
            "Mcc": "1234",
            "Address": "Alameda Xingu, 512",
            "City": "Barueri",
            "State": "SP",
            "CountryCode": "076",
            "PostalCode": "06455914",
            "PhoneNumber": "11987654321",
            "CompanyName": "Subseller"
        }
    }
}