Summary
ID Format
Deleted Record Support
Mapping Collection Status
Duplicate or Conflicting Mappings
Supported Child Collections
System Caveats
Setup Requirements
Integration Flow
Mappings
Error Handling
Testing and Validation
Additional Notes
Related Documents

Summary

iPaaS.com Transactions can be updated from PayTrace invoices through the Update PayTrace Invoice TO iPaaS.com mapping collection, by the integration's own write-back, PayTrace's payment notification, the reconciliation poll or Manual Sync. It writes the pay link, PayTrace's invoice id and status, the amount paid and the balance onto the transaction the invoice was sent for, and a paid invoice becomes Complete. Its child collection, PayTrace Invoice Payment TO iPaaS.com, writes each card transaction on the invoice as a Transaction Payment.

The collection never creates a transaction: only invoices this subscription sent through PayTrace come back. Because an update TO iPaaS.com replaces the whole transaction record, the template writes back the transaction's own values for the fields PayTrace does not own (see Unmapped Field Overwrite Risk).

ID Format

Manual Sync ID Format

Enter the invoice number on the Manual Sync page of Update PayTrace Invoice TO iPaaS.com, for example INV-10042. The child collection has no Manual Sync of its own: it runs with its parent.

External ID Format

Invoice: the invoice number (format {{InvoiceNumber}}, for example INV-10042). It is saved by Add/Update PayTrace Invoice FROM iPaaS.com when the invoice is first sent; this collection uses it to find the transaction to update.
Payment: the invoice number and PayTrace's transaction id, joined by "|" (format {{InvoiceNumber}}|{{TransactionId}}, for example INV-10042|123456789). A notification, a poll and a Manual Sync therefore never add the same payment twice, and a later void updates the same payment line.

Deleted Record Support

Not supported: these collections only update. They never delete or cancel a transaction or its payments.

A PayTrace invoice deleted or cancelled in PayTrace comes back with PayTrace Invoice Status Cancelled and a blank pay link. The transaction keeps its own status, and the After Cancelled Invoice setting decides whether a new PayTrace invoice is sent for what is still owed.
A transaction cancelled in iPaaS.com is handled by Add/Update PayTrace Invoice FROM iPaaS.com; this collection then writes the blank pay link and Cancelled status, and the transaction stays Cancelled.
A payment voided or refunded in PayTrace comes back as Voided, or as its own Refunded payment line. Payment lines are never deleted.

Mapping Collection Status

Status: Enabled (both collections).
Trigger Events:
Write-back after a send: started by the integration itself a few seconds after a PayTrace invoice is created, replaced or cancelled FROM iPaaS.com. Nothing needs to be enabled.
Payment notification: PayTrace's payment notification is built into each invoice: the integration puts this subscription's notification address, made from the subscription's webhook API key, on every invoice it creates. When the invoice is paid, PayTrace notifies iPaaS.com and the payment usually lands within moments. Nothing needs to be set up for this, on Inbound Data Flows or in PayTrace.
invoice/poll: the reconciliation, the supported way to bring changes back automatically. Schedule this event for the subscription; the Installation Instructions recommend every 15 minutes.
The invoice/silent_post and invoice/created options on Inbound Data Flows exist for these transfers; you do not need to turn either on. Expiries, voids and refunds come back only with the poll. Manual Sync by invoice number is always available.
PayTrace Invoice Payment TO iPaaS.com runs with every transfer of its parent and has no trigger of its own.

Duplicate or Conflicting Mappings

Collision Handling

Collision handling is automatic and is not a subscriber setting.

Never creates. An invoice number not linked to an iPaaS.com transaction for this subscription transfers nothing, whether it arrives by notification, poll or Manual Sync.
Repeats are harmless. A repeated or late notification, a poll and a Manual Sync all read PayTrace again and write the same values. Payments are matched by their external ID, so they are never added twice.
A refund is its own payment line, with a negative amount, so the original payment stays as it was.

Unmapped Field Overwrite Risk

