PayFabric from iPaaS.com Invoice Refund Mapping Documentation

Refunds recorded against an iPaaS.com transaction can be synced to PayFabric so the refund appears on the PayFabric Receivables Payments screen and the invoice balance is updated. PayFabric records refunds (and credit memos) as Payment records, so the refund Payment is posted by the child collection while the parent collection marks the invoice as a refund update.

ID Format

Manual Sync ID Format

On the iPaaS.com Manual Sync page, enter the iPaaS.com Transaction Id of the invoice being refunded.

External ID Format

The invoice is matched in PayFabric by the InvoiceId (transaction number) recorded when the invoice was originally transferred. The refund does not create a new external-id record for the invoice.

Deleted Record Support

Outbound delete is not supported for this collection or its child. The delete operations are not implemented and delete mappings are not included in the default templates.

Custom Field Support

This refund flow is driven by iPaaS.com transaction and payment custom fields, which must be populated for a refund to be recognized and posted: Refund Amount, PaymentId, Transaction Key, IsRefundable, AlreadyRefunded, OriginationID, and RefundPaymentIdentity. The custom fields RefundPaymentIdentity, OriginationID, and AlreadyRefunded must exist in iPaaS.com before any refund is initiated.

Mapping Collection Status

Status: Enabled (gated by the filters below)

Trigger Events: Transaction Update (subscribed under Outbound Data Flows as transaction/updated). Manual Sync is also available at any time.

Duplicate or Conflicting Mappings

Add/Update PayFabric Invoice FROM iPaaS.com processes the same transaction entity for ordinary (non-refund) invoice writes; its filter skips refund-flagged transactions, so the two collections are complementary. A transaction should be processed by exactly one path.

Supported Child Collections

Add PayFabric Invoice Payment Refund FROM iPaaS.com — posts the refund as a PayFabric Payment record (PaymentType Refund) against the original invoice payment.

System Caveats

PayFabric Caveats

Refund/Void uses the Referenced Transaction API, which authenticates with the Device ID and Device Password credentials — distinct from the Receivables Sync credentials used for invoices and customers.
The invoice must already exist in PayFabric and have a payment in an approved status before a refund can be posted.
A refund posts a Payment record with PaymentType = Refund and updates the invoice balance.
One refund payment record per invoice — additional refund records linked to the same Transaction Key overwrite the previous refund amount rather than adding a second refund.

iPaaS.com Caveats

The custom fields RefundPaymentIdentity, OriginationID, and AlreadyRefunded must exist in iPaaS.com before initiating refunds. After a successful refund, OriginationID is stored to prevent duplicate refunds on future updates.

Setup Requirements

PayFabric Configuration

Set Integration Method to API only in the PayFabric portal.

iPaaS.com Configuration

Configure Device ID and Device Password in addition to API URL, Portal Name, Integration Key, and Integration Password. Device credentials are required for refunds.
Create the RefundPaymentIdentity, OriginationID, and AlreadyRefunded custom fields, and populate the payment-level refund custom fields.

Integration Flow

A refund is recorded against a transaction in iPaaS.com (the refund custom fields are populated), or the transaction is manually synced.
The parent filter confirms the transaction is an eligible refund (see the Mapping Filter below).
The PayFabric invoice is updated for the refund via POST /receivables/sync/api/{PortalName}/api/invoices.
The child collection posts the refund Payment record to PayFabric through the Referenced Transaction API.
The refund appears on the Receivables Payments screen and the invoice balance is updated.

Mappings

Update PayFabric Invoice Refund FROM iPaaS.com

Mapping Filter

bool isValid = false;
if (!string.IsNullOrEmpty(await GetExternalIdAsync(Id, "Transaction", SpaceportSystemId)))
{    if (Payments?.Count > 0)
    {
        isValid = Type == "Invoice" && (Status == "Complete" || Status == "Awaiting Payment");bool hasInvalidPayments =
    Payments.Any(p =>
        !string.IsNullOrEmpty(GetCustomFieldValue(p.CustomFields, "Refund Amount")?.ToString()) 
    )    ||
    Payments.Any(p =>
        !string.IsNullOrEmpty(GetCustomFieldValue(p.CustomFields, "PaymentId")?.ToString()) 
    )
    ||
    Payments.Any(p =>
        !string.IsNullOrEmpty(GetCustomFieldValue(p.CustomFields, "IsRefundable")?.ToString()) &&
        GetCustomFieldValue(p.CustomFields, "IsRefundable")?.ToString().ToLower() == "true"
    ) ||
    Payments.Any(p =>
        !string.IsNullOrEmpty(GetCustomFieldValue(p.CustomFields, "AlreadyRefunded")?.ToString()) &&
        GetCustomFieldValue(p.CustomFields, "AlreadyRefunded")?.ToString().ToLower() != "true"
    );        isValid = isValid && hasInvalidPayments
    }
    // else: Payments.Count == 0, skip payment checks, still valid if Type/CustomerId/CompanyId is okay
}return isValid;

Filter Description. A transaction is processed as a refund only when all of the following are true: the invoice already exists in PayFabric (an external id is linked for the Transaction); the transaction has at least one payment; the transaction Type is Invoice; and the Status is Complete or Awaiting Payment. In addition, at least one payment must carry a refund indicator — a non-empty Refund Amount custom field, a non-empty PaymentId custom field, IsRefundable set to true, or a present AlreadyRefunded value that is not true. A transaction with no payments does not pass. Transactions that do not meet these conditions are skipped.

