Cashback API

tonyofbyteball edited this page Dec 14, 2017 · 6 revisions

This API is for merchants and payment processors who participate in the Byteball cashback program.

After you accepted payment from the customer, you use this API to request cashback for your customer. You send a POST request to:

(for testnet use

and pass the following parameters:

  • partner: (string) your partner name you were assigned when you signed up for the program.
  • partner_key: (string) partner key used to authenticate your requests.
  • customer: (string) any id of the customer who made a purchase such as customer name or id in your database. This field must be the same when the same customer makes another purchase.
  • order_id: (string) unique id of the order associated with the purchase. You should never request cashback for the same order id again.
  • description: (string) description of the purchase.
  • merchant: (string) this field is used by payment processors only to identify the individual merchant. When another purchase is made from the same merchant, this fiels should be the same.
  • address: (string) Byteball address or email address of the customer. The cashback will be sent to this address. If it is email address, a textcoin will be sent. If the textcoin is not claimed within 1 week, it will be taken back.
  • currency: (string) currency of the purchase. Supported values: USD, EUR, RUR, GBYTE, BTC. If the purchase was paid in any other currency, you should convert its amount to any of the supported currencies except GBYTE.
  • currency_amount: (number) amount of the purchase in currency.
  • partner_cashback_percentage: (number) the percentage of the amount you want to pay to the customer out of your own funds in addition to the regular cashback. Byteball will add the same percentage out of the distribution fund (merchant match). Default it 0. You have to deposit the funds in advance in order to fund this option.
  • purchase_unit: (string) unit (transaction id) of the customer's purchase if it was paid in GBYTE.

Response format

The response is in JSON format. It always contains a result field, which is either 'ok' or 'error'.

If the cashback was successfully sent to the customer, the response has "result": "ok" and also indicates the cashback amount and the unit it was sent in:


In case of an error, the response has "result": "error" and error description in error field:

{"result":"error","error":"authentication failed"}
Clone this wiki locally
You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.
Press h to open a hovercard with more details.