Logo
PORTUGUÊS EUA
Exemplo

Visão geral

O objetivo desta documentação é orientar o desenvolvedor sobre como integrar com a API Gateway ,descrevendo as funcionalidades, os métodos a serem utilizados, listando informações a serem enviadas e recebidas, e provendo exemplos.

Nesse manual você encontrará a referência sobre todas as operações disponíveis na API REST da API Gateway.

Credenciais do estabelecimento

Para qualquer chamada feita em nossa base é preciso que o Estabelecimento se identifique com as suas credenciais.. O ID de Loja (MID) e a sua Chave (MKEY) são informados pela nossa equipe quando seu cadastro é criado.

Para fazer o cadastro basta acessar https://cadastro.bit.one

Independentemente da requisição que estiver chamando você deverá informar suas credenciais dentro do objeto JSON, da seguinte forma:



{
    "merchantId": "MID",
    "merchantKey": "MKEY",
    	.
	.
	.

}

Integração via API

A principal característica da integração via API é que os dados são digitados no site do estabelecimento e então enviados para a Bit.One. Nesse processo não há existência de pop-up ou redirecionamentos. A responsabilidade de coletar os dados do comprador é do estabelecimento, logo, deve existir uma preocupação com a segurança dos dados. É necessária a compra de um

Para utilizar a API da Bit.One, basta efetuar um POST com um objeto JSON de acordo com o tipo de transação desejada.

Tipos de requisição

A troca de informações com a Bit.One é feita através de JSON enviado diretamente no corpo do Post - ele não deve estar dentro de nenhum parâmetro e nem ser enviado em um formulário.

O content type deve ser text/xml e o charset deve ser UTF-8

TIPO DESCRIÇÃO
BITCOIN Cria um endereço único de depósito para transação.
BLOCKCHAIN Solicita a verificação do status da transação.
MERCHANT Solicita o cadastro ou atualização dos dados de uma loja.
BALANCE Solicita o saldo disponível para saque.
WITHDRAWAL Solicita a retirada/saque de valores.

Cada tipo de requisição de transação deverá ser utilizada uma URL específica:

AMBIENTE DE TESTES
API https://testapi.bit.one/bitOneApi/gw/req
PORTAL https://testportal.bit.one

AMBIENTE DE PRODUÇÃO
API https://api.bit.one/bitOneApi/gw/req
PORTAL https://portal.bit.one

BITCOIN

Estas requisições são responsáveis por processar pedidos de depósito de Bitcoins. Nossa API recebe os dados, e solicita a geração de um endereço para depósito da nova transação, assim, para cada transação teremos um endereço único. Após a criação do endereço, é retornado o status da transação bem como a url para visualização do novo endereço criado.

Os parâmetros recebidos são:

NOME DESCRIÇÃO
merchantId ID da loja que identifica o estabelecimento.
merchantKey Solicita a verificação do status da transação.
Currency Moeda ( BRL/USD)
amount Valor da transação a ser depositado. Os decimais devem ser separados por ponto(".") Exemplo: 12.00 ou 1234.99
referenceTag Observação/Descrição da transação. Identificador único do pedido(pode ser um ID da transação na base do cliente)..

As seguintes informações são retornadas no objeto JSON:

NOME DESCRIÇÃO
success Indica se o endereço foi criado corretamente.
true - sucesso
false - erro na geração do endereço. Tente novamente.
transactionState Indicador do status da transação. 6 - pendente de depósito 10 - capturada / depósito efetuado.
referenceTag Observação/Descrição informada pelo cliente na requisição.
transactionTimestamp Data/hora da transação em formato epoch.
responseCode Indicador do status da transação na Bit.One. 0 - aprovada 1 - negada - verificar errorMessage
qrcodeUrl URL para geração do QR code. Recomenda-se salvar esta URL para uso futuro.
btcTransactionId ID único para transações com Bitcoin.
errorMessage
btcAmount Valor do depósito em Bitcoin.
address Preço do Bitcoin no momento da solicitação.
btcPrice Mensagem de erro.
qrcodeImage URL para a imagem do QR code.
returnFeeBtc Valor da taxa adicional para a loja em Bitcoin.

ACESSANDO A URL DE RETORNO

Caso o site retorne ao cliente a URL (qrcodeUrl), será exibido o seguinte conteúdo no navegador:

qrcode

Caso o cliente efetue o pagamento, o sistema identificará o depósito na carteira, atualizará o status da transação na página e após 5 segundos redirecionará o cliente para o sistema da loja. Para isso deverá ser criada uma url de retorno para receber o status da transação.

Serão enviados os seguintes parâmetros:

