GuidesCommunity
Guides

P2P Payments

Peer to Peer Payments are a fast and reliable way to transfer Assets between Wallets.

Suggest Edits

P2P works by creating Transactions, that each may contain multiple Payments. Payments from the same Transaction may even handle different Assets, but only if all Assets are from the same provider. Transactions are embed on the blockchain and are immutable after processing. You can't edit a Transaction after it's already executed - you will need to create a new one to revert any mistakes.

You can create a simple payment with the example payload below:

// Creates a new transaction using the SDK
const transaction = await bitcapital.payments().pay({
  // The source wallet id
  source: '9b1d1baa-a7a6-4cd9-ac40-616514d548b7',
  recipients: [{
    // The asset code or ID for this payment
  	asset: 'BRLD',
    // The amount to send for this recipient
    // It's important to send as a string to avoid rounding issues
    amount: '100.00'
  }],
});

curl --location --request POST 'https://testnet.btcore.app/payments' \
--header 'Content-Type: application/json' \
--data-raw '{
	"source": "6dc8d0ce-ee77-4031-9434-baff510139f6",
	"recipients": [{
		"asset": "BRLD",
		"amount": "1.00",
		"destination": "fcb7155d-ff8d-415b-9056-dc6bc648e4ef"
	}]
}'

When creating multiple payments at once, you may choose between Split Payments and Bulk Payments. This is the default approach, event for a single payment. You may pass an array with a single recipient.


Split Payments

The platform supports sending a payment to a lot of recipients in a single API request, we call it Split Payments. They are faster to process and access, as they generate a Single Transaction in the blockchain and thus, in the user transaction history.

const source = '9b1d1baa-a7a6-4cd9-ac40-616514d548b7';

// Pay 100 BRLD to Bob
const bob = {
  asset: 'BRLD',
  amount: '10.00000', // number string with at most 6 decimal places
  destination: '82b24cfc-8421-419c-9ff8-333d0e91cdaa', // Bob Wallet ID
};

// Pay 35 BRLD to Josh
const josh = {
  asset: 'BRLD',
  amount: '35',
  destination: '2d008a35-69b5-4f45-9ba2-bff7e0650097', // Josh  Wallet ID
};

// Perform P2P transaction
const transaction = await bitcapital.payments().pay({
  source,
  recipients: [bob, josh],
  // Optional scheduling
  scheduleFor: new Date(Date.now() + 60 * 1000),
});

curl --location --request POST 'https://instance-url.btcore.app/payments' \
--header 'Authorization: Bearer 0000000000000000000000000000000000000000'\
--header 'Content-Type: application/json' \
--header 'X-Request-Signature: 140cf378103cb985a938fa3080401f9eb72524172f1a9725482c74a003d4993b' \
--header 'X-Request-Timestamp: 1578678110828' \
--data-raw '{
	"source": "9b1d1baa-a7a6-4cd9-ac40-616514d548b7",
	"recipients": [{
		"asset": "BRLD",
		"amount": "10.00000",
		"destination": "b0066e1682b24cfc-8421-419c-9ff8-333d0e91cdaa"
	},
	{
		"asset": "BRLD",
		"amount": "35",
		"destination": "2d008a35-69b5-4f45-9ba2-bff7e0650097"
	}]
}'

📘

Max Number of Payments

For the BRLD we have a limitation of 5 payments per transaction, for STR Provider assets this limit can be up to 100 payments.


Bulk Payments

Bulk Payments creates multiple transactions at once, and enables you to specify different sources to different payments. Creating additional Transactions that may slow the processing queue and occur in additional costs.

❗️

Work in Progress

Sending payments in bulks under pilot operation and is not currently available in production environments. Contact your project manager for more information.

A bulk payment with multiple sources and assets may be created with:

// Source Wallet ID
const alan = '75baeaf6-925e-49ec-afd3-593a8a73e155';
const paul = 'f4b58152-14b1-4690-bb62-2b32bb656cc6';

// Alan pays 100 BRLD to bob
const bob = {
  source: alan,
  recipients: [{
    asset: 'BRLD',
    amount: '100',
    destination: '82b24cfc-8421-419c-9ff8-333d0e91cdaa', // Bob Wallet ID
  }],
};

// Paul pays 0.035 BRLP to josh
const josh = {
  source: paul,
  recipients: [{
    asset: 'BRLP',
    amount: '0.035',
    destination: '2d008a35-69b5-4f45-9ba2-bff7e0650097', // Josh Wallet ID
  }],
};

const transaction = await bitcapital.payments().pay([bob, josh]);

Filtering transactions

❗️

Work In Progress

Filtering payments is under pilot operation and is not currently available in production environments. Contact your project manager for more information.

When requesting a list of transactions, you can optionally provide a JSON query parameter "filters".
This property will be used to query the database and get all transactions that includes this property on it's user defined additional data.

const walletId = '82b24cfc-8421-419c-9ff8-333d0e91cdaa';

// When requesting a new P2P payment, you may add additional data
await bitcapital.payments().pay({
  source: '2d008a35-69b5-4f45-9ba2-bff7e0650097',
  recipients: [{
    asset: 'BRLD',
    amount: '100',
    destination: walletId,
  }],
  extra: { some: 'stuff', fizz: 'buzz', my: 'payment' } // User defined additional data
}

// And now you may filter the transaction list using a subset of this additional data
const transactions = bitcapital.wallets().findWalletTransactions(walletId, {}, { some: 'stuff');

Updated over 3 years ago

What’s Next