An update TO iPaaS.com replaces the whole transaction record. The template's keep formulas write back the transaction's own CustomerId, EmailAddress, Subtotal, TaxAmount, ShippingAmount, DiscountAmount, Total and TotalQty unchanged, and its TransactionNumber and Type formulas do the same. Testing confirmed that the totals, email address, status, lines, addresses, notes, taxes and payments are unchanged after an update. Removing a keep formula is expected to clear that field every time a payment or status arrives from PayTrace. The parent link, tracking and your own Transaction custom fields have no keep formula and were not covered by testing; validate them in a staging environment before relying on them. Do not replace the Total formula with a plain mapping of Amount.

Related Collections

Add/Update PayTrace Invoice FROM iPaaS.com: sends the invoice to PayTrace. This collection writes the results back and does not change the fields that collection sends.

Supported Child Collections

Parent: Update PayTrace Invoice TO iPaaS.com (Transaction).
Child: PayTrace Invoice Payment TO iPaaS.com (Transaction Payment): writes each card transaction on the invoice as a payment line, linked by the invoice number and PayTrace transaction id.

System Caveats

iPaaS.com Caveats

Updates replace the whole record, hence the keep formulas.
The custom fields must exist. Create the Transaction custom fields PayTrace Pay Link, PayTrace Invoice ID, PayTrace Invoice Status, PayTrace Amount Paid and PayTrace Balance, and the Transaction Payment custom fields PayTrace Transaction ID, PayTrace Refund Of, PayTrace Approval Code, PayTrace Card Last Four, PayTrace Paid At and PayTrace Payment Message, with exactly these names.
The Payment Method must exist. The payment collection's Method must name a Payment Method configured in your company, or iPaaS.com refuses each payment with VALD-1036.
Declined and voided attempts are payment lines. iPaaS.com has no data type for a declined or voided card transaction, so they are Transaction Payments with a status and an amount of 0.00. Adding up every payment's amount gives the money actually moved; PayTrace Amount Paid on the transaction already holds the net amount.
No native payment date. The payment time is kept in PayTrace Paid At.
Reconciliation window. The poll checks transactions changed in the last Reconciliation Days (default 60). An invoice whose transaction has not changed in that window is no longer reconciled; raise the setting if customers pay late. A Manual Sync with the invoice number still reads any invoice whose transaction holds its PayTrace Invoice ID.
Very busy companies. Each poll reads every transaction changed within Reconciliation Days. When more than 100,000 changed in that window, the poll reconciles nothing and reports PTRC-BIZL-1001 until Reconciliation Days is lowered.

PayTrace Caveats

Payments arrive within moments; the poll catches any missed. PayTrace notifies iPaaS.com when an invoice is paid. A missed notification is caught by the next reconciliation run. Never turn the poll off.
Expiries, voids and refunds are not notified. PayTrace notifies payments only; the poll finds the rest.
An invoice closes after any payment. PayTrace closes an invoice after any payment on it, including a partial one. A closed invoice's pay link is not written back, because it cannot be paid again.
Card payments only. No full card number passes through the integration: only the last four digits, the transaction id and the approval code. An invoice PayTrace reports as paid by ACH, or by another method that is not a card, writes nothing: it is not marked paid or re-issued, and each reconciliation run reports PTRC-BIZL-1002 until the payment is recorded on the transaction or the transaction is cancelled. Ask PayTrace support to turn off ACH payment for invoice checkout.
Refunds are matched to a payment. PayTrace's refund record does not name the payment it refunds. The integration takes the latest earlier approved payment on the invoice with the same card, preferring one that covers the refund amount, and records its transaction id in PayTrace Refund Of.
Paid At is in PayTrace's own time, not UTC.
Rate limiting. When PayTrace's rate limit is reached, the transfer is rescheduled automatically and resumes when the limit resets. No action is required.

Integration-Specific Caveats

