The PayTrace integration sends invoices from iPaaS.com to PayTrace's invoicing (Trace AR Checkout), which emails each customer a pay link, and brings the card payments, amount paid and balance back onto the same iPaaS.com invoice. Follow the sections in order.
Before You Begin
You need the following before you start in iPaaS.com:
Invoicing enabled for API access. Ask PayTrace to enable Trace AR Checkout for the merchant for API access. Until it is enabled, every invoice is refused with PAYTRACE-AUTH-1004.
A PayTrace API user for iPaaS.com, with all permissions. Create it in PayTrace for this integration only (see Authentication Configuration). A missing permission shows as PAYTRACE-AUTH-1006.
ACH off for invoice checkout. The integration records card payments only. If the merchant's PayTrace account offers ACH (bank account) payment on invoices, ask PayTrace support to turn off ACH (bank account) payment for invoice checkout. An invoice paid by ACH cannot be recorded and reports PAYTRACE-VALD-1009 on every reconciliation run.
Trace AR settings reviewed. In the PayTrace Virtual Terminal, open Trace AR → Settings and select Save Settings after any change:
Silent Post: the integration sets its own payment-notification address on each invoice it creates, so nothing needs to be entered here for this integration; leave it empty.
Return Method: the only option is "Use a hyperlink, do NOT pass non-sensitive values".
Payment Approved Link and Payment Declined Link: optional pages on your website that the payer sees after paying; the integration does not use them.
Invoice Expiration: 14 days or 30 days, the merchant's default expiry for invoice pay links. Leaving ExpireAt unmapped uses this default.
Terms & Conditions: required by PayTrace: the link to your terms, shown on the pay page.
Require these Fields from Customer: choose whether the payer must enter an Email Address, Billing Address or CSC on the pay page.
- An invoicing system connected to iPaaS.com that sends invoices as Transactions of type Invoice with an invoice number and the customer's email, and sets Awaiting Payment when an invoice is ready to be paid; or that sends orders placed on account with an A/R payment. - A credit card Payment Method in your iPaaS.com company, for recording PayTrace payments.
No merchant id, OAuth application or redirect address is needed: the integration signs in with the API user's username and password and asks PayTrace which merchant the user belongs to.
Installation Instructions for Integration Setup
In iPaaS.com, go to Subscriptions and select Search Certified Integration Marketplace & Subscribe.
Find the PayTrace tile and open it.
Select Subscribe.
Name the subscription PayTrace - [Environment], for example PayTrace - Production or PayTrace - Sandbox.
Leave Create Default Mappings checked. It installs the four PayTrace mapping collections and their translations, which the rest of these instructions configure. Uncheck it only if you will build every mapping yourself.
On the Subscription Settings page, enter the PayTrace settings (see Authentication Configuration and Operational Configuration).
API Url: enter the PayTrace environment the API user belongs to.
Test/Sandbox: https://api.sandbox.paytrace.com
Production: https://api.paytrace.com (the default)
Review the throttle settings. They are pre-populated; the defaults suit most merchants.
API Throttle Limit: the number of calls allowed per throttle period. Default: 500. Recommended: initial setup 5, ongoing operations 500, high volume 500.
API Throttle Seconds: the length of the throttle period, in seconds. Default: 60.
API Throttle Limit (To iPaaS) and API Throttle Seconds (To iPaaS): the same limits for transfers TO iPaaS.com. Defaults: 500 and 60.
Concurrent Connections: how many transfers run at the same time. Default: 10.
Concurrent Batch Executions: how many batches run at the same time. Default: 10.
Select Apply.
Authentication Configuration
PayTrace API User
API Username
Location: the API user you create in PayTrace for iPaaS.com.
Description: identifies the merchant the integration works for; every PayTrace invoice is created for the merchant this user belongs to.
API Password
Location: the password you give that API user.
Description: signs the integration in to PayTrace. It is masked once saved and never logged.
To create the API user, sign in to the PayTrace Virtual Terminal (a sandbox account signs in at https://sandbox.paytrace.com) as a user who can manage users, then:
Go to Users → New User.
Under Type of User, select API User.
Complete the user details the page asks for, including the User Name.
Under Permissions, choose Select All, then check that the permissions are ticked.
Select Save.
Enter the username and password in the subscription settings and select Apply. Saving is the authorization: there is no separate Authorize step.
Important Notes
Use an API user only iPaaS.com uses. PayTrace disables a user after four consecutive failed sign-ins (see PayTrace API Response Codes), so a mistyped password on another system sharing the user would stop your invoices too.
After a refused sign-in (PAYTRACE-AUTH-1002), the integration does not send the same username and password again for 30 minutes, so retries do not use up the four attempts. Corrected values are tried at once. If you fix the problem only in PayTrace, wait 30 minutes from the last refusal, then resend the transactions that failed.
Environments do not mix. Sandbox credentials work only with the sandbox API Url, and production credentials only with the production API Url.
The PayTrace Integrator ID is managed by iPaaS.com. You do not enter it. If it is missing or refused, transfers report PAYTRACE-AUTH-1003: contact iPaaS.com Support.
The integration never moves money. It creates, reads and deletes invoices and reads transactions; it never charges, voids or refunds. No card number passes through it: the customer types the card on PayTrace's own pay page.
Revoking access. In PayTrace, open Users → Manage Users (Edit User in the side menu), select the API user, and reset its password or delete it. Invoices already sent keep their pay links until they are paid, expire or are deleted in PayTrace.
Operational Configuration
Reconciliation Days
Description: how far back the reconciliation poll looks. It checks the transactions changed in the last this-many days, and it bounds how far back a PayTrace invoice is looked up by its number.
Purpose: payments whose notification was missed, and voids, refunds and expiries made in PayTrace, come back only through the poll, so the window must cover how long your invoices stay open.
Example: 60 means an invoice whose transaction has not changed for more than 60 days is no longer reconciled automatically.
Recommended values: initial setup: 60. Ongoing operations: longer than your longest payment terms, up to 365. High volume: lower it if the poll reports PAYTRACE-BIZL-1001 (more than 100,000 transactions changed within the window).
Balance Settings
PayTrace closes an invoice after any payment on it, and an invoice that expired or was cancelled in PayTrace cannot be paid either. When money is still owed in one of these situations, its setting chooses Re-issue Payment (a new PayTrace invoice for the balance, emailed to the customer) or Handle Manually (nothing is sent at that moment):
Setting | Situation | Default |
After Partial Payment | The customer paid less than the total on the pay page. | 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 |
Purpose: decide, per situation, whether the customer is asked again automatically or your team follows up.
Example: with After Partial Payment set to Re-issue Payment, a customer who pays 40.00 of a 100.00 invoice receives a new PayTrace invoice for 60.00.
Note: 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. Existing subscriptions keep the values they saved. See PayTrace Connections and Settings for details.
Additional Configuration Options
Custom Fields
Create these iPaaS.com custom fields with exactly these names before enabling any flow. The default mappings write them, and the integration reads several of them back.
Custom field | On | Holds |
PayTrace Pay Link | Transaction | The invoice's pay link while it can be paid. |
PayTrace Invoice ID | Transaction | PayTrace's id for the invoice. |
PayTrace Invoice Status | Transaction | Open, PartiallyPaid, Paid, Expired or Cancelled. |
PayTrace Amount Paid | Transaction | The amount paid through PayTrace. |
PayTrace Balance | Transaction | What is still owed. |
PayTrace Transaction ID | Transaction Payment | PayTrace's transaction id. |
PayTrace Refund Of | Transaction Payment | On a refund, the transaction id of the payment it refunds. |
PayTrace Approval Code | Transaction Payment | The approval code. |
PayTrace Card Last Four | Transaction Payment | The last four digits of the card. |
PayTrace Paid At | Transaction Payment | When it was paid, in PayTrace's time. |
PayTrace Payment Message | Transaction Payment | PayTrace's approval or status message. |
Placeholder Values
Placeholder value — replace during implementation: the default mappings carry three values that start "REPLACE with your …". Replace each before enabling the flows.
FromName on Add/Update PayTrace Invoice FROM iPaaS.com: your company name, the sender name on PayTrace's email. While the placeholder remains, every invoice is refused with PAYTRACE-VALD-1007 and nothing is sent.
ReplyEmail on Add/Update PayTrace Invoice FROM iPaaS.com: your accounts receivable mailbox, the Reply-To of PayTrace's email. While the placeholder remains, every invoice is refused with PAYTRACE-VALD-1007.
Method on PayTrace Invoice Payment TO iPaaS.com: the exact name of your credit card Payment Method in iPaaS.com. Until it matches, iPaaS.com refuses every payment with VALD-1036. Once corrected, the next reconciliation poll records the payment; dismiss the earlier error.
Mapping Filter
Review the filter of Add/Update PayTrace Invoice FROM iPaaS.com before enabling the flows. By default it sends invoices in Awaiting Payment, orders placed on account (an A/R payment) in any status except Complete, and cancelled ones so their PayTrace invoice is deleted. Change Awaiting Payment and the on-account method name to match your invoicing system; keep Invoice and Cancelled as they are. Keep the mappings of Update PayTrace Invoice TO iPaaS.com, in particular its Status and keep formulas. See iPaaS.com to PayTrace Invoice Mapping Documentation for the full filter.
Payment Notifications
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. The same address also lets the integration recognise its own invoices later.
The invoice/silent_post and invoice/created options on Inbound Data Flows exist for the integration's own transfers; you do not need to turn either on. The supported way to bring payments, voids, refunds and expiries back automatically is the reconciliation poll below.
Reconciliation Poll
Under Dashboard / Integration Monitoring / Events, add an event:
Field | Value |
Subscription | this PayTrace subscription |
Scope | invoice/poll |
Schedule | every 15 minutes: the cron expression 0 0/15 * * * ? |
Active | on |
The poll catches any payment whose notification was missed and brings back voids, refunds and expiries made in PayTrace, which PayTrace never notifies. Never turn it off. After 15 minutes, check that the event's run history shows an invoice/poll run completed without an error.
Outbound Triggers
Enable these last: from that moment, every matching invoice is emailed to its customer.
transaction/created and transaction/updated, in the subscription configuration's Outbound Data Flows section: they send each invoice to PayTrace.
Optional: transaction/deleted, with Delete PayTrace Invoice FROM iPaaS.com: only if your invoicing system deletes invoices instead of cancelling them. If it deletes and re-creates transactions when it re-synchronises, leave it off: each cycle would delete the PayTrace invoice and email a new one.
The write-back after a send needs no setup: the integration starts it itself.
Sending Your Own Email
To send the invoice from your own system, set the SendEmail mapping to false: PayTrace then creates the pay link without emailing it. Include the PayTrace Pay Link custom field in your own invoice email; it arrives on the transaction a few seconds after the invoice reaches Awaiting Payment.
Post-Installation Verification
Connection Test
There is no separate connection test: the first transfer checks the settings. If the settings are refused, the transfer's error may read only "Unable to connect to subscription with id …". Find the entry with the same time and reference id in the company's Logs; it names the code (for example PAYTRACE-AUTH-1001 or PAYTRACE-AUTH-1002) and the setting to fix.
Data Sync Test
Create an Invoice transaction with a unique invoice number, a total and an email address you control, and set it to Awaiting Payment.
Within a few seconds, verify that the transaction carries PayTrace Pay Link, PayTrace Invoice ID and PayTrace Invoice Status Open, and that PayTrace emailed the invoice to your address.
Update the transaction without changing the amount or email. Verify no second email arrives.
Functionality Test
On a sandbox subscription, pay the invoice's link with one of PayTrace's published sandbox test cards. Never pay a production invoice with a test card, or a sandbox invoice with a real card.
Within moments (or after the next poll, or a Manual Sync of the invoice number on Update PayTrace Invoice TO iPaaS.com), verify a Completed payment with the PayTrace transaction id and last four digits, PayTrace Invoice Status Paid, and an invoice status of Complete.
Cancel a second test invoice. Verify PayTrace Pay Link is cleared and the old link no longer opens a pay page.
Error Messages
Errors appear in iPaaS.com under Dashboard / Integration Monitoring / Error Logs. Every code is described in PayTrace Error Messages; these are the ones most often seen during installation.
"Unable to connect to subscription with id …"
Description: the settings were refused; the reason is in the company's Logs.
Resolution: find the Logs entry with the same time and reference id, and follow the code it names.
PAYTRACE-AUTH-1001
Description: API Username or API Password is empty.
Resolution: fill them in and select Apply.
PAYTRACE-AUTH-1002
Description: PayTrace refused the API username and password: mistyped, or the API Url is the other PayTrace environment.
Resolution: check both values and the API Url before the next transfer.
PAYTRACE-AUTH-1003
Description: the PayTrace Integrator ID is missing or refused.
Resolution: contact iPaaS.com Support.
PAYTRACE-AUTH-1004, PAYTRACE-AUTH-1006
Description: 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.
PAYTRACE-AUTH-1005
Description: 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; contact PayTrace support if it persists.
PAYTRACE-AUTH-1007
Description: the API Url is not a web address.
Resolution: set it to https://api.paytrace.com, or https://api.sandbox.paytrace.com for a sandbox account.
PAYTRACE-VALD-1007
Description: a "REPLACE with your …" placeholder is still in the FROM iPaaS.com collection.
Resolution: replace FromName and ReplyEmail, or remove those mappings.
"VALD-1036 Payment Method is not valid"
Description: the payment collection's Method names no Payment Method in your company.
Resolution: replace the Method value; the next poll records the payment. Dismiss the earlier error.
PAYTRACE-VALD-1009
Description: an invoice was paid by ACH or another method that is not a card.
Resolution: record the payment in your source system, and ask PayTrace support to turn that payment method off for invoice checkout.
A payment does not appear within moments
Description: PayTrace's notification did not arrive or was not accepted.
Resolution: nothing is lost: the next reconciliation poll brings the payment, and a Manual Sync of the invoice number brings it at once.
Payments do not come back at all
Description: the invoice/poll event is not scheduled or not active.
Resolution: schedule the poll as described above.
Support and Troubleshooting
Support Portal: https://support.ipaas.com/en/
Contact Information: https://ipaas.com/contact-us/
New subscription API key: subscribers cannot generate a new subscription API key themselves. If you suspect the key has been misused, contact iPaaS.com Support to generate a new one.
PayTrace support: contact PayTrace support to enable Trace AR Checkout for API access, to turn off ACH payment for invoice checkout, or about an API user that has been disabled after failed sign-ins.
Known limitations: see PayTrace Integration Known Limitations for the integration's scope and design decisions.