CashFlow Payment Gateway API Documentation

REST API and WebSocket notifications



Introduction

CashFlow is a Bitcoin Cash payment processor featuring instant zero confirmation payments, and live payment notifications. It enables buyers to make secure instant purchases and merchants to make instant withdrawals for a low fee.


A merchant or a developer can take order requests from clients and update them live on the status of their purchase and can also see purchase requests live on their dashboard. They can create invoices and send the URL to their clients.


REST API

In order to start making requests to the API, the merchant must first register through the dashboard register page or the /register POST endpoint, log in through the /login endpoint with their new credentials, then use the JWT token they received in the Authorization header to start making new order / invoice and withdrawal requests.


POST /register

Send a JSON object with email and password keys in order to register to the gateway.


Headers:

Content-Type:application/json

Request:

{email: "example@mail.com","password":"superstrongpass"}

Responses: (JSON)

{"success":"registered sucesfully"}
{"error":"missing parameters}

POST /login

Send a JSON object with email and password keys in order to login to the gateway.


Headers:

Content-Type:application/json

Request:

{email: "example@mail.com","password":"superstrongpass"}

Responses: (JSON)

{"token":"jwttoken"}
{"error":"missing parameters}

POST /withdraw

Send a JSON object with addressand the Authorization header containing your JWT token to withdraw your Bitcoin Cash earnings.


Headers:

Content-Type:application/json
Authorization: Bearer [JWT]

Request:

{address: bitcoincash:withdrawaladdress}

Responses: (JSON)

{"txid":"bitcoincashtxid"}
{"error":"funds too low"}

GET /transactions

Make a GET request to this endpoint with your Authorization header containing your JWT token to get an array of the orders from your clients.


Headers:

Authorization: Bearer [JWT]

Responses: (JSON)

[{"price":0.01,"itemdesc":"One VPS","address":"bchaddress","returnaddr":"returnaddress","postdata":"{}","posturl":""},...]

GET /transactions/[txid]

You can get a single order by it's TXID.


Headers:

Authorization: Bearer [JWT]

Responses: (JSON)

{"price":0.01,"itemdesc":"One VPS","address":"bchaddress","returnaddr":"returnaddress","postdata":"{}","posturl":""}

POST /transactions

Create a transaction (order attempt). Only gets saved in the database when the client pays. Returns an address for the client to pay to.


Headers:

Authorization: Bearer [JWT]
Application-Type:application/json

Request: (JSON)

{"price":0.01,"itemdesc":"One VPS","address":"bchaddress","returnaddr":"returnaddress","postdata":"callbackdata","posturl":"backend/callbackurl"}

Response: (JSON)

{address: depositaddressforclient}

GET /invoices/[receivingbitcoincashaddress]

You can generate an invoice link for a client by appending the payment receiving address you got from /transactions to this URL.



Websocket Notifications

You can receive live updates on a transaction payment by using socket.io to bind to the root URL of the payment gateway at the event event.


The event event receives an object in the format of {address:address,event:eventname} where address is the receiving Bitcoin Cash address and the event is one of success, underpaid or overpaid. In the case of underpaid or overpaid events, there will also be an amount field to denote how much BCH needs to be deposited more or is about to be refunded for being surplus.


Below is a code snippet that we hope will help you use this feature.



<script>
  var socket = io('https://cashflow.fm');
  socket.on('event', function (data) {
      if(data.address == addressfromposttransactions) {
          switch(data.event) {
              case "success":
              //inform the user of payment success
              break;
              case "overpaid":
              //inform the user of payment success and that they'll get the money they paid extra back
              break;
              case "underpaid":
              //inform the user of payment failure and how much they need to pay more (in data.amount)
              break;
              default: 
              break;
          } else {
              //not relevant to current tx, you can ignore safely
          }
      }
  });
</script>
      

Notes

You must always include the Content-Type:application/json header when you make POST requests with JSON format or your requests will fail.