Tools for developers

As any other Drupal 8 module, Commerce Funds provides easily reusable code that allows you to adapt the background concept to your needs.

Transaction as entity

The module is made on a single Content Entity Type called Transaction which is supposed to hold any transactions made through the website. By default there are 5 bundles :

• Deposit (deposit)
• Transfer (transfer)
• Escrow (escrow)
• Payment (payment)
• Withdrawal (withdrawal_request)
• Conversion (conversion)

Definition of a Transaction Entity

The transaction entity is defined as-is:

Transaction::create([
      'issuer' => (int)$issuer, // User uid targets instance of \Drupal\Core\Session\AccountInterface, the issuer of the transaction.
      'recipient' => (int)$recipient, // User uid targets instance of \Drupal\Core\Session\AccountInterface, the recipient of the transaction (sometimes == to the issuer).
      'type' => (string)'type', // Transaction bundle ('deposit', 'transfer', 'escrow', 'payment', 'withdrawal_request' or 'conversion').
      'method' => (string)'method', // Method used for the transaction, can be a Drupal commerce payment method for a deposit, 'internal' for transfers, escrows, payments and conversions. Withdrawal method for withdrawal requests.
      'brut_amount' => (decimal)$amount, // The amount requested by the user before applying fees OR amount before conversion.
      'net_amount' => (decimal)$net_amount, // The amount after aplying the fees OR the amount after conversion.
      'fee' => (decimal)$fee, // The amount of fee OR the currency exchange rate.
      'from_currency' => (string)$currency, // The initial currency for a conversion, i.e from EUR to something. Instance of \Drupal\commerce_price\Entity\Currency.
      'currency' => (string)$currency, // The currency of the transaction OR the converted currency ... to USD. Instance of \Drupal\commerce_price\Entity\Currency.
      'status' => (string)'status', // The transaction status (Pending, Completed). Status are available as static var in TransactionInterface.
      'notes' => (string)'notes', // The notes left by the user if any.
]);

Services provided

Commerce funds provides 2 useful services for developers to help them build customized code over the contrib module.

• FeesManager to manage operations related to fees calculation.
• TransactionManager for all operations regarding transactions.

A transaction can be executed as followed:

use Drupal\commerce_funds\Entity\Transaction;
  
// Calculate the fee applied to the transaction.
  $fee_applied = \Drupal::service('commerce_funds.fees_manager')->calculateTransactionFee($amount, $currency, 'transfer');

  // Create a new transaction.
  $transaction = Transaction::create([
      'issuer' => $issuer->id(),
      'recipient' => $recipient->id(),
      'type' => 'transfer',
      'method' => 'internal',
      'brut_amount' => $amount,
      'net_amount' => $fee_applied['net_amount'],
      'fee' => $fee_applied['fee'],
      'currency' => $currency,
      'status' => Transaction::TRANSACTION_STATUS['canceled'],
      'notes' => $this->t('Transaction paid for done service.'),
    ]);

   // Save the transaction to the db.
   $transaction->save();

  // Perform the transaction to update the differents balances.
  \Drupal::service('commerce_funds.transaction_manager')->performTransaction($transaction);

Important! Since 2.1.0, the status of the created Transaction should always be set to "canceled" or "pending" (depending on the transaction type). The status of the Transaction to "completed" will automatically be set during performTransaction just after the balances have been updated. Thus, to prevent a transaction to appear as completed whereas the balance wouldn't have been updated.