A money-out payment merchant is essential to pay commissions. Although there are many providers built into the Platform, you have the power to add a custom one using the Client Extension.

Building a Custom Commission Merchant Integration

Refer to the Pull Request below to learn how to implement a Custom Commission Merchant Integration. The provided example does not integrate with any third-party APIs but includes comments in the code where External Merchant APIs would be called.

github.com

Implement Custom Commission Merchant by ds-vinny · Pull Request #8 · DS-Partners/AcmeClientExtension

❗️

This code example should only be used to understand how to write an integration with a third-party Merchant. All third-party integrations should be rigorously tested to ensure that there are no defects or miscalculations as they could be very costly.

This example shows the following methods implemented:

• The PayCommissions() Method - Required For All Money Out Merchant Integrations
• The ProvisionAccount() Method - Optional method that can be implemented to create and save account information from a third-party system. This may not need to be implemented as some merchants just accept a Unique ID and create an account. With those type of merchants the AssociateID is often used as the unique Identifier

Key Take-Aways From This Example

Implementing the PayCommissions() Method

This method is a bulk call. If the third-party commission merchant does not have a bulk processing API then the implementation of this method needs to make sure that if any API calls to process a payment fail it does not stop the method from returning payments that were successfully processed.

🚧

If the method is not implemented in this way then the DirectScale system will not have any record of successful payments when a batch has at least one payment that fails.

string payAssociateResult = "";
try
{
  payAssociateResult = await PayAssociate(payments[i]); // Method Contains External Call to Merchant
}
catch (Exception) // do not let external calls stop the loop because some may have processed successfully.
{
  commissionPaymentResults[i].Status = CommissionPaymentStatus.Failed;
  commissionPaymentResults[i].TransactionNumber = "transaction number from external system if applicable";
  commissionPaymentResults[i].ErrorMessage = "Error message from external payment vendor";
}

if (payAssociateResult == "Success")
{
  commissionPaymentResults[i].TransactionNumber = "transaction number from external system";
  commissionPaymentResults[i].Status = CommissionPaymentStatus.Paid;
}

It is important that any CommissionPaymentResult returned by this method is assigned a PaymentUniqueId from the PaymentUniqueId of the CommissionPayment object passed into the method.

public async override Task<CommissionPaymentResult[]> PayCommissions(int batchId, CommissionPayment[] payments)
{
  var commissionPaymentResults = new CommissionPaymentResult[payments.Length];

  for (int i = 0; i < payments.Length; i++)
  {
    commissionPaymentResults[i] = new CommissionPaymentResult()
    {
      DatePaid = DateTime.UtcNow,
      Status = CommissionPaymentStatus.Submitted,
      PaymentUniqueId = payments[i].PaymentUniqueId, // This Id must be assigned!
    };
    
    ... Omitted for Brevity
}