Automated Payouts (MPay) Integration Guide

What you’ll learn

In this article you’ll learn:

• How MPay’s Deposit & Reconcile model works
• How to pass payment references during order creation
• How to handle payment references for refunds
• How to use the mPayStartDepositReconciliation mutation to reconcile deposits

Overview

This guide outlines the integration steps required to utilise MPay, Marketplacer’s integrated global payout infrastructure powered by Airwallex. By adopting MPay, Marketplace Operators can transition from manual, spreadsheet-based payouts to a fully automated system.

To enable this automation, Marketplacer requires precise mapping between the funds you collect from shoppers (via your front-end payment gateway) and the funds you deposit into the MPay ecosystem for seller distribution.

The Reconciliation Model

The MPay workflow relies on a Deposit & Reconcile model:

1. Capture: You capture funds from the shopper using your existing gateway (Stripe, Adyen, Braintree, etc.).
2. Tag: You pass the Gateway Transaction ID (Payment Reference) to Marketplacer during order or refund creation.
3. Deposit: Periodically (e.g., daily), you transfer the aggregated net funds to your MPay (Airwallex) Holding Account.
4. Reconcile: You signal Marketplacer via API that a deposit has been made, detailing which specific orders and refunds (Payment References) are included in that lump sum.

1. Order Creation

Endpoint: orderCreate (Mutation) and orderUpdate (Mutation)

Reference: OrderInput Documentation

When placing an order into Marketplacer, if the customer is using MPay, you must include the paymentReferences argument. This serves as the unique link between the external financial transaction and the Marketplacer Order ID.

Schema Update

paymentReferences is a top-level argument on the orderCreate and orderUpdate mutations (not a field inside OrderInput). The below example shows a single order being created with multiple payment references. This may be the situation where part of the order (e.g. $15) was purchased using a gift card and the remainder ($5) was purchased using a credit card.

Input Object: MPayPaymentReferenceInput

mutation createOrder(
  $order: OrderInput!
  $paymentReferences: [MPayPaymentReferenceInput!]
) {
  orderCreate(input: {
    order: $order
    paymentReferences: $paymentReferences
  }) {
    # ...
  }
}

# Variables:
# {
#   "order": { ... existing fields (cart_id, shopper_email, etc.) ... },
#   "paymentReferences": [
#     {"paymentReference": "GC_230226_1", "amount": "15.00"},
#     {"paymentReference": "VISA_230226_2", "amount": "5.00"}
#   ]
# }

Implementation Note

2. Handling Refunds

Endpoints: refundRequestRefund (Mutation), refundRequestApprove (Mutation) and invoiceAmendmentUpdate (Mutation)

Reference: refundRequestRefundMutationInput Documentation

When initiating a refund, you must provide the payment reference associated with the funds being returned to the shopper. This allows MPay to adjust the net payout calculation for the seller involved in the return, ensuring we do not pay out commissions on refunded goods and transfer any funds for the refund back to the operator.

Schema Update

input refundRequestRefundMutationInput {
  # ... existing fields (order_id, line_item_ids)

  # NEW: The reference associated with the refund transaction
  paymentReferences: [
    {paymentReference: "REF_GC_230226_1", amount: "15.00"},
  ]
}

3. Deposit Reconciliation

Endpoint: mPayStartDepositReconciliation (Mutation)

This is the core of the MPay automation. At an interval of your choosing (typically matching your Payment Gateway’s settlement schedule, e.g., daily), you must inform Marketplacer of the bulk deposit made into your Airwallex holding account.

This mutation tells Marketplacer: “I have deposited $X into the holding account. This money covers the following list of orders and refunds.”

Marketplacer then matches what is provided in the Deposit Reconciliation mutation against existing order and refund references and checks the MPay account to ensure the amount deposited is correct.

The Mutation

mutation mPayStartDepositReconciliation($input: mPayStartDepositReconciliationInput!) {
  mPayStartDepositReconciliation(input: $input) {
    mPayDepositReconciliation {
      id
      status
    }
    clientMutationId
    errors {
      messages
      field
    }
  }
}

Input Object: MPayStartDepositReconciliationInput

Input Object: PaymentReconciliationItem

Example Payload

In this scenario, the operator has deposited $297.00 into the MPay account, covering two separate orders.

mutation {
  mPayStartDepositReconciliation(input: {
    depositReference: "dr111",
    amount: 297.00,
    paymentReferences: [
      {
        paymentReference: "pr001",
        amountPaid: 100.00,
        amountCollected: 99.00
      },
      {
        paymentReference: "pr002",
        amountPaid: 200.00,
        amountCollected: 198.00
      }
    ]
  }) {
    mPayDepositReconciliation {
      id
      status
    }
    clientMutationId
    errors {
      messages
      field
    }
  }
}

Calculation Logic

Marketplacer validates that the sum of amountCollected across all payment references balances against the total deposited into the MPay account:

sum(amountCollected) = sum(amountDeposited)

The mutation itself will return errors only for validation failures (e.g. missing required fields, duplicate references, or MPay not being enabled). Amount mismatches are handled asynchronously — the reconciliation record is created with a status of unmatched, and a background process then evaluates the totals. If the values do not balance, the status is updated to error and the payout process for the affected orders will pause until the discrepancy is resolved.

Frequently Asked Questions

Q: What happens if I forget to send the payment references on Order Create?

The order will be created, but it will be “unreconcilable” in the MPay system. You will need to update the paymentReferences via the orderUpdate mutation before it can be processed for a payout. Similarly, you can add payment references to an existing refund using the invoiceAmendmentUpdate mutation.

Q: Do I need to include amountCollected?

Yes. MPay calculates the flow of funds based on what effectively hit your bank account. amountCollected is usually:

Gross Order Value - Payment Gateway Fees

Q: Can I run the deposit reconciliation mutation multiple times a day?

Yes. However, each depositReference must be unique. If you make three separate deposits to Airwallex in one day, you must fire this mutation three times with the respective batch of orders.

Q: What if I have made a mistake in the deposit reconciliation mutation?

You can remove the deposit reconciliation reference and its associations by using the mPayDeleteDepositReconciliation mutation. Here you will be required to provide the id of the Deposit Reconciliation reference.