Logo
PORTUGUÊS EUA
Example

Overview

The purpose of this documentation is to guide the developer on how to Integrate with the API Gateway ,describing the Features, the methods to be used, listing information To be sent and received, and providing examples.

In this manual you will find the reference on all the operations available in the Gateway API REST API. API Gateway.

Merchant Credentials

All requests that go through our database require identification via credentials.. O A Merchant ID (MID) and yours Merchant Key (MKEY) are generated and sent by our team as soon as a Customer wants to use our platform.

To register, just access. https://cadastro.bit.one

As shown in this example, the JSON object needs to have valid Credentials in order to perform requests to our platform:



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

}

API Integration

The main characteristic of the API Integration is that all data will be typed inside the Merchan´s environment and then relayed to Bit.One. In this process there is no existence of popup or redirects. The responsibility of collecting the data of the buyer is of the establishment, therefore, there must be a concern with data security. It is necessary to purchase a

To use Bit.One API, the Merchant will issue POST with a JSON object compatible with the desired type of transaction. This will be further explained in this manual.

Types of Request

The exchange of information with Bit.One is done through JSON sent directly in the body of the Post - it should not be within any parameters nor be sent in a form.

O content type must be text/xml and the charset should be UTF-8

TYPE DESCRIPTION
BITCOIN Creates a unique deposit address for a Bitcoin transaction.
BLOCKCHAIN Requests and verifiy each transaction status on Bitcoin Network.
MERCHANT Request the registration or update of the data of a store.
BALANCE Request the balance available for withdrawal.
WITHDRAWAL Request the withdrawal / withdrawal of securities.

Each type of transaction request should be used a specific URL:

TEST ENVIRONMENT
API https://testapi.bit.one/bitOneApi/gw/req
PORTAL https://testportal.bit.one

PRODUCTION ENVIRONMENT
API https://api.bit.one/bitOneApi/gw/req
PORTAL https://portal.bit.one

BITCOIN

These requests are responsible for processing Bitcoin deposits. Our API will receive the data and generate a new Bitcoin address for each transaction. Each deposit will have a unique address for it. When the address is generated, it returns the transaction status as well as the URL for visualizing it.

The received parameters are:

NAME DESCRIPTION
merchantId Store ID that identifies the property.
merchantKey Requests verification of transaction status.
Currency Currency( BRL/USD)
amount Value of the transaction to be deposited. Decimals must be separated by periods (".") Example: 12.00 ou 1234.99
referenceTag Note / Description of the transaction. Unique identifier of the order (can be a transaction ID in the customer base)..

The following information is returned in the JSON object:

NAME DESCRIPTION
success Indicates whether the address was created correctly.
true - sucess
false - address generation error. Try again.
transactionState Transaction Status Indicator. 6 - deposit pending 10 - captured / deposit made.
referenceTag Observation / Description informed by the client in the request.
transactionTimestamp Transaction date / hour in epoch format.
responseCode Transaction status indicator on Bit.One. 0 - approved 1 - denied - check errorMessage
qrcodeUrl URL for generating QR code. It is recommended that you save this URL for future use.
btcTransactionId Unique ID for transactions with Bitcoin.
errorMessage
btcAmount Value of the deposit in Bitcoin.
address Bitcoin price at the time of request.
btcPrice Error Message.
qrcodeImage URL for the QR code image.
returnFeeBtc Additional fee for the shop in Bitcoin.

ACCESSING THE RETURN URL

If the site returns the URL (qrcodeUrl) to the client, the following content appears in the browser:

qrcode

If the customer makes the payment, the system will identify the deposit in the wallet, update the status of the transaction on the page and after 5 seconds will redirect the customer to the store system. For this, a return url must be created to receive the status of the transaction.

The following parameters will be sent:

NAME DESCRIPITION
btcTransactionId Unique ID for transactions with Bitcoin.
transactionState Transaction Status Indicator.
6 - deposit pending
10 - captured / deposited
30 - payment lower than stipulated
amountRemaining Amount to be deposited to complete the transaction.

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

The structure of the JSON object should look like this:

{
  "merchantId": "MID",
  "merchantKey": "MKEY",   
  "order":{
     "bitcoin":{
	  "currency":"BRL",
	  "amount":"1.00",
	 "referenceTag": "1234"
	}
    }
}
	
	
Transaction Return

