NAV Navbar

Apresentação

Nós criamos nossa API seguindo a técnica REST. Dessa forma, nossas URLs são amigáveis e previsíveis.

Todas nossas APIs respondem em JSON.

Introdução

Você está acessando a documentação para integrar o seu e-commerce na plataforma da Stelo, uma empresa de meios de pagamentos online que pertence ao Banco do Brasil, Bradesco e Cielo.

A solução que você irá integrar com a Stelo será a Carteira Digital, que permite que o pagamento das compras realizadas em sua loja seja feito por meio de um cadastro que o comprador tem com a Stelo, no qual ele armazena os dados de pagamento, dados pessoais e endereço de entrega em uma única conta. Ao selecionar a opção Pagar com Stelo, no checkout de sua plataforma, o comprador realiza o login em sua Carteira Digital e compra com um clique, já que todos os dados deles já estão armazenados e selecionados na carteira digital Stelo dele. Caso o comprador não seja cadastrado na Stelo, poderá criar uma Carteira Digital no momento da finalização da compra. Este processo facilita a vida de quem compra, pois não é necessário informar os dados pessoais, do cartão e de endereço toda vez que for finalizar uma compra: basta pagar com a Carteira Digital Stelo.

Com a Carteira Digital Stelo também é possível oferecer aos compradores a compra sem realização de cadastro em sua loja, ou seja, o usuário faz o login em sua loja pulando essa etapa e compra com muito mais rapidez. A Stelo compartilha todos os dados para sua loja faça a entrega e o relacionamento com esse novo cliente. Para saber como funciona esta integração, acesse (Link Integração Login com Stelo).

Introdução 1 Introdução 2 Introdução 3

Domínios

Todas as requisições devem ser feitas para os seguintes domínios:

Ambiente URL
Sandbox https://apic1.hml.stelo.com.br
Produção https://api.stelo.com.br

Autenticação API

A Stelo utiliza o padrão “HTTP Basic Authentication” W3C.

Para sua autenticação no serviço de APIs Stelo, deve ser utilizado o clientId e clientSecret(Chaves) de sua conta Stelo. Para utilização da API de Produção(real) será necessário homologação prévia de sua aplicação em ambiente Sandbox com nossa equipe de integração.

Exemplo de Basic Authentication

Como Montar

Authorization: Basic BASE64(CLIENTID:CLIENTSECRET)

Resultado

Authorization: Basic TU9JUF9BUElfVE9LRU46TU9JUF9BUElfS0VZ==

Erros

A Stelo API utiliza os próprios Códigos de Status HTTP para indicar sucesso ou falha da chamada. Em geral os códigos iniciados com 2 indicam sucesso, os iniciados com 4 indicam erro (Ex: Falta de parâmetro obrigatório) e iniciados com 5 indicam erro interno nos servidores da Stelo.

Resposta de Erro

Ex de Erro de Autenticação (Status 400)

{
  "errorCode": 400,
  "errorMessage": "Bad Request",
  "detail": "Failed to authenticate. Check your credentials."
}

Ex de Erro de Parâmetro (Status 400)

{
  "errorCode": 400,
  "errorMessage": "Bad Request",
  "detail": {
    "message": [
      "orderData.orderId: required field is missing"
    ]
  }
}

Checkout Stelo (Carteira digital)

Este processo facilita a vida de quem compra, pois não é necessário informar os dados pessoais, do cartão e de endereço toda vez que for finalizar uma compra: basta pagar com a Carteira Digital Stelo.

Criando transação

Na criação da transação devem ser informados os dados básicos do pagamento, dados do pedido e os dados do comprador. O Valor é enviado neste momento entre servidores para garantir que não será adulterado posteriormente.

Requisição - OpenTransaction

{
    "orderData":{
        "orderId":"100000309",
        "plataformId":"1",
        "transactionType":"w",
        "shippingBehavior":"default",
        "country":"BR"
    },
    "paymentData":{
        "amount":139.99,
        "discountAmount":"",
        "freight":"5.0",
        "currency":"BRL",
        "maxInstallment":"3",
        "cartData":[
            {
                "productName":"Produto Teste",
                "productPrice":"134.9900",
                "productQuantity":1,
                "productSku":"asc"
            }
        ]
    },
    "customerData":{
        "customerIdentity":"39488996811",
        "customerName":"teste testador",
        "customerEmail":"teste@teste.com.br",
        "birthDate":"1991-01-14",
        "billingAddress":{
            "street":"endereco teste ",
            "number":"123",
            "complement":"ap12",
            "neighborhood":"centro",
            "zipCode":"07114000",
            "city":"Guarulhos",
            "state":"SP",
            "country":"BR"
        },
        "shippingAddress":{
            "street":"endereco teste ",
            "number":"123",
            "complement":"ap12",
            "neighborhood":"centro",
            "zipCode":"07114000",
            "city":"Guarulhos",
            "state":"SP",
            "country":"BR"
        },
        "phoneData":[
            {
                "type":"LANDLINE",
                "number":"1124242424"
            },
            {
                "type":"CELL",
                "number":"11978787878"
            }
        ]
    }
}