Description. Marks the invoice as a refund update and supplies the invoice identity.

Mapping Type	Source Field (iPaaS.com)	Destination Field (PayFabric)	Description
Field	TransactionNumber	InvoiceId	Required. Identifies the PayFabric invoice to refund.
Field	Type	InvoiceType	Required. The PayFabric invoice type.
Static	`"true"`	IsRefund	Always `true`; marks the transfer as a refund update.

Add PayFabric Invoice Payment Refund FROM iPaaS.com

Mapping Filter

var paymentId = GetCustomFieldValue(CustomFields, "PaymentId")?.ToString();
var refundAmount = GetCustomFieldValue(CustomFields, "Refund Amount")?.ToString();
var isRefundable = GetCustomFieldValue(CustomFields, "IsRefundable")?.ToString().ToLower() == "true";
var alreadyRefunded = GetCustomFieldValue(CustomFields, "AlreadyRefunded")?.ToString().ToLower() == "true";
var transactionKey = GetCustomFieldValue(CustomFields, "Transaction Key")?.ToString();if (isRefundable && string.IsNullOrEmpty(transactionKey))
    throw new InvalidOperationException("Transaction Key is required when IsRefundable is true.");return !string.IsNullOrEmpty(paymentId)
    && !string.IsNullOrEmpty(refundAmount)
    && isRefundable
    && !alreadyRefunded
    && !string.IsNullOrEmpty(transactionKey);

Filter Description. A payment is posted as a refund only when its PaymentId, Refund Amount, and Transaction Key custom fields are all populated, IsRefundable is true, and AlreadyRefunded is not true. If IsRefundable is true but the Transaction Key is missing, the transfer raises the error "Transaction Key is required when IsRefundable is true." — search the iPaaS.com Error Logs for this message if a refund is rejected.

Description. Posts the refund Payment record to PayFabric and records the tracking custom fields.

Mapping Type	Source Field (iPaaS.com)	Destination Field (PayFabric)	Description
Dynamic Formula	Refund Amount custom field (see formula below)	Amount	Required. The refund amount, preserved from the Refund Amount custom field.
Dynamic Formula	Transaction Key custom field (see formula below)	TransactionKey_Transaction	Required. Identifies the original transaction being refunded.
Dynamic Formula	PaymentId custom field (see formula below)	Identity	Identifies the payment and checks whether it is already fully refunded.
Dynamic Formula	IsRefundable custom field (see formula below)	IsRefund	Whether the payment is refundable; `true` marks it ready for refund.
Dynamic Formula	AlreadyRefunded custom field (see formula below)	AlreadyRefunded	Whether the payment is already fully refunded; defaults to `false`.
Field	Custom.RefundPaymentIdentity	RefundPaymentId	The refund payment identity from the RefundPaymentIdentity custom field.
Field	Custom.OriginationID	TrxOriginationID_Transaction	When present, indicates the refund was already processed; stored to prevent duplicate refunds on future updates.

Amount formula:

var refundAmount = GetCustomFieldValue(CustomFields, "Refund Amount");
if (!string.IsNullOrEmpty(refundAmount)){
return refundAmount;
}
return null;

TransactionKey_Transaction formula:

var transactionKey = GetCustomFieldValue(CustomFields, "Transaction Key");
if (!string.IsNullOrEmpty(transactionKey)){
return transactionKey;
}
return null;

Identity formula:

var identity = GetCustomFieldValue(CustomFields, "PaymentId");
if (!string.IsNullOrEmpty(identity)){
return identity;
}return null;

IsRefund formula:

var IsRefund = GetCustomFieldValue(CustomFields, "IsRefundable");
if (!string.IsNullOrEmpty(IsRefund)){
return IsRefund;
}return "false";

AlreadyRefunded formula:

var alreadyRefunded = GetCustomFieldValue(CustomFields, "AlreadyRefunded");
if (!string.IsNullOrEmpty(alreadyRefunded)){
    return alreadyRefunded;
}return "false";

Error Handling

"Transaction Key is required when IsRefundable is true." — Raised by the refund payment filter when a payment is marked refundable but has no Transaction Key. Populate the Transaction Key custom field on the payment before retrying.
A refund will not post if the invoice does not exist in PayFabric or has no payment in an approved status — confirm the original invoice and its payment transferred successfully first.

Testing & Validation

Test Scenarios

Record a full refund against a synced invoice (populate the refund custom fields) and verify a Refund Payment appears on the PayFabric Receivables Payments screen and the invoice balance updates.
Record a partial refund and verify the partial amount, not the full invoice amount, is posted.
Attempt a refund with IsRefundable = true but no Transaction Key and confirm the documented error is raised.
Re-send an already-refunded payment (AlreadyRefunded = true) and confirm it is skipped.
Confirm a second refund record against the same Transaction Key overwrites rather than adding a duplicate refund.

Validation Checklist

Device ID and Device Password presets are configured.
The RefundPaymentIdentity, OriginationID, and AlreadyRefunded custom fields exist in iPaaS.com.
The original invoice exists in PayFabric with an approved payment.

Additional Notes

The parent filter requires the transaction to have at least one payment; transactions without payments are not treated as refunds.
Only one refund payment record per invoice is supported (see PayFabric Caveats).