{
   "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

These requests are responsible for performing Bitcoin transaction checks. Transactions are verified at the Blockchain network and if any bitcoin amount was deposited to the address, it will update the transaction status.

Parameters received are:

NAME DESCRIPTION
merchantId Store ID that identifies the establishment.
merchantKey Key associated with store ID.
Affiliate Store Id Affiliate Store Id
btcTransactionId Transaction ID created in the "bitcoin" command.

The following information is returned in the JSON object:

NAME DESCRIPTION
success Indicates whether the address was created correctly.
False - Error generating address. Try again.
False - Error generating address. Try again.
transactionState Transaction Status Indicator.
6 - deposit pending
10 - captured / deposited
30 - Payment lower than given
referenceTag Observation / Description informed by the client in the request.
transactionTimestamp Date / time of transaction in epoch format.
responseCode Transaction status indicator on Bit.One. 0 - approved 1 - denied - check errorMessage
approvedAmount Amount received (BRL / USD). This value should be used as a reference for releasing credits.
qrcodeUr URL for generating QR code.
errorMessage Error Message
btcAmount Value of the deposit in Bitcoin.
btcAmountReceived Value in Bitcoin received in the portfolio.
amountRemaining Amount to be deposited in case of lower payment. Use this value to create a companion transaction if necessary. Use this value to create a companion transaction if necessary.
btcAmountRemaining Amount not deposited in Bitcoin.
btcPrice Bitcoin price at time of deposit.
address Portfolio address for deposit.
returnFeeBtc Additional fee for the shop in Bitcoin. 
 The structure of the JSON object should look like this:

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



Transaction Return:
{
  "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

This type of requisition is responsible for registering a new store associated with an existing store. Usually used by networks of stores and / or resellers. It checks the data from the "parent" store and replicates its settings to the "daughter" store.

NAME DESCRIPTION
merchantId Store ID that identifies the establishment.
merchantKey Key associated with store ID.
name Fantasy name.
dba Company Name
E-mail E-mail
Address Address
Complement Complement
Neighborhood Neighborhood
City City
State State
Zip Zip
TaxId CNPJ's Store
UserFirstName UserFirstName
UserLastName UserLastName
UserEmail User email for portal access
UserPhone UserPhone
UserLanguage UserLanguage
US - Inglês
BR - Português Brasil
WalletBTC Wallet / Address of Bitcoin from the store.

The following information is returned in the JSON object:

NAME DESCRIPTION
Success Indicates whether the address was created correctly.
true - sucesso.
false - address generation error. Try again..
orderID ID created for transaction.
transactionTimestamp Date / time of transaction in epoch format.
merchantId establishment ID..
merchantKey Key for API access.
message Informational message.
errorMessage Error Message. 

The structure of the JSON object should look like this:
	    
{
"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"
}

NOTE

You can update the data from a daughter store. Just pass on the requisition merchantId of the store that should have your data updated.


The structure of the JSON object should look like this:
{
"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

These requests are responsible for processing requests for balance checking available for withdrawal. It checks the amount available for withdrawal in a given currency.

The received parameters are:

Name Description
merchantId Store ID that identifies the establishment.
merchantKey Key associated with store ID.
currency USD - American dollar
BRL - Real
BTC - Bitcoin

The following information is returned in the JSON object:

Name Description
sucess Indicates whether the address was created correctly.
true - sucess
false - address generation error. Try again.
orderID orderID ID created for transaction.
transactionTimestamp Date / time of transaction in epoch format.
currency. Coin.
amount Value available for withdrawal.
Message Informative message.
errorMessage Error Message. 
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

These requests are responsible for processing requests for withdrawal requests. It checks if the balance requested is available and if so, adds the withdrawal request.

The received parameters are:

NAME DESCRIPTION
merchantId Store ID that identifies the establishment.
merchantKey Key associated with store ID.
currency Coin
amount Value

You can also check the status of a previously generated withdrawal request by simply using the generated ID.

The received parameters are:

NAME DESCRIPTION
merchantId Store ID that identifies the establishment.
merchantKey Key associated with store ID.
withdrawalId ID of the service transaction to be queried.

The received parameters are:

NAME DESCRIPTION
sucess Indicates whether the address was created correctly
true- sucess
false - address generation error. Try again.
transactionstate Transaction Status Indicator
6 - pending
3 - approved / queued for processing
10 - processed serve
12 - canceled
13 - failure / error in the transfer process
orderID ID created for transaction
transactionTimestamp Date / time of transaction in epoch format
currency Coin
USD - American dollar
BRL - Real
BTC - Bitcoin
amount Withdrawal amount
withdrawalId ID generated for this transaction
message Informative message
errorMessage Error Message 
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"
}

Transaction Status

Check here for possible transactions status:


TRANSACTIONSTATE DESCRIPTION
3 Successfully approved
6 Pending
9 Unauthorized transaction.
10 Transaction captured
Ticket Paid Bitcoin Deposited
Draw completed
12 Transaction canceled
13 Failure
15 Timeout na Adquirente
17 Offline system
27 When the debit transaction is successfully completed but needs to be confirmed by the customer.
28 Ticket Created.
29 Displayed Ticket
30 Ticket Paid / Bitcoin Deposited (lower value than stipulated)
31 Ticket Paid/Bitcoin Depositado (valor acima do estipulado)

General information

The Brand Bit.One. and the entire contents of this manual is the property of Tranfero Payment S.A., enrolled with CNPJ under number 11.480.809 / 0001-84, established at Rua Barão do Flamengo, nº 22 - sala

The use of this material or copy without the prior authorization of the company infringes the Intellectual Property Law and thus will be responsible for the use, subject to all applicable legal measures.

Glossary

Estabelecimento / Merchant Vendor data entered on the Bit.One platform / Gateway user.

Sandbox = Platform testing environment.

MID / Merchant ID = Merchant ID on Bit.One.

MKEY / Merchant Key = The shopkeeper's key to use the API.

Blockchain =Network or structure where all the records of the bitcoin transactions are located.

Bitcoin/BTC = It is a criptomoeda and online payment system based on open source protocol that is independent of any central authority.

Example