Balance handling. When money is still owed that PayTrace's invoice can no longer collect (a partial payment or refund, a full refund, a void, an expired or cancelled invoice), the subscription setting for that situation decides what happens. Re-issue Payment creates a new PayTrace invoice for the balance under the same invoice number, which PayTrace emails to the customer, and writes its pay link here. Handle Manually sends nothing at that moment. See PayTrace Connections and Settings for the six settings and their defaults.
A read can send an invoice. With Re-issue Payment on, any read of the invoice can create and email a new PayTrace invoice: a payment notification, a reconciliation poll or a Manual Sync.
An open balance invoice is not updated by a later refund. The balance settings act only once PayTrace's invoice is closed. A refund made on an earlier payment while a re-issued balance invoice is still open leaves that invoice's amount unchanged, so it asks for less than PayTrace Balance shows. After the customer pays it, the remainder is handled by the After Partial Payment setting.

Setup Requirements

PayTrace Configuration

Nothing to set up for notifications: each invoice the integration creates carries its own notification address. Ask PayTrace support to turn off ACH payment for invoice checkout.

iPaaS.com Configuration

Create the custom fields listed under iPaaS.com Caveats.
Replace the Method placeholder on PayTrace Invoice Payment TO iPaaS.com (see Mappings).
Schedule the invoice/poll event for the subscription, every 15 minutes, as described in the Installation Instructions.
The write-back after a send needs no setup.

Integration Flow

A transfer starts: after a FROM iPaaS.com send, from PayTrace's notification (invoice/silent_post), from the reconciliation poll (invoice/poll, which picks only invoices whose PayTrace status or amount paid differs from the transaction), or by Manual Sync with the invoice number.
The integration finds the iPaaS.com transaction linked to the invoice number for this subscription. When there is none, nothing is transferred.
It reads the PayTrace invoice named in PayTrace Invoice ID, or finds one it created by invoice number, and the card transactions made on it. An invoice made in PayTrace itself with the same number is never read as this one.
It works out the amount paid through PayTrace (approved payments, less refunds), the balance (the transaction's total, less PayTrace's payments and the payments your source system recorded) and the status: Paid, PartiallyPaid, Open, Expired or Cancelled. An invoice PayTrace reports paid by a method other than a card stops here with PTRC-BIZL-1002, and nothing is written.
When money is still owed and PayTrace's invoice can no longer take it, the balance setting for that situation either re-issues a PayTrace invoice for the balance or does nothing.
The parent mappings write the PayTrace fields and the status onto the transaction, keeping every other field.
The child collection writes each card transaction as a Transaction Payment, matched by its external ID; each refund is linked to the payment it refunds.

Mappings

Update PayTrace Invoice TO iPaaS.com

iPaaS.com data type: Transaction

Mapping Filter

// Leave as is: only invoices this subscription sent through PayTrace ever come back.
return true;

Filter Description. The filter lets every record through. Leave it as it is: an invoice number this subscription did not send through PayTrace transfers nothing.

Description: Writes PayTrace's view of the invoice onto the transaction it was sent for.