Após o cliente efetuar os passos de compra da loja, escolher o meio de pagamento Stelo e clicar em “Finalizar Compra”, a loja realizará a seguinte requisição (REST) pelo método POST enviando os dados abaixo:

Transaction

Parâmetro Descrição Tipo Obrigatório
OrderData Dados do Pedido OrderData Sim
PaymentData Dados de Pagamento PaymentData Sim
CustomerData Dados do Cliente CustomerData Sim

OrderData

Parâmetro Descrição Tipo Obrigatório
orderId Identificador do pedido na loja String Sim
platformId Identificador da plataforma String Não
transactionType Sempre passar o valor “W” String Sim
authorization* Token de acesso ao Login Stelo String Não
country Sigla de duas letras (ex: BR) String Sim

PaymentData

Parâmetro Descrição Tipo Obrigatório
amount Valor total da compra incluindo frete Double Sim
discountAmount Valor do desconto Double Não
freight Valor do frete Double Sim
currency Moeda (ex: “BRL” / “USD”) String Sim
maxInstallment Número máximo de parcelas String Sim
CartData Dados do carrinho CartDataCollection Sim

CartDataCollection

Parâmetro Descrição Tipo Obrigatório
productName Nome do produto String Sim
productPrice Valor do produto (Ex: 99.00) Double Sim
productQuantity Quantidade do produto String Sim
productSku Código do produto String Não

CustomerData

Parâmetro Descrição Tipo Obrigatório
customerIdentity CPF do cliente String Sim
customerName Nome do cliente String Sim
customerEmail E-mail do cliente String Sim
birthDate Data de nascimento Date Date Sim
gender Sexo (m ou f) String Não
BillingAddress Endereço de cobrança BillingAddress Sim
ShippingAddress Endereço de entrega ShippingAddress Sim
PhoneData* Dados de telefone/celular PhoneDataCollection Sim

BillingAddress

Parâmetro Descrição Tipo Obrigatório
street Rua String Sim
number Número String Sim
complement Complemento String Não
neighborhood Bairro String Sim
zipcode CEP String Sim
city Cidade String Sim

ShippingAddress

Parâmetro Descrição Tipo Obrigatório
street Rua String Sim
number Número String Sim
complement Complemento String Não
neighborhood Bairro String Sim
zipcode CEP String Sim
city Cidade String Sim

PhoneDataCollection

Parâmetro Descrição Tipo Obrigatório
phoneType Tipo (LANDLINE / CELL) String Sim
number Número de telefone com código de área String Sim

Resposta

{
    "link":[
        {
            "@title":"confirmar",
            "@rel":"confirm",
            "@href":"http://integracao.stelo.com.br/ec/V1/orders/transactions/648/confirm"
        },
        {
            "@title":"cancelar",
            "@rel":"cancel",
            "@href":"http://integracao.stelo.com.br/ec/V1/orders/transactions/648/cancel"
        },
        {
            "@title":"checkout wallet",
            "@rel":"urlWallet",
            "@href":"https://carteirac1.hml.stelo.com.br/comprador/checkout?orderId=uYN93csF7z8i1s2_tjlA7Q"
        }
    ],
    "orderData":{
        "orderId":648
    }
}

Ao receber os dados da transação a Stelo confirmará o recebimento das informações e informará a URL para qual a loja deverá redirecionar o cliente.

Códigos de retorno Descrição
202 Se a transação tiver sido criada com sucesso.
400 Se houver alguma falha na criação da transação (neste caso, um texto descritivo estará presente no corpo da requisição)
Parâmetro Descrição Tipo
steloId Identificador da ordem na Stelo
authenticationUrl URL para redirecionar o Cliente
confirmationUrl* URL para confirmação do Pedido
cancelUrl URL para cancelamento do Pedido

Response Stelo

Ao receber os dados da transação a Stelo confirmará o recebimento das informações e informará o id do pedido e url de checkout.

