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:
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) |
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.