Manual Carteira Digital
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.
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).
Todas as requisições devem ser feitas para os seguintes domínios:
Sandbox https://apic1.hml.stelo.com.br
Produção https://api.stelo.com.br
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
Exemplo: Basic Authentication
Aplicação: HTTP Header
Authorization: Basic TU9JUF9BUElfVE9LRU46TU9JUF9BUElfS0VZ==
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.
errors - Pode conter tanto uma string de erro como um hash contendo o atributo e seus erros.
Ex de Erro de Autenticação (Status 400)
"detail": "Failed to authenticate. Check your credentials."
Ex de Erro de Parâmetro (Status 400)
"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
"orderId":"100000309",
"plataformId":"1",
"transactionType":"w",
"shippingBehavior":"default",
"amount":139.99,
"discountAmount":"",
"freight":"5.0",
"maxInstallment":"3",
"cartData":[
"productName":"Produto Teste",
"productPrice":"134.9900",
"productQuantity":1,
"productSku":"asc"
"customerIdentity":"39488996811",
"customerName":"teste testador",
"customerEmail":"teste@teste.com.br",
"birthDate":"1991-01-14",
"street":"endereco teste ",
"complement":"ap12",
"zipCode":"07114000",
"phoneData":[
"type":"LANDLINE",
"number":"1124242424"
"number":"11978787878"
POST /ec/V1/wallet/transactions
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:
OrderData Dados do Pedido OrderData Sim
PaymentData Dados de Pagamento PaymentData Sim
CustomerData Dados do Cliente CustomerData Sim
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
O parâmetro authorization é obrigatório caso utilize o Login Stelo
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
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
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
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
phoneType Tipo (LANDLINE / CELL) String Sim
number Número de telefone com código de área String Sim
"@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"
"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.
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)
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.
orderId Identificador da ordem na Stelo
Checkout Wallet URL para redirecionar o Cliente
Processo Cliente X Stelo por Checkout ligthbox
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:
Fancybox (jQuery): http://fancyapps.com/fancybox
Lytebox: http://lytebox.com
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.
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.
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:
API Consultar Transação
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
A Stelo envia automaticamente um email para o vendedor assim que o pagamento é autorizado, entra em análise, cancelado ou foi concluído.
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.
GET /ec/V1/subacquirer/transactions/{steloID}
"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.
statusCode Código do Status do pedido String
statusMessage Mensagem do status String
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).
DELETE /ec/V1/orders/transactions/{steloID}
SteloResponse
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.
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.
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. ✔
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