Mapping Type	Source Field (PayTrace)	Destination Field (iPaaS.com)	Description
Dynamic Formula	The Status formula (shown below)	Status	Required. Sets the transaction's status from PayTrace's view of the invoice (see below). Keep the mapping: removing it resets the status on every update.
Field	PayLink	PayTrace Pay Link (custom field)	Recommended. The pay link; blank once the invoice is paid, has expired or was cancelled, and while PayTrace's invoice cannot take a payment. A replaced or re-issued invoice has a new link.
Field	InvoiceId	PayTrace Invoice ID (custom field)	Recommended. PayTrace's id for the invoice. Keep it as shipped: the integration reads it back to find the PayTrace invoice.
Field	Status	PayTrace Invoice Status (custom field)	Recommended. Open, PartiallyPaid, Paid, Expired or Cancelled. Keep it as shipped: the reconciliation compares PayTrace against it.
Field	AmountPaid	PayTrace Amount Paid (custom field)	Recommended. Approved payments through PayTrace, less refunds. Keep it as shipped: the reconciliation compares against it, and a later send FROM iPaaS.com asks only for what is still owed.
Field	Balance	PayTrace Balance (custom field)	Recommended. What is still owed: the total, less PayTrace Amount Paid, less the payments your source system recorded. Nothing reads it back, so it may be removed.
Dynamic Formula	`return DestinationValue != null ? (object)DestinationValue.SystemId : SpaceportSystemId;`	SystemId	Optional. Writes back the transaction's own system. iPaaS.com does not change a transaction's system on an update, so this mapping has no effect.
Dynamic Formula	`return DestinationValue != null ? DestinationValue.TransactionNumber : InvoiceNumber;`	TransactionNumber	Required. Writes back the transaction's own number unchanged; iPaaS.com requires a transaction number on every update.
Dynamic Formula	`return DestinationValue != null ? DestinationValue.Type : "Invoice";`	Type	Required. Writes back the transaction's own type unchanged, so an order placed on account stays an order.
Dynamic Formula	`return DestinationValue != null ? DestinationValue.CustomerId : null;`	CustomerId	Recommended; do not remove it. Writes back the transaction's own customer unchanged.
Dynamic Formula	`return DestinationValue != null ? DestinationValue.EmailAddress : null;`	EmailAddress	Recommended; do not remove it. Writes back the transaction's own email address unchanged.
Dynamic Formula	`return DestinationValue != null ? DestinationValue.Subtotal : Amount;`	Subtotal	Recommended; do not remove it. Writes back the transaction's own subtotal unchanged.
Dynamic Formula	`return DestinationValue != null ? DestinationValue.TaxAmount : 0;`	TaxAmount	Recommended; do not remove it. Writes back the transaction's own tax amount unchanged.
Dynamic Formula	`return DestinationValue != null ? DestinationValue.ShippingAmount : 0;`	ShippingAmount	Recommended; do not remove it. Writes back the transaction's own shipping amount unchanged.
Dynamic Formula	`return DestinationValue != null ? DestinationValue.DiscountAmount : 0;`	DiscountAmount	Recommended; do not remove it. Writes back the transaction's own discount amount unchanged.
Dynamic Formula	`return DestinationValue != null ? DestinationValue.Total : Amount;`	Total	Recommended; do not remove it. Writes back the transaction's own total unchanged; PayTrace Amount Paid and PayTrace Balance are worked out against it. Do not replace it with a plain mapping of Amount.
Dynamic Formula	`return DestinationValue != null ? DestinationValue.TotalQty : 0;`	TotalQty	Recommended; do not remove it. Writes back the transaction's own total quantity unchanged.

In these formulas, DestinationValue is the iPaaS.com transaction as it is now. Each keep formula returns its current value; the part after ":" would apply only to a transaction that does not exist yet, which this collection never creates.

Status formula

// A paid invoice becomes Complete, and reopens (Awaiting Payment) if a void or refund takes it below its total; a cancelled transaction stays Cancelled even if PayTrace was paid (PayTrace Amount Paid shows it: refund it in PayTrace); an order keeps its own status (its paid state travels on the payments).
if (DestinationValue == null) return Status == "Paid" ? "Complete" : "Awaiting Payment";
if (DestinationValue.Status == "Cancelled") return "Cancelled";
if (DestinationValue.Type != "Invoice") return DestinationValue.Status;
if (Status == "Paid") return "Complete";
if ((Status == "Open" || Status == "PartiallyPaid") && DestinationValue.Status == "Complete") return "Awaiting Payment";
return DestinationValue.Status;

Here Status is the PayTrace invoice's status and DestinationValue.Status the transaction's own. In order:

A Cancelled transaction stays Cancelled, even when PayTrace already collected a payment. PayTrace Amount Paid shows it; refund it in PayTrace.
A transaction that is not an Invoice, such as an order placed on account, keeps its own status. Its paid state is carried by its payment lines.
A paid invoice becomes Complete.
A Complete invoice reopens to Awaiting Payment when a void or refund takes it back to Open or PartiallyPaid.
Anything else keeps the transaction's own status; an expired invoice stays Awaiting Payment.