NOME DESCRIÇÂO
btcTransactionId ID único para transações com Bitcoin.
transactionState Indicador do status da transação.
6 - pendente de depósito
10 - capturada / depósito efetuado
30 - pagamento menor do que o estipulado
amountRemaining Valor a ser depositado para concluir a transação.

Ex1:
http://sualoja.com.br/pagamento/atualizacaoPagamento.php?btcTransactionId=123&transactionState=10
Ex2:
http://sualoja.com.br/pagamento/atualizacaoPagamento.php?btcTransactionId=123&transactionState=30&amountRemaining=0.78 

A estrutura do objeto JSON deverá ficar da seguinte forma:

{
  "merchantId": "MID",
  "merchantKey": "MKEY",   
  "order":{
     "bitcoin":{
	  "currency":"BRL",
	  "amount":"1.00",
	 "referenceTag": "1234"
	}
    }
}
	
	
Retorno da Transação

{
   "success": true,
   "transactionState": "6",
   "referenceTag": "1234",
   "transactionTimestamp": "1471630349139",
   "responseCode": "0",
   "qrcodeUrl": "https://payment.bit.one/bitcoin?h=b3B0aW9uPXFyY29kZSZ0aWQ9MjQ=",
   "btcTransactionId": "24",
   "btcAmount": "0.00053579",
   "btcPrice": “13671.38",
   "address": “16ra8bW9gZaWToC7yAEwvB2LuUfd9NhqVs”,
   "qrcodeImage": "https://payment.bit.one/bitcoin?h=b3B0aW9uPWltYWdlJmFkZHJlc3M9Mzg3V2lUY1g5UEdRaFp0TTdyMVVUbWU1azY2N3lWYTI2ZSZhbW91bnQ9MC4wMDAwNzMxNA==",
   "returnFeeBtc": "0.00000000"
}

BLOCKCHAIN

Estas requisições são responsáveis por processar pedidos de verificação de depósitos de Bitcoins. Ela verifica na rede Blockchain se algum valor foi depositado na carteira de Bitcoin gerada e atualiza o status da transação.

Os Parâmetros recebidos são:

NOME DESCRIÇÃO
merchantId ID de loja que identifica o estabelecimento.
merchantKey Chave associada ao ID de loja.
Id da loja da afiliada Id da loja da afiliada
btcTransactionId ID da transação criada no comando "bitcoin".

As seguintes informações são retornadas no objeto JSON:

NOME DESCRIÇÃO
success Indica se o endereço foi criado corretamente.
False - Erro na geração do endereço. Tente novamente.
False - Erro na geração do endereço. Tente novamente.
transactionState Indicador do status da transação.
6 - pendente de depósito
10 - capturada / depósito efetuado
30 - Pagamento inferior ao determinado
referenceTag Observação/Descrição informada pelo cliente na requisição.
transactionTimestamp Data/hora da transação em formato epoch.
responseCode Indicador do status da transação na Bit.One. 0 - aprovada 1 - negada - verificar errorMessage
approvedAmount Valor recebido (BRL/USD). Este valor deverá ser usado como referência para liberação de créditos.
qrcodeUr URL para geração do QR code.
errorMessage Mensagem de erro.
btcAmount Valor do depósito em Bitcoin.
btcAmountReceived Valor em Bitcoin recebido na carteira.
amountRemaining Valor a ser depositado no caso de pagamento inferior. Utilizar este valor para criar uma transação complementar caso necessário. Utilizar este valor para criar uma transação complementar caso necessário.
btcAmountRemaining Valor não depositado em Bitcoin.
btcPrice Preço do Bitcoin no momento do depósito.
address Endereço da carteira para depósito.
returnFeeBtc Valor da taxa adicional para a loja em Bitcoin. 
 A estrutura do objeto JSON deverá ficar da seguinte forma:

{
"merchantId": "MID",
"merchantKey": "MKEY",   
 "order":{
    "blockchain":{
      "btcTransactionId": 
      "84"
    }
  }
}



Retorno da Transação:
{
  "success": true,
  "transactionState": "30",
  "referenceTag": "3333",
  "transactionTimestamp": "1475082432975",
  "responseCode": "0",
  "approvedAmount": "0.00",
  "qrcodeUrl": "https://payment.bit.one/bitcoin?h=b3B0aW9uPXFyY29kZSZ0aWQ9ODQ=",
  "btcTransactionId": "84",
  "btcAmount": "0.00051721",
  "btcAmountReceived": "0.00032495",
  "amountRemaining": "0.37",
  "btcAmountRemaining": "0.00051721",
  "btcPrice": “1933.44",
  "address": “12yeaBKeRrA9LcambtiNrsASeANuGhhVNR”,    
  "returnFeeBtc": "0.0000"
  }

