Skip to main content

iPaaS.com to PayTrace Invoice Mapping Documentation

How the PayTrace integration turns an iPaaS.com invoice or A/R order into a PayTrace invoice that PayTrace emails with its pay link, and replaces or deletes it when the transaction changes.

Contents

  • 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

PayTrace invoices can be transferred from iPaaS.com Transactions through the Add/Update PayTrace Invoice FROM iPaaS.com mapping collection, by outbound trigger or Manual Sync. Each iPaaS.com Transaction of type Invoice whose status is Awaiting Payment, and each order placed on account (a transaction with an A/R payment) in any status except Complete, becomes a PayTrace invoice for the amount still owed, which PayTrace emails to the customer with its pay link.

A few seconds later the Update PayTrace Invoice TO iPaaS.com collection writes the pay link, PayTrace's invoice id and its status onto the same transaction. PayTrace invoices cannot be edited, so a changed amount, recipient or partial-payment setting replaces the invoice, and a Cancelled transaction has its PayTrace invoice deleted.

ID Format

Manual Sync ID Format

Enter the iPaaS.com Transaction ID on the Manual Sync page.

External ID Format

iPaaS.com saves the invoice number as the transaction's external ID on a dedicated external-ID record (format {{InvoiceNumber}}, for example INV-10042). This link is how later transfers update the same PayTrace invoice, and how Update PayTrace Invoice TO iPaaS.com brings payments back onto the same transaction. The template maps TransactionNumber to InvoiceNumber, so the number on the PayTrace invoice is the one your customers see in iPaaS.com.

PayTrace's own id for the invoice is kept in the custom field PayTrace Invoice ID. It changes when an invoice is replaced; the invoice number stays the same.

Deleted Record Support

Cancelling is handled by this collection; deleting is handled by the optional collection Delete PayTrace Invoice FROM iPaaS.com.

  • Transaction set to Cancelled: the integration deletes the open PayTrace invoice, so its pay link stops working. PayTrace Pay Link is cleared and PayTrace Invoice Status becomes Cancelled. The transaction stays Cancelled.

  • Already Cancelled when first sent: nothing is created in PayTrace.

  • Only this integration's invoices are deleted. An invoice made in PayTrace itself with the same number is never deleted.

  • A paid PayTrace invoice is never deleted. It is left as it is and a warning is logged. PayTrace Amount Paid shows what PayTrace collected; refund the payment in PayTrace if it is not owed.

  • Transaction deleted in iPaaS.com: see Delete PayTrace Invoice FROM iPaaS.com.

Mapping Collection Status

  • Status: Enabled. Review the mapping filter before enabling the outbound triggers.

  • Trigger Events: the iPaaS.com transaction/created and transaction/updated outbound triggers, enabled in the subscription configuration's Outbound Data Flows section. No automatic transfers occur until they are enabled. Whether a transfer creates or updates the PayTrace invoice depends on whether the transaction is already linked to one, not on which trigger fired. Manual Sync is available for a one-off transfer by Transaction ID.

Duplicate or Conflicting Mappings

Collision Handling

Own invoices are recognised by their notification address. The integration recognises its own PayTrace invoices by the notification address it puts on each one, made from the subscription's webhook API key. Nothing needs to be set up for this.

Collision handling is automatic and is not a subscriber setting; the collection has no Collision Handling Method. The integration matches a PayTrace invoice to the transaction by invoice number, among the invoices it created itself within Reconciliation Days (default 60).

  • Re-sends do not email the customer twice. A live PayTrace invoice with the same amount, recipients and partial-payment setting is reused: its pay link is written back and nothing is emailed.

  • A lost answer is not sent twice. If PayTrace's answer to a create is lost, the integration looks the invoice up at once and uses it. Only when PayTrace did not make it is the transfer retried (PTRC-EXTN-1002).

  • Invoices made in PayTrace itself are left alone. When PayTrace holds an invoice with the same number that this integration did not create, nothing is sent and the transfer fails with PTRC-BIZL-1004. Give the transaction a different number, or delete that invoice in PayTrace, then update the transaction.

  • One live pay link per invoice. When an invoice is replaced, the old PayTrace invoice is deleted before the new one is created.

  • Outside the window. A transaction that lost its PayTrace Invoice ID and is re-sent after Reconciliation Days can create and email a second invoice.

