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: "Like comment #123145512",
appAction: "like",
payments: [
{ destination: 'nosetwo', currencyCode: 'USD', sendAmount: 0.25 },
]
};
const paymentResult = await account.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 account = 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 account.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 account.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 |