Parâmetro Descrição Tipo
orderId Identificador da ordem na Stelo
Checkout Wallet URL para redirecionar o Cliente
confirmationUrl* URL para confirmação do Pedido
cancelUrl URL para cancelamento do Pedido

Processo Cliente X Stelo por Checkout ligthbox

Utilizando o Lightbox

O Lightbox é um script que sobrepõe objetos HTML à página corrente, facilitando a exibição de imagens, vídeos, banners e formulários, possibilitando uma visualização ou destaque no objeto HTML. Existem diversas bibliotecas prontas que disponibilizam este recurso com facilidade. Exemplos:

Para a integração é necessário incluir um Frame no Lightbox, onde será aberta a página com o login Stelo para o envio das informações e exibição do Checkout Stelo.

Como funciona:

1º – A loja deverá disponibilizar o Lightbox na tela de checkout; 2º – Inserir um frame dentro do Lightbox, com a chamada para o formulário de integração com o checkout Stelo.

Lightbox 2

Acompanhamento de Transação

Após criar uma transação, você vai querer acompanhar o seu status: se foi aprovado ou cancelado.

Para isso, a Stelo disponibiliza 3 maneiras para que você acompanhe seus pagamentos. Com essas ferramentas você fica sabendo assim que uma transação muda de status, podendo tomar uma ação, seja postando o produto de uma transação autorizada ou entrando em contato com o comprador para reconquistar uma venda com pagamento cancelado. As ferramentas são:

Notificação Automática de Status

A notificação automática da Stelo por meio de um POST HTTP. Você é informado sobre qualquer alteração no status do pagamento no momento em que ela ocorre. Para usá-la, você deve ser integrado por JSON e cadastrar a URL de notificação.

{
    "steloId" : 100000000000000
}

Email

A Stelo envia automaticamente um email para o vendedor assim que o pagamento é autorizado, entra em análise, cancelado ou foi concluído.

API Consultar Transação

Após receber a Notificação de Status, o seu servidor faz um REQUEST e nós retornamos todos os dados do pagamento. Para consultar o Status de uma transação você deverá realizar uma requisição (utilizando método HTTP GET) informando o código do pedido Stelo.

Request

Response

{
  "amount": 134,
  "freight": 30,
  "steloId": 144856769181290,
  "steloStatus": {
    "statusCode": "C",
    "statusMessage": "Cancelado"
  }
}

Stelo StatusData

Ao receber consultar o status de uma transação a Stelo irá retornar os parâmetros statusCode e statusMessage pré-definidos detalhados na tabela StatusResponse.

Parâmetro Descrição Tipo
statusCode Código do Status do pedido String
statusMessage Mensagem do status String

Cancelar transação

Após criar uma transação e o comprador desistir da compra a Stelo permite que você faça o cancelamento do pedido. Para isso basta enviar um REQUEST (utilizando método HTTP DELETE) informando o (steloId).

Request

Response

{
  "steloId": 144856769181290,
  "amount": 0.0
}

Anexo

SteloResponse

Status Descrição
I Iniciada - Transação iniciada na base.
E Em análise - Transação iniciada mais não paga.
A Aprovada - Transação paga.
N Negada- Transação Negada
NE Negada emissor - Negada pela financeira.
S Estornado - Transação estornada.
SP Estorno parcial - Transação estornada.

Homologação

Para que você possa usar as APIs da Stelo Pagamentos em ambiente real é necessário submeter-se ao processo de homologação Stelo.

Este processo tem como principal objetivo garantir que a sua integração com a Stelo ocorrendo da melhor forma possível, evitando assim transtornos no processo de pagamento, alem de auxiliar nas oportunidades de melhora na experiência de uso de seu checkout, aumentando consideravelmente a conversão de sua loja.

Ambiente de teste (Sandbox)

Requisito Adequação
Já tenho uma conta sandbox com a ferramenta API habilitada.Saiba mais sobre o sandbox aqui.
A integração foi realizada em ambiente de teste (sandbox) contemplando todos os cenários que serão usados em produção.

Checkout

Requisito Adequação
O pagador é informado com clareza sobre o valor total a ser pago, incluindo descontos e acréscimos.
Os Scripts de segurança estão enviando as informações como detalhado na documentação. Saiba mais sobre os Scripts de segurança.
O cliente é comunicado na interface, de forma discreta, que o pagamento será processado pela Stelo. Para mais informações consulte nosso Guideline da marca aqui