Subscribers may change the names Complete and Awaiting Payment, together with the same names in the filter of Add/Update PayTrace Invoice FROM iPaaS.com. Keep Invoice and Cancelled as they are: the integration looks for those exact words. Try a rename on one invoice first.

Amount and Balance: in the invoice this collection reads, Amount is always the invoice total, never what is left to pay; Balance is what is still owed; AmountPaid is only what PayTrace collected. Do not map Amount to the transaction's Total.

Optional fields (not mapped by the template)

Field	What it holds
LastPaidAt	When the latest approved payment was made, as PayTrace records it.
PayTraceStatus	PayTrace's own invoice status: INITIATED, IN_PROGRESS, COMPLETED, EXPIRED or INVALID.

Map them into custom fields of your own if you want them.

PayTrace Invoice Payment TO iPaaS.com

iPaaS.com data type: Transaction Payment

This collection has no mapping filter: every card transaction on the invoice is processed.

Description: Writes each PayTrace card transaction on the invoice as a payment on the iPaaS.com transaction.

Mapping Type	Source Field (PayTrace)	Destination Field (iPaaS.com)	Description
Static	`"REPLACE with your iPaaS.com credit card Payment Method name"`	Method	Required. The iPaaS.com Payment Method PayTrace payments are recorded with. Placeholder: replace it (see below).
Field	Description	Description	Recommended; do not remove it. A readable description of what happened (examples below). With PayTrace Transaction ID, it lets the integration recognise its own payment lines when working out what is still owed.
Field	Amount	Amount	Required. The money moved: the payment amount, a negative amount for a refund, and 0.00 for a declined, voided or authorized (not captured) attempt.
Lookup	Lookup Translation: PayTrace Payment Status TO iPaaS.com	Status	Required. An approved payment becomes Completed (see the table below). Keep Completed as a status your downstream systems count as paid.
Field	TransactionId	PayTrace Transaction ID (custom field)	Recommended; do not remove it. PayTrace's transaction id, used to find the payment in PayTrace and to recognise the integration's own payment lines. If both this and Description are removed, PayTrace payments are counted a second time as payments from your source system.
Field	RefundOf	PayTrace Refund Of (custom field)	Recommended. On a refund line, the transaction id of the payment it refunds. Blank on every other line.
Field	ApprovalCode	PayTrace Approval Code (custom field)	Optional. The card network's approval code.
Field	LastFour	PayTrace Card Last Four (custom field)	Optional. The last four digits of the card used.
Field	PaidAt	PayTrace Paid At (custom field)	Optional. When the transaction happened, as PayTrace records it.
Field	Message	PayTrace Payment Message (custom field)	Optional. PayTrace's approval or status message. For a line that moved no money, it starts with what happened, for example "Voided payment of 10.00; PayTrace: APPROVAL - Approved and completed".

Placeholder value — replace during implementation: replace "REPLACE with your iPaaS.com credit card Payment Method name" with the exact name of your company's credit card Payment Method in iPaaS.com, or create a Payment Method with the name you put here. Until it matches, iPaaS.com refuses every payment with VALD-1036 and no payment is recorded.

Description examples

"PayTrace invoice payment (card ending 5439)"
"PayTrace declined attempt of 40.00 (card ending 5439)"
"PayTrace voided payment of 10.00 (card ending 5439)"
"PayTrace authorization of 20.00, not captured (card ending 5439)"
"PayTrace refund of payment 123456789 (card ending 5439)"

Do not start the description of your own source system's payment lines with the word "PayTrace": the integration treats those lines as its own.

Lookup Translation Tables

PayTrace Payment Status TO iPaaS.com:

Source Value	Destination Value	Notes
Approved	Completed	Money received.
Authorized	Authorized	Not captured; amount 0.00.
Declined	Declined	Amount 0.00.
Voided	Voided	Amount 0.00.
Refunded	Refunded	Negative amount.

Subscribers may change the iPaaS.com side to match their own status names.