Automatic Payments

Developers can prompt users to authorize automatic payments to their app. Once automatic payments are authorized, the app can request and receive payments from the user's wallet without the user needing to confirm each transaction. The user can set limits on the size of each payment, and the cumulative amount.

This feature is very useful for apps requiring high frequency, low value transactions.

Note: The payment uses your application secret so must be sent from your backend server.

Step 1: Authorize automatic payments

Redirect the client to the DotWallet automatic payment authorization screen

Param Required Description
app_id YES Application ID
redirect_uri YES Url to redirect client to after authorization

The DotWallet automatic payment authorization screen:

  • User taps Continue

    	1. User decides what limit to put on individual transactions, and the cumulative total transaction value (default 0.01 and 0.1 BSV)
    	2. After the user confirms, the page will redirect to <font color=orange>{redirect_uri}</font>
  • User taps Refuse

The client will be redirected to {redirect_uri}

Failure example:

Error code Description
10003 Micropayment error, incorrect redirect_uri

Step 2: Initiate a payment

Param Required Type Description
app_id YES string Application ID
secret YES string Application secret key
merchant_order_sn YES string Order ID (recommended: UUID)
pre_amount YES int Payment amount (unit: satoshi)
user_open_id YES string User's global ID
item_name YES string Purchased item, product, or service name
opreturn NO string User provided custom OP_RETURN message/data (format: rawhex)
receive_address NO string Receiving wallet address. If left empty will send to app developer's default wallet as per the app settings

Note: receive_address must be a string that is a valid JSON array of objects such as the following:

    "address": "1MS3HE9M3oEqW81KXp8iK9nBMTGXekdxAP",
    "amount": 622


Note: "code" here is the error response code. 0 means success

  "code": 0,
  "msg": "",
  "data": {
    "order_sn": "ORDER_SN",
    "pay_txid": "PAY_TXID"

Return params description:

Param Description
order_sn DotWallet generated order number
pay_txid TXID (bitcoin transaction ID)

Failure example:

If the user is prompted that the balance is too low, please redirect them to Step 1
payment exists

  "code": 10039,
  "msg": "Micropayment error, the current order number already exists",
  "data": []

balance too low

  "code": -101001,
  "next_do": "todo",
  "show_kind": 1,
  "data": "balance=0,amount=700,fee=113,0 < 813"