Related Collections

  • Delete PayTrace Invoice FROM iPaaS.com: deletes the PayTrace invoice of a transaction deleted in iPaaS.com. Use it only when your invoicing system deletes invoices instead of cancelling them.

  • Update PayTrace Invoice TO iPaaS.com: writes PayTrace's results back onto the same transaction. Its write-back does not come back to this subscription as a FROM iPaaS.com transfer.

Important: Make sure only one system creates PayTrace invoices for your iPaaS.com transactions. Card orders can sit in Awaiting Payment while their payment settles; the filter lets an order through only when it carries an A/R payment, so keep that check.

Supported Child Collections

None. PayTrace invoices have no line items, tax lines or addresses. Payments come back through PayTrace Invoice Payment TO iPaaS.com, the child of Update PayTrace Invoice TO iPaaS.com.

System Caveats

PayTrace Caveats

  • Invoicing must be enabled. PayTrace's invoicing (Trace AR Checkout) must be enabled for the merchant's API access. Until it is, every invoice is refused with PTRC-AUTZ-1001.

  • Invoices cannot be edited. A changed amount, list of recipients or partial-payment setting replaces the invoice: the old pay link stops working and the customer receives a new email. A change to Message, From Name, Reply Email, ExpireAt, PayTraceCustomerId or SendEmail alone is not sent to an invoice PayTrace already holds. When an invoice is replaced, values that only the old invoice held are lost.

  • No line items, tax, PO or due-date fields. The optional Message can carry a short description or a PO number.

  • The invoice does not name the customer. The customer is identified by the email recipients, and by a Customer Vault id when one is mapped.

  • Duplicate numbers are allowed in PayTrace. PayTrace accepts two invoices with the same number, so invoice numbers must be unique in your own system. They can be at most 50 characters (PTRC-VALD-1005).

  • An invoice closes after any payment. PayTrace closes an invoice after any payment on it, including a partial one. Money still owed after that is handled by the balance settings (see Setup Requirements).

  • Expiry. A pay link expires on the mapped ExpireAt date, or after the merchant's PayTrace default. The next update FROM iPaaS.com of an expired invoice that still awaits payment creates and emails a new PayTrace invoice; cancel the transaction to stop that.

  • Amounts in PayTrace's email. PayTrace's invoice email shows one decimal (for example "$15.0"). The pay page shows $15.00, and the amount charged is exact.

  • Rate limiting. When PayTrace's rate limit is reached, the transfer is rescheduled automatically and resumes when the limit resets. No action is required.

iPaaS.com Caveats

  • Invoice is a Transaction type. iPaaS.com has no separate invoice data type: Transactions of type Invoice, and orders placed on account, are sent.

  • The customer email may be on the Customer record. The template's Email formula reads the linked customer's email when the transaction has none.

  • The pay link arrives in a separate transfer. iPaaS.com does not write a create's result back, so the integration starts a TO iPaaS.com transfer of the invoice itself. If that cannot start, PTRC-INTL-1002 is logged as a warning and the next reconciliation poll writes the pay link. A Manual Sync of the invoice number on Update PayTrace Invoice TO iPaaS.com writes it at once.

  • No initial load. Invoices already awaiting payment when the subscription is set up are sent when they next change, or now with a Manual Sync.

Setup Requirements

PayTrace Configuration

  • A PayTrace API user with all permissions, and Trace AR Checkout enabled for API access.

  • Ask PayTrace support to turn off ACH (bank account) payment for invoice checkout: the integration records card payments only.

iPaaS.com Configuration

  • Settings: API Url, API Username and API Password. Optional: Reconciliation Days and the six balance settings below.

  • Custom fields: create the Transaction custom fields PayTrace Pay Link, PayTrace Invoice ID, PayTrace Invoice Status, PayTrace Amount Paid and PayTrace Balance, with exactly these names.

  • Placeholders: replace FromName and ReplyEmail (see Mappings).

  • Filter: review it (see Mappings).

  • Outbound triggers: enable transaction/created and transaction/updated under Outbound Data Flows. Do this last: from that moment, every matching invoice is emailed to its customer.

  • Write-back and payments: set up Update PayTrace Invoice TO iPaaS.com and schedule the invoice/poll event, as described in the Installation Instructions.

Balance Settings

PayTrace closes an invoice once any payment is made on it, and an invoice that expired or was cancelled in PayTrace cannot be paid either. When money is still owed on such an invoice, one setting per situation decides what happens:

Setting

Situation

Default

After Partial Payment

The customer changed the amount on the pay page and paid less than the total.

Re-issue Payment

After Partial Refund

Part of a payment was refunded in PayTrace.

Handle Manually

After Full Refund

The whole payment was refunded in PayTrace.

Handle Manually

After Voided Payment

The payment was voided in PayTrace.

Handle Manually

After Cancelled Invoice

The PayTrace invoice was cancelled or deleted in PayTrace while the transaction still awaits payment.

Handle Manually

After Expired Invoice

The PayTrace invoice expired unpaid.

Handle Manually

  • Re-issue Payment: a new PayTrace invoice for the balance is created under the same invoice number, to the same recipients, and PayTrace emails it when the earlier one was emailed. Its pay link goes onto the transaction.

  • Handle Manually: nothing is sent at that moment. PayTrace Amount Paid and PayTrace Balance show where the invoice stands. For an expired invoice, or one cancelled or deleted in PayTrace, the next update FROM iPaaS.com while it still awaits payment creates and emails a new PayTrace invoice. After a partial payment, refund or void, an update sends nothing.

Integration Flow

  1. An invoice is created, updated or cancelled in iPaaS.com and passes the mapping filter, or a subscriber runs a Manual Sync with the Transaction ID.

  2. The integration reads the transaction's PayTrace Invoice ID and PayTrace Amount Paid, and finds the PayTrace invoice that belongs to it: first by PayTrace Invoice ID, then, when that invoice is no longer open, by invoice number among the invoices this integration created within Reconciliation Days.

  3. Cancelled: the open PayTrace invoice is deleted and its pay link cleared. A paid one is left alone with a warning. When there is none, nothing happens.

  4. What is still owed: the total, less PayTrace Amount Paid, less the payments your source system recorded on the transaction. When nothing is owed, nothing is sent, and any open PayTrace invoice for the transaction is deleted so the customer cannot pay twice.

  5. The invoice is checked: an invoice number (PTRC-VALD-1001) of at most 50 characters (PTRC-VALD-1005) and without &, + or / (PTRC-VALD-1009); an amount above 0 (PTRC-VALD-1002); no "REPLACE with your …" placeholder (PTRC-VALD-1007); an email when SendEmail is true (PTRC-VALD-1003), every address well formed (PTRC-VALD-1004); PayTraceCustomerId, if mapped, a number (PTRC-VALD-1006); ExpireAt, if mapped, a future date on PayTrace's clock (PTRC-VALD-1008). Nothing is sent when a check fails.

  6. A PayTrace invoice exists: paid → nothing changes; open and unchanged → nothing is sent; open and changed → the old invoice is deleted and a new one created and emailed; expired, or cancelled or deleted in PayTrace → a new one is created and emailed.

  7. No PayTrace invoice yet: an invoice with the same number made in PayTrace itself stops the transfer (PTRC-BIZL-1004). Otherwise the PayTrace invoice is created, and PayTrace emails it when SendEmail is true.

  8. After a PayTrace invoice is created, replaced or cancelled, the integration starts the TO iPaaS.com write-back. Update PayTrace Invoice TO iPaaS.com writes the pay link (or an empty one), PayTrace Invoice ID, PayTrace Invoice Status, amount paid and balance onto the transaction, usually within seconds.

Mappings

Add/Update PayTrace Invoice FROM iPaaS.com

iPaaS.com data type: Transaction

Mapping Filter

// Which transactions become PayTrace invoices. Adjust to your business before turning this collection on:
// - Invoices: the Type and Status your invoicing system uses for an unpaid invoice (default: Type "Invoice", Status "Awaiting Payment").
// - Orders placed on account: a transaction with a payment whose Method is your A/R / on-account payment method
//   (default matches "A/R" or "AR"; change "AR" below to your method's name, without "/" and in capitals).
// - Cancelled ones are sent too, so their PayTrace invoice is deleted and its pay link cleared.
var onAccount = Payments != null && Payments.Any(p => p.Method != null && p.Method.Replace("/", "").Trim().ToUpper() == "AR");
if (Status == "Cancelled") return Type == "Invoice" || onAccount;
if (Type == "Invoice") return Status == "Awaiting Payment";
return onAccount && Status != "Complete";

Filter Description. The filter sends three kinds of transaction:

  • Transactions of type Invoice whose status is Awaiting Payment.

  • Orders placed on account: any transaction with a payment whose Method is A/R (compared without the "/" and ignoring case, so A/R, AR and a/r all match), in any status except Complete. Their own order status is left alone.

  • Invoices and orders placed on account whose status is Cancelled, so that their PayTrace invoice is deleted and the pay link cleared.

Invoices in other statuses (for example drafts) and orders without an A/R payment are skipped; card orders must never be invoiced. Subscribers may change Awaiting Payment (together with the same name in the Status formula of Update PayTrace Invoice TO iPaaS.com) and "AR" (your on-account method's name, without "/", in capitals). Keep Invoice and Cancelled as they are: the integration looks for those exact words.

Description: Sends each invoice awaiting payment, and each order placed on account, to PayTrace as a PayTrace invoice that PayTrace emails to the customer.

Mapping Type

Source Field (iPaaS.com)

Destination Field (PayTrace)

Description

Field

TransactionNumber

InvoiceNumber

Required. The invoice number shown on the PayTrace invoice and pay page, and saved as the transaction's external ID. At most 50 characters (PTRC-VALD-1005), without &, + or / (PTRC-VALD-1009); must be unique in your own system.

Field

Total

Amount

Required. The invoice total; must be more than 0 (PTRC-VALD-1002). The integration asks only for what is still owed (see Integration Flow). Keep it mapped to Total, never to a balance, or payments would be subtracted twice.

Dynamic Formula

return !string.IsNullOrWhiteSpace(EmailAddress) ? EmailAddress : await GetCustomerEmailAsync(CustomerId);

Email

Required while SendEmail is true. The transaction's email address, or the linked customer's when the transaction has none. Several addresses may be separated by commas, semicolons or spaces.

Static

"true"

SendEmail

Optional. true has PayTrace email the invoice with its pay link. Set it to false to create only the pay link and send it from your own system. Unmapped or blank means true.

Static

"REPLACE with your company name"

FromName

Recommended. The sender name on PayTrace's invoice email. Placeholder: replace it (see below).

Static

"REPLACE with your accounts receivable email address"

ReplyEmail

Recommended. The Reply-To of PayTrace's invoice email; must be a well-formed address (PTRC-VALD-1004). Placeholder: replace it (see below).

Field

Id

IpaasTransactionId

Recommended. The iPaaS.com transaction id, used to read the transaction's current PayTrace values. Without it, the transaction is found by invoice number instead, which is slower. Keep it as shipped.

Lookup

Lookup Translation: PayTrace Invoice Status FROM iPaaS.com

Status

Recommended. Cancelled deletes the PayTrace invoice and clears its pay link; any other status translates to blank and the invoice is sent. Without it, cancelling a transaction would leave its PayTrace invoice open.

Placeholder values — replace during implementation:

  • FromName: replace "REPLACE with your company name" with your company name, or remove the mapping to use PayTrace's default sender name.

  • ReplyEmail: replace "REPLACE with your accounts receivable email address" with your accounts receivable mailbox, or remove the mapping to send without a Reply-To.

While either placeholder remains, every transfer fails with PTRC-VALD-1007 and nothing is sent, so an unedited template never emails a customer.

Lookup Translation Tables

PayTrace Invoice Status FROM iPaaS.com:

Source Value

Destination Value

Notes

Cancelled

Cancelled

Deletes the PayTrace invoice. Other statuses are not translated and arrive blank.

Do not add a second cancelled status (for example Void) to the translation: the filter, the reconciliation and the Status formula of Update PayTrace Invoice TO iPaaS.com look for the exact word Cancelled.

Optional fields (not mapped by the template)

Field

What it changes

Message

A message in the invoice email, for example what the invoice is for, or a PO number.

ExpireAt

The date the pay link stops working, on PayTrace's own clock (UTC−8 all year). A date alone is the end of that day at UTC−8; a time with an offset or Z is taken as that moment. Blank uses the merchant's PayTrace default. It is checked on every update and must be in the future (PTRC-VALD-1008), so do not map a due date that can pass while the invoice is open. A re-issued balance invoice takes the merchant's default.

AllowPartialPayment

true lets the payer change the amount on the pay page. Default false. A partial payment leaves a balance that the After Partial Payment setting handles.

PayTraceCustomerId

The customer's PayTrace Customer Vault id, a number (PTRC-VALD-1006 otherwise).

The table's other fields (InvoiceId, PayLink, PayTraceStatus, AmountPaid, Balance, LastPaidAt) are filled by PayTrace and come back TO iPaaS.com; mapping them FROM iPaaS.com has no effect.

Error Handling

Errors appear in iPaaS.com Dashboard / Integration Monitoring / Error Logs. Full descriptions are in PayTrace Error Messages.

  • PTRC-VALD-1001: The invoice has no invoice number. Resolution: keep TransactionNumber mapped to InvoiceNumber, and make sure the source system sends one.

  • PTRC-VALD-1002: The amount is empty, zero or negative. Resolution: check the invoice total, or what is mapped to Amount.

  • PTRC-VALD-1003: SendEmail is true but there is no email. Resolution: send the customer's email on the transaction, or set SendEmail to false.

  • PTRC-VALD-1004: An email or the ReplyEmail is not a well-formed address. Resolution: correct the address named in the message.

  • PTRC-VALD-1005: The invoice number is longer than 50 characters. Resolution: use a shorter invoice number.

  • PTRC-VALD-1009: The invoice number contains &, + or /. PayTrace cannot take a payment on such a number, and iPaaS.com cannot look it up. Resolution: use an invoice number without those characters.

  • PTRC-VALD-1006: PayTraceCustomerId is not a number. Resolution: map the Customer Vault id, or remove the mapping.

  • PTRC-VALD-1007: A "REPLACE with your …" placeholder is still in this collection. Resolution: replace it, or remove that mapping. Nothing is sent until then.

  • PTRC-VALD-1008: ExpireAt is not a date, or is in the past on PayTrace's clock. Resolution: leave it blank, or map only a date that is always in the future.

  • PTRC-EXTN-1006: PayTrace refused the invoice; its reason is in the message. Resolution: correct the field PayTrace names and send it again.

  • PTRC-BIZL-1004: PayTrace already holds an invoice with this number that the integration did not create. Resolution: give the transaction a different number, or delete that invoice in PayTrace, then update the transaction.

  • PTRC-EXTN-1003: PayTrace created the invoice but returned no id or pay link. Resolution: check the PayTrace Virtual Terminal, then resync the invoice; the existing invoice is reused, not emailed again.

  • PTRC-INTL-1002 (warning): The pay link could not be written onto the transaction straight away. Resolution: nothing is required; the next reconciliation poll writes it. For it at once, run a Manual Sync of the invoice number on Update PayTrace Invoice TO iPaaS.com.

  • PTRC-AUTH-1001, PTRC-AUTH-1002, PTRC-AUTH-1005: A required setting is empty, PayTrace refused the API username and password, or the API Url is not a web address. Resolution: check the settings. PayTrace disables a user after four consecutive failed sign-ins (see PayTrace API Response Codes), so after a refusal the same username and password are not sent again for 30 minutes; a corrected value is tried at once.

  • PTRC-AUTH-1003: The PayTrace Integrator ID is missing or refused. Resolution: contact iPaaS.com Support.

  • PTRC-AUTZ-1001, PTRC-AUTZ-1002: Invoicing is not enabled for API access, or the API user lacks a permission. Resolution: ask PayTrace to enable Trace AR Checkout for API access, and give the API user all permissions.

  • PTRC-AUTH-1004: PayTrace did not say which merchant the API user belongs to. Resolution: check that the API user belongs to the merchant that sends the invoices.

  • PTRC-EXTN-1002, PTRC-EXTN-1005: PayTrace was unavailable, or its rate limit was reached. Resolution: nothing; the transfer is rescheduled automatically.

  • PTRC-EXTN-1001, PTRC-NFND-1001: PayTrace gave an unexpected answer, or no record. Resolution: read PayTrace's answer in the message, and check the invoice in the PayTrace Virtual Terminal.

Testing and Validation

Test Scenarios

  1. Create an Invoice transaction with status Pending. Verify nothing happens.

  2. Set it to Awaiting Payment. Verify PayTrace emails the invoice from your From Name, and that within a few seconds the transaction carries PayTrace Pay Link, PayTrace Invoice ID and PayTrace Invoice Status Open.

  3. Re-send the same transaction, or run a Manual Sync. Verify nothing new is created and no email is sent.

  4. Change the invoice total. Verify the old pay link stops working, a new email arrives with a new pay link, and PayTrace Invoice ID and PayTrace Pay Link change.

  5. Set the transaction to Cancelled. Verify PayTrace Pay Link is cleared, PayTrace Invoice Status is Cancelled, the status stays Cancelled, and the old link no longer opens a pay page.

  6. Create a transaction that is already Cancelled. Verify nothing is created in PayTrace.

  7. Create an Order in Awaiting Payment with a card payment and no A/R payment. Verify it gets no PayTrace invoice. Create an Order in Pending with an A/R payment. Verify it gets one, and keeps its status and its A/R payment after the write-back.

  8. Before replacing FromName and ReplyEmail, send an invoice. Verify PTRC-VALD-1007 and that no email is sent.

  9. Send an invoice with a 51-character invoice number, and one whose number contains &. Verify PTRC-VALD-1005 and PTRC-VALD-1009 and no PayTrace invoice.

  10. Set SendEmail to false and send an invoice. Verify no email is sent and PayTrace Pay Link still arrives on the transaction.

Validation Checklist

  • Your source system sends invoices as Type Invoice with unique invoice numbers of at most 50 characters and the customer's email, and sets Awaiting Payment when they are ready to be paid; or it sends orders placed on account with an A/R payment.

  • FromName and ReplyEmail hold your own values, or are removed.

  • The filter's invoice status and on-account method name match your source system.

  • The Status mapping and its translation are in place.

  • The Transaction custom fields exist with exactly the names above.

  • The outbound triggers are enabled, Update PayTrace Invoice TO iPaaS.com is set up and the invoice/poll event is scheduled.

Additional Notes

  • The total comes from iPaaS.com. The iPaaS.com transaction is the source of truth: the amount paid, balance and paid status that come back are worked out against its total.

  • A payment recorded in your source system re-sends the invoice. A deposit, cheque or other payment recorded on the transaction changes what is still owed, so the open PayTrace invoice is replaced: the old pay link stops working and PayTrace emails the customer a new invoice for the new amount.

  • Only what is still owed is asked for. Payments your source system recorded count when their status is Completed, Paid, Captured or Settled; Refunded lines are taken back off. Pending, Authorized, Declined and Voided lines (such as an on-account A/R line) are not counted. Do not start the description of your own payment lines with the word "PayTrace": the integration treats those lines as its own.

  • Sending your own email. With SendEmail false, PayTrace only creates the pay link. Map the PayTrace Pay Link custom field into your invoicing system's own invoice email.

  • Revoking a link. Cancel the transaction in iPaaS.com: the PayTrace invoice is deleted and the pay link stops working.

  • An invoice paid outside PayTrace keeps its pay link. When a customer pays by cheque or bank transfer and the invoice is marked Complete in your invoicing system, the filter does not send it, so the emailed link still works. Cancel the invoice first, or delete the PayTrace invoice in PayTrace. A card payment made on the old link still comes back as a payment, so it can be refunded.

  • Out of scope. No values are written to custom fields in PayTrace; ACH (bank) payments are not supported; invoice line items, tax and addresses are not sent.

Related Documents

Related Mapping Documentation

Related Articles
Did this answer your question?