Payments

Simple Payments

HandCash Connect enables you to construct and execute transactions on behalf of your connected users. This can be done by passing payment parameters through the wallet.pay function:

const {HandCashConnect} = require('@handcash/handcash-connect');
const handCashConnect = new HandCashConnect('<app-id>'); 
const account = handCashConnect.getAccountFromAuthToken(token);
const paymentParameters = {
    description: "Hold my beer!🍺",
    appAction: "like",
    payments: [
        { destination: 'nosetwo', currencyCode: 'DUR', sendAmount: 25 },
    ]
};
const paymentResult = await account.wallet.pay(paymentParameters);
console.log(paymentResult);

Output:

{
  transactionId: '4c7b7cdc18702bb1a09c75a47bc2fa9630545761fbbd53b8c38735c73173e043',
  note: 'Hold my beer!🍺',
  type: 'send',
  time: 1604958667,
  satoshiFees: 113,
  satoshiAmount: 12500,
  fiatExchangeRate: 160.74284545024352,
  fiatCurrencyCode: 'USD',
  participants: [
    {
      type: 'user',
      alias: 'nosetwo',
      displayName: 'Nose two',
      profilePictureUrl: 'https://res.cloudinary.com/hk7jbd3jh/image/upload/v1574787300/gntqxv6ed7sacwpfwumj.jpg',
      responseNote: ''
    }
  ],
  attachments: [],
  appAction: 'like'
}

For payments we recommend the Duro, or DUR. Duro is equal to 500 Satoshi, or 0.000005 BSV.

Read more about duro here.

appAction is used for transaction labeling and notification grouping. This way, HandCash can display more insightful information to users.

Recipient Types

HandCash Connect supports three different recipient types:

Example: eyeone
Recommended for sending money to another HandCash user.

Example: name@moneybutton.io, name@relayx.io, etc...
Recommended for sending money to another services.

Example: 1BvBMSEYstWetqTFn5Au4m4GFg7xJaNVN2
Recommended for sending money to a custom addresses.

Pay to multiple people

The Connect SDK allows up to 200 recipients per payment. To send to multiple people, add more recipients to the payments array while constructing your app parameters:

const paymentParameters = {
    description: "Hold my beer!🍺",
    appAction: "like",
    payments: [
        { to: 'eyeone', currencyCode: 'DUR', amount: 1 },
        { to: 'eyeone@moneybutton.com', currencyCode: 'EUR', amount: 0.25 },
        { to: '131xrWSKXHbhucFPTfZqnxF8ZhjpMxJH7K', currencyCode: 'USD', amount: 0.25 },
    ]
};

Video Walkthroug: Simple Payments

Below is a video walkthrough illustrating a demo implementation of the simple payments and multi-recipient payments:

Some of the code in the video may be outdated, please refer to the documentation for up to date code.

Attach Data

With the SDK, you can alse attach public data to payments. This data is uploaded to a public and immutable blockchain, meaning it cannot be modified or deleted. This can be used as a data timestamping service, and can lend transparency to your platform.

You may attach data in the following formats:

attachment: { format: 'base64', value: 'ABEiM0RVZneImQCqu8zd7v8=' }

attachment: { format: 'hex', value: '0011223344556677889900AABBCCDDEEFF' }

attachment: { format: 'json', value: {"param1": "value1", "param2": "value2"} }

To attach data, add an attachment field to your payment parameters:

const {HandCashConnect} = require('@handcash/handcash-connect');
const handCashConnect = new HandCashConnect('<app-id>'); 
const account = handCashConnect.getAccountFromAuthToken(token);
const paymentParameters = {
    description: "Hold my beer!🍺",
    appAction: "like",
    payments: [
        { destination: 'nosetwo', currencyCode: 'DUR', sendAmount: 200 },
    ]
    attachment: { format: 'json', value: {"param1": "value1", "param2": "value2"} },
};
const paymentResult = await account.wallet.pay(paymentParameters);
console.log(paymentResult);

Output:

{
  transactionId: '4c7b7cdc18702bb1a09c75a47bc2fa9630545761fbbd53b8c38735c73173e043',
  note: 'Hold my beer!🍺',
  type: 'send',
  time: 1604958667,
  satoshiFees: 113,
  satoshiAmount: 10000,
  fiatExchangeRate: 160.74284545024352,
  fiatCurrencyCode: 'USD',
  participants: [
    {
      type: 'user',
      alias: 'nosetwo',
      displayName: 'Nose two',
      profilePictureUrl: 'https://res.cloudinary.com/hk7jbd3jh/image/upload/v1574787300/gntqxv6ed7sacwpfwumj.jpg',
      responseNote: ''
    }
  ],
  attachments: [ { value: [Object], format: 'json' } ],
  appAction: 'like'
}

Fetch a Payment

You may use the SDK to fetch information about a transaction, using the transaction ID as reference.

const paymentResult = await account.wallet.getPayment("4c7b7cdc18702bb1a09c75a47bc2fa9630545761fbbd53b8c38735c73173e043")
console.log(paymentResult)

Output:

{
  transactionId: '4c7b7cdc18702bb1a09c75a47bc2fa9630545761fbbd53b8c38735c73173e043',
  note: 'Hold my beer!🍺',
  type: 'send',
  time: 1604958667,
  satoshiFees: 113,
  satoshiAmount: 10000,
  fiatExchangeRate: 160.74284545024352,
  fiatCurrencyCode: 'USD',
  participants: [
    {
      type: 'user',
      alias: 'nosetwo',
      displayName: 'Nose two',
      profilePictureUrl: 'https://res.cloudinary.com/hk7jbd3jh/image/upload/v1574787300/gntqxv6ed7sacwpfwumj.jpg',
      responseNote: ''
    }
  ],
  attachments: [ { value: [Object], format: 'json' } ],
  appAction: 'like'
}

Video Walkthrough: Transactions with Data

Below is a video walkthrough illustrating a demo implementation of transactions with data attached:

Some of the code in the video may be outdated, please refer to the documentation for up to date code.

Supported Currencies

The Duro is a universal money for apps and games:

Currency Code	Currency Name	Description
DUR	Duro	1 duro = 500 satoshis

Connect also supports the following currencies conversions:

Currency Code	Currency Name
ARS	Argentinian Peso
AUD	Australian Dollar
BRL	Brazilian Real
CAD	Canadian Dollar
CHF	Swiss Franc
CNY	Chinese Yuan
COP	Colombian Peso
CZK	Czech Koruna
DKK	Danish Krone
EUR	Eurozone Euro
GBP	British Pound
HKD	Hong Kong Dollar
JPY	Japanese Yen
KRW	Korean Won
MXN	Mexican Peso
NOK	Norwegian Krone
NZD	New Zealand Dollar
PHP	Philippine Peso
RUB	Russian Ruble
SEK	Swedish Krona
SGD	Singapore Dollar
THB	Thai Baht
USD	United States Dollar
ZAR	South African Rand

Additionally, Connect supports the following BitCoin SV currencies:

Currency Code	Currency Name	Description
SAT	satoshis	Indivisible unit
BSV	bitcoins	1 bitcoin = 100000000 satoshis