MERCHANT

Este tipo de requisição é responsável por cadastrar uma nova loja associada à uma loja já existente. Geralmente utilizada por redes de lojas e/ou revendas. Ela verifica os dados da loja "mãe" e replica suas configurações para a loja "filha".

NOME DESCRIÇÃO
merchantId ID de loja que identifica o estabelecimento.
merchantKey Chave associada ao ID de loja.
name Nome fantasia.
dba Razão Social
Email E-mail
Address Endereço
Complement complemento
Neighborhood Bairro
City Cidade
State Estado
Zip CEP
TaxId CNPJ da loja
UserFirstName Nome do usuário
UserLastName Sobrenome do usuário
UserEmail E-mail do usuário para acesso no portal
UserPhone Telefone do usuário
UserLanguage Idioma do usuário
US - Inglês
BR - Português Brasil
WalletBTC Carteira/Endereço de Bitcoin da loja.

As seguintes informações são retornadas no objeto JSON:

NOME DESCRIÇÃO
Success Indica se o endereço foi criado corretamente.
true - sucesso.
false - erro na geração do endereço. Tente novamente..
orderID ID criado para transação.
transactionTimestamp Data/hora da transação em formato epoch.
merchantId ID do estabelecimento..
merchantKey Chave para acesso da API.
message Mensagem informativa.
errorMessage Mensagem de erro. 

A estrutura do objeto JSON deverá ficar da seguinte forma:
	    
{
"merchantId": "MID",
"merchantKey": "MKEY",   
"order": {
  "merchant":{
    "name": "Merchant Name"
    "dba": "Merchant DBA"
    "email":"email"
    "address":"address"
    "complement":"complement"
    "neighborhood":"neighborhood"
    "city": "city"
    "state": "state"
    "zip": "00000000"
    "taxId": "Merchant TaxId"
    "userFirstName":"User First Name"
    "userLastName":"User Last Name"
    "userEmail":"user@email.com"
    "userPhone":"+00 000 00 0000 000000"
    "userLanguage":"US"
    "walletBTC":"wallet"
   }
 }
}


Retorno da Transação:
{
  "success": true,    
  "message": "Merchant created/updated",
  "orderID": "88ac107a-1767-4bc1-9dfe-46cba4aad66a",
  "transactionTimestamp": "1475082432975",    
  "merchantId": "1234",
  "merchantKey": "dkjnfuiyr2knfwehiuhewkmnfwb"
}

OBSERVAÇÃO

É possível atualizar os dados de uma loja filha. Basta passar na requisição o merchantId da loja que deverá ter os seus dados atualizados.


A estrutura do objeto JSON deverá ficar da seguinte forma:
{
"merchantId": "MID",
"merchantKey": "MKEY",   
"order": {
  "merchant":{
    "merchantId": "Merchant Id"
    "name": "Merchant Name"
    "dba": "Merchant DBA"
    "email":"email"
    "address":"address"
    "complement":"complement"
    "neighborhood":"neighborhood"
    "city": "city"
    "state": "state"
    "zip": "00000000"
    "taxId": "Merchant TaxId"
    "userFirstName":"User First Name"
    "userLastName":"User Last Name"
    "userEmail":"user@email.com"
    "userPhone":"+00 000 00 0000 000000"
    "userLanguage":"US"
    "walletBTC":"wallet"
   }
 }
}
Retorno da Transação:	{
  "success": true,    
  "message": "Merchant created/updated",
  "orderID": "88ac107a-1767-4bc1-9dfe-46cba4aad66a",
  "transactionTimestamp": "1475082432975",    
  "merchantId": "1234",
  "merchantKey": "dkjnfuiyr2knfwehiuhewkmnfwb"
}

BALANCE

Estas requisições são responsáveis por processar pedidos de verificação de saldo disponível para saque. Ela verifica o valor disponível para saque em determinada moeda.

Os parâmetros recebidos são:

Nome Descrição
merchantId ID de loja que identifica o estabelecimento.
merchantKey Chave associada ao ID de loja.
currency USD - Dólar Americano
BRL - Real
BTC - Bitcoin

As seguintes informações são retornadas no objeto JSON:

Nome Descrição
sucess Indica se o endereço foi criado corretamente.
true - sucesso
false - erro na geração do endereço. Tente novamente.
orderID orderID ID criado para transação.
transactionTimestamp Data/hora da transação em formato epoch.
currency. Moeda.
amount Valor disponível para saque.
Mensagem Mensagem informativa.
errorMessage Mensagem de erro. 
A estrutura do objeto JSON deverá ficar da seguinte forma:

{
"merchantId": "MID",
"merchantKey": "MKEY",  
"order":{
    "balance":{
     "currency": 
     "BTC"
     }
  }
}
	
				
Retorno da Transação:
{
  "success": true,    
  "message": "Merchant created/updated",
  "orderID": "cc07c15f-baab-4b3a-91ff-6501d835dfc3",
  "transactionTimestamp": "1502908379086",    
  "currency": "BTC",
  "amount": "0.0593"
}

WITHDRAWAL

Estas requisições são responsáveis por processar pedidos de solicitação de saque. Ela verifica se o saldo solicitado está disponível e em caso positivo, adiciona o pedido de saque.

Os parâmetros recebidos são:

NOME DESCRIÇÃO
merchantId ID de loja que identifica o estabelecimento.
merchantKey Chave associada ao ID de loja.
currency Moeda
amount Valor

Também é possível consultar o status de uma solicitação de saque gerada anteriormente, basta utilizar o ID gerado.

Os parâmetros recebidos são:

NOME DESCRIÇÃO
merchantId ID de loja que identifica o estabelecimento.
merchantKey Chave associada ao ID de loja.
withdrawalId ID da transação de saque a ser consultada.

Os parâmetros recebidos são:

NOME DESCRIÇÃO
sucess Indica se o endereço foi criado corretamente.
true- sucesso
false - erro na geração do endereço. Tente novamente.
transactionstate Indicador do status da transação.
6 - pendente
3 - aprovada / inserida na fila para processamento
10 - saque processado
12 - cancelada
13 - falha/erro no processo de transferência de fundos.
orderID ID criado para transação.
transactionTimestamp Data/hora da transação em formato epoch.
currency Moeda
USD - Dólar Americano
BRL - Real
BTC - Bitcoin
amount Valor da retirada.
withdrawalId ID gerado para esta transação.
message Mensagem informativa.
errorMessage Mensagem de erro. 
A estrutura do objeto JSON deverá ficar da seguinte forma:
{
"merchantId": "MID",
"merchantKey": "MKEY",   
"order":{
   "withdrawal":{
       "currency": 
       "BTC"
       "amount": "0.0593"
     }
  }
}
	
				

A estrutura do objeto JSON deverá ficar da seguinte forma (apenas consulta):
{
 "merchantId": "MID",
 "merchantKey": "MKEY",   
 "order": {
     "withdrawal": {
     "withdrawalId": "123"                     
      }
  }
}
	
				
Retorno da Transação:
{
    "success": true,    
    "message": "Withdrawal request/status",
    "transactionState": "6",
    "orderID": "cc07c15f-baab-4b3a-91ff-6501d835dfc3",
    "transactionTimestamp": "1502908379086",    
    "currency": "BTC",
    "amount": "0.0593",
    "withdrawalId": "123"
}

Status da transação

Verifique aqui os possíveis status para transações:


TRANSACTIONSTATE DESCRIÇÃO
3 Aprovada com sucesso
6 Pendente
9 Transação não autorizada.
10 Transação capturada
Boleto Pago Bitcoin Depositado
Saque concluído
12 Transação cancelada
13 Falha
15 Timeout na Adquirente
17 Sistema fora do ar
27 Quando a transação de débito é finalizada com sucesso,mas precisa ser confirmada pelo cliente.
28 Boleto Criado.
29 Boleto Visualizado
30 Boleto Pago/Bitcoin Depositado (valor menor do estipulado)
31 Boleto Pago/Bitcoin Depositado (valor acima do estipulado)

Informações gerais

A marca Bit.One. e todo o conteúdo deste manual é propriedade da Tranfero Pagamento S.A., inscrita no CNPJ sob nº 11.480.809/0001-84, estabelecida na Rua Barão do Flamengo, nº 22 - sala

O uso deste material ou cópia sem a devida autorização prévia da empresa infringe a Lei de Propriedade Intelectual e assim estará o responsável pelo uso, sujeito à todas as medidas legais cabíveis.

Glossário

Estabelecimento / Merchant Dados do lojista cadastrado na plataforma Bit.One / Usuário do gateway.

Sandbox = Ambiente de testes da plataforma.

MID / Merchant ID = ID do lojista na Bit.One.

MKEY / Merchant Key = Chave do lojista para utilização da API.

Blockchain =Rede ou estrutura onde se encontram todos os registros das transações bitcoin realizadas.

Bitcoin/BTC = É uma criptomoeda e sistema de pagamento online baseado em protocolo de código aberto que é independente de qualquer autoridade central.

Exemplo