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 cloudAccount = await handCashConnect.getAccountFromAuthToken(token);

const paymentParameters = {
    description: "Like comment #123145512",
    appAction: "like",
    payments: [
        { destination: 'nosetwo', currencyCode: 'USD', sendAmount: 0.25 },
    ]
};

const paymentResult = await cloudAccount.wallet.pay(paymentParameters);
console.log(paymentResult);

Output:

{
  transactionId: '4c7b7cdc18702bb1a09c75a47bc2fa9630545761fbbd53b8c38735c73173e043',
  note: 'Like comment #123145512',
  type: 'send',
  time: 1604958667,
  satoshiFees: 113,
  satoshiAmount: 15555,
  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'
}

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.com, 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: "Tip group #23421555",
    appAction: "tip-group",
    payments: [
        { to: 'eyeone', currencyCode: 'USD', amount: 0.25 },
        { to: 'cryptokang@moneybutton.com', currencyCode: 'EUR', amount: 0.25 },
        { to: '131xrWSKXHbhucFPTfZqnxF8ZhjpMxJH7K', currencyCode: 'SAT', amount: 50000 },
    ]
};


Video Walkthroug: Simple Payments

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



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 cloudAccount = await handCashConnect.getAccountFromAuthToken(token);
const paymentParameters = {
    appAction: "publish",
    payments: [
        { destination: 'nosetwo', currencyCode: 'USD', sendAmount: 0.25 },
    ]
    attachment: { format: 'json', value: {"param1": "value1", "param2": "value2"} },
};

const paymentResult = await cloudAccount.wallet.pay(paymentParameters);
console.log(paymentResult);

Output:

{
  transactionId: '4c7b7cdc18702bb1a09c75a47bc2fa9630545761fbbd53b8c38735c73173e043',
  type: 'send',
  time: 1604958667,
  satoshiFees: 113,
  satoshiAmount: 15555,
  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: 'publish'
}


Fetch a Payment

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

const paymentResult = await cloudAccount.wallet.getPayment("4c7b7cdc18702bb1a09c75a47bc2fa9630545761fbbd53b8c38735c73173e043")

console.log(paymentResult)

Output:

{
  transactionId: '4c7b7cdc18702bb1a09c75a47bc2fa9630545761fbbd53b8c38735c73173e043',
  type: 'send',
  time: 1604958667,
  satoshiFees: 113,
  satoshiAmount: 15555,
  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: 'publish'
}


Video Walkthrough: Transactions with Data

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



Supported Currencies

Connect 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