Skip to main content

PayTrace Error Messages

Catalog of the errors the iPaaS.com PayTrace integration reports, with what triggers each one and what to do about it.

Overview

This article catalogs the errors subscribers can encounter with the PayTrace integration. Each error carries a stable code you can search for on this page, followed by what triggers it and what to do. Errors appear in iPaaS.com under Dashboard / Integration Monitoring / Error Logs.

iPaaS.com categorizes errors by families. You can learn more about that categorization at Understanding iPaaS.com API Error Codes.

Some resolutions refer to your Managed Integration Service Provider (MiSP): the partner who set up and manages your iPaaS.com integration.

Every message is logged in the form {code} - {message} - {link to this article}. In the messages below, words in braces are filled in when the error happens, for example {invoice number}.

Situations the integration handles without an error, such as an update that changes nothing PayTrace holds, a retried send that reuses the existing PayTrace invoice, or a paid invoice whose card payment is not yet listed, are described in PayTrace Integration Known Limitations and the PayTrace mapping documentation.

Supported Flows

  • Authentication and connection validation

  • Invoice FROM iPaaS.com

  • Invoice and payments TO iPaaS.com

  • Any flow

Authentication and connection validation

A required connection setting is missing

PAYTRACE-AUTH-1001 - These settings are required: {missing settings}. Use the username and password of a PayTrace API user (all permissions) for this merchant.

  • Description: API Username or API Password is empty. The message lists which. This fires before any call to PayTrace. (API Url has a default, https://api.paytrace.com.)

  • Resolution: Fill in the listed settings on the subscription with the API user's username and password, and save. There is no merchant id to enter: the integration reads the API user's merchant from PayTrace.

PayTrace refused the API username and password

PAYTRACE-AUTH-1002 - PayTrace refused the API Username and API Password ({HTTP status}). Check them, and that the API Url is the right PayTrace environment (https://api.paytrace.com, or https://api.sandbox.paytrace.com for a sandbox account).

PAYTRACE-AUTH-1002 - PayTrace refused the API Username and API Password for {action}. Check them, and that the API Url is the right PayTrace environment.

PAYTRACE-AUTH-1002 - PayTrace answered {HTTP status} to the token request without an access token.

PAYTRACE-AUTH-1002 - PayTrace refused this API Username and API Password in the last 30 minutes, so they were not sent again. Correct them on the subscription; the corrected values are tried at once.

  • Description: The first form: PayTrace refused the sign-in (HTTP 400, 401 or 403 to the token request). The username or password is wrong, or the API Url points at the other PayTrace environment (a sandbox API user can't sign in to production, and the reverse). The second form: a call was refused with HTTP 401 even after the integration signed in again once. The third form: PayTrace answered the sign-in without a token; an API Url with a wrong path after the host (PayTrace answers 404) gives this form. The fourth form: PayTrace refused the same API Url, API Username and API Password less than 30 minutes ago, so the integration didn't send them again. PayTrace disables a user after four consecutive failed sign-ins (see PayTrace API Response Codes).

  • Resolution: Check API Username and API Password, and that API Url is https://api.paytrace.com (or https://api.sandbox.paytrace.com), the environment the API user was created in, with nothing after the host. Fix the settings before the next transfer runs. A corrected value on the subscription is tried at once. If the fix is made only in PayTrace (for example the API user's password is reset in Users → Manage Users (Edit User in the side menu)) and the settings don't change, the integration waits until 30 minutes after the last refusal before it signs in again. Then resend the transactions that failed in the meantime: their automatic retries are used up.

The PayTrace Integrator ID is missing or refused

PAYTRACE-AUTH-1003 - The PayTrace integration is not configured: its PayTrace Integrator ID is missing. Contact iPaaS.com support; nothing on the subscription needs changing.

PAYTRACE-AUTH-1003 - PayTrace refused {action}: the integrator id is missing or not valid (error 971). This is set by iPaaS.com on the integration, not on the subscription: contact iPaaS.com support.

  • Description: PayTrace requires an Integrator ID on every call. It identifies the iPaaS.com integration, not the merchant, and iPaaS.com sets it on the integration. The first form: the integration has none. The second form: PayTrace refused the one it has (PayTrace error 971).

  • Resolution: Nothing on the subscription can fix this. Contact iPaaS.com Support at support@ipaas.com with the time of the error, or ask your MiSP to.

PayTrace refused the call: product not enabled or not permitted

PAYTRACE-AUTH-1004 - PayTrace refused {action}: {PayTrace's reason} Ask PayTrace to enable the product (Trace AR Checkout invoicing) for API access on this API user's merchant, and give the API user every permission.

  • Description: PayTrace answered HTTP 403. The most common reason is that invoicing (Trace AR Checkout) is not enabled for the merchant: PayTrace answers "This product is not enabled for your account." An API user without permission for the call is the other likely reason.

  • Resolution: Ask PayTrace to enable Trace AR Checkout for the merchant. In the PayTrace Virtual Terminal, give the API user all permissions (Users → Manage Users (Edit User in the side menu), Select All).

The API user doesn't have permission for a call

PAYTRACE-AUTH-1006 - PayTrace refused {action}: the API user doesn't have permission for it ({PayTrace's reason}). In PayTrace, give the API user every permission (Users → Manage Users → the API user → Permissions: Select All).

  • Description: PayTrace answered HTTP 401 with "Your user has insufficient permissions to process this request." The API Username and API Password are right (PayTrace issued a token), but the API user isn't allowed to make this call.

  • Resolution: In the PayTrace Virtual Terminal, open Users → Manage Users (Edit User in the side menu), select the API user and choose Select All under Permissions. Nothing on the subscription needs changing; the next transfer retries the call.

The API Url setting is not a web address

PAYTRACE-AUTH-1007 - The API Url setting is not a web address. Use https://api.paytrace.com, or https://api.sandbox.paytrace.com for a sandbox account (blank means https://api.paytrace.com).

  • Description: The API Url on the subscription can't be read as a web address (for example it contains spaces), so the integration doesn't call PayTrace. The transfer's error may read only "Unable to connect to subscription with id …"; this message is in the company's Logs at the same time.

  • Resolution: Set API Url to https://api.paytrace.com (the default) for a production account or https://api.sandbox.paytrace.com for a sandbox account. Then resync the record.

PayTrace didn't say which merchant the API user belongs to

PAYTRACE-AUTH-1005 - PayTrace didn't say which merchant the API user belongs to. Check that the API Username is a user of the merchant that sends the invoices.

  • Description: Every PayTrace invoice call names the merchant by the id PayTrace's API knows it by. The integration doesn't ask for it: it reads it from PayTrace (the API user's own record) on the first call and keeps it with the sign-in for 10 minutes. This error means PayTrace answered that request without a merchant id. The merchant number shown in the PayTrace Virtual Terminal's header can be a different number (the processor's merchant id), so it is never asked for.

  • Resolution: Check in the PayTrace Virtual Terminal that the API Username belongs to the merchant that sends the invoices (Users → Manage Users (Edit User in the side menu)), and that it has every permission. Then retry the transfer. If it persists, contact PayTrace support with the API username and the time of the error, or raise it with your MiSP.

Invoice FROM iPaaS.com

These errors stop the invoice from being sent. Nothing is sent to PayTrace and no customer is emailed until the cause is fixed and the invoice is sent again (for example by a Manual Sync with the Transaction ID).

The invoice has no invoice number

PAYTRACE-VALD-1001 - The invoice has no InvoiceNumber: map the transaction number to InvoiceNumber.

  • Description: The mapped InvoiceNumber is empty. The invoice number is what the customer sees on the PayTrace invoice and its email, and it is how the PayTrace invoice and its payments are matched back to the iPaaS.com transaction, so it is required. This also fires when an invoice with no number is cancelled.

  • Resolution: Map the transaction number to InvoiceNumber (the default template does), and make sure the invoicing system sends a transaction number.

The invoice number is longer than 50 characters

PAYTRACE-VALD-1005 - Invoice number "{invoice number}" is longer than PayTrace allows (50 characters).

  • Description: PayTrace takes an invoice number of at most 50 characters.

  • Resolution: Use a shorter invoice number. If the invoicing system's numbers are longer, map a shorter value to InvoiceNumber; it must still be unique in your own system.

The invoice number contains a character PayTrace can't use

PAYTRACE-VALD-1013 - Invoice number "{invoice number}" contains {characters}. PayTrace can't take a payment on an invoice number with &, and an invoice number with + or / can't be matched back to its transaction. Use an invoice number without &, + or /.

  • Description: The invoice number contains an ampersand (&), a plus sign (+) or a slash (/). PayTrace creates such an invoice, but its pay page cannot take a payment on it, and iPaaS.com cannot look the transaction up by that number, so payment notifications and Manual Sync by number would not find it. The integration refuses the invoice before anything is sent to PayTrace, so no unpayable invoice is emailed.

  • Resolution: Use invoice numbers without &, + or / in your invoicing system, or map a value without them to InvoiceNumber. Then send the invoice again.

The invoice has no amount to collect

PAYTRACE-VALD-1002 - Invoice {invoice number} has no amount to collect (Amount must be more than 0).

  • Description: The mapped Amount (the invoice total, in the default template) is empty, zero or negative.

  • Resolution: Check the invoice total in the invoicing system, or what the mapping sends as Amount. An invoice with nothing to pay needs no PayTrace invoice.

A template placeholder hasn't been replaced

PAYTRACE-VALD-1007 - Invoice {invoice number}: the {field} mapping still holds the template placeholder "{placeholder}". Replace it in the FROM iPaaS.com mapping collection (or remove the mapping).

  • Description: The default template Add/Update PayTrace Invoice FROM iPaaS.com ships with instructional values that start "REPLACE with your …", for example for Reply Email and From Name of the invoice email. The integration refuses to send an invoice while one of them is still in place, so an unedited template can never email a customer. It checks the Email, ReplyEmail, FromName, Message and ExpireAt mappings.

  • Resolution: In Add/Update PayTrace Invoice FROM iPaaS.com, replace the value of the mapping named in the message with your own (for example your accounts receivable mailbox for Reply Email and your company name for From Name), or remove the mapping. Then send the invoice again.

The invoice has no email to send it to

PAYTRACE-VALD-1003 - Invoice {invoice number} has no email to send it to: map the customer's email to Email, or set Send Email to false.

  • Description: Send Email is true (the default), so PayTrace is to email the invoice, but the mapped Email is empty.

  • Resolution: Make sure the transaction carries the customer's email. If your own system delivers the pay link instead, set Send Email to false: PayTrace then makes the pay link without emailing it.

An email address isn't valid

PAYTRACE-VALD-1004 - Invoice {invoice number}: "{address}" is not an email address.

PAYTRACE-VALD-1004 - Invoice {invoice number}: ReplyEmail "{address}" is not an email address.

  • Description: The first form: one of the recipients in Email is not an email address. Several recipients may be given, separated by commas, semicolons or spaces. The second form: the mapped ReplyEmail is not an email address.

  • Resolution: Correct the address named in the message in the invoicing system or in the mapping.

The PayTrace Customer Vault id is not a number

PAYTRACE-VALD-1006 - Invoice {invoice number}: PayTraceCustomerId "{value}" must be the customer's PayTrace Customer Vault id (a number).

  • Description: PayTraceCustomerId is optional. When it is mapped, it must be the numeric id of a customer profile in the PayTrace Customer Vault.

  • Resolution: Map the Customer Vault id, or remove the PayTraceCustomerId mapping. The default template doesn't map it.

The expiry date isn't usable

PAYTRACE-VALD-1008 - Invoice {invoice number}: ExpireAt "{value}" is not a date.

PAYTRACE-VALD-1008 - Invoice {invoice number}: ExpireAt {yyyy-MM-dd HH:mm} (PayTrace's clock, UTC−8) is in the past, so the pay link would never work.

  • Description: ExpireAt is optional: it sets when the pay link stops working. The mapped value is not a date (first form) or is already past (second form). PayTrace keeps its own clock at UTC−8 all year, and the integration reads and checks ExpireAt on that clock: a date alone means the end of that day on PayTrace's clock (23:59:59 UTC−8); a time with an offset (or Z) is taken as that moment; a time without one is read as PayTrace's clock. The message shows the expiry on PayTrace's clock. The check compares it with the current time, wherever the integration runs, so "end of today" is accepted until midnight UTC−8.

  • Resolution: Leave ExpireAt blank, so PayTrace uses the merchant's default expiry (14 or 30 days), or map only a date that is still in the future whenever the invoice is sent or updated. The date is checked on every update FROM iPaaS.com, so a due date that passes while the invoice is still open makes each later update fail with this error.

PayTrace already holds an invoice with this number that the integration didn't create

PAYTRACE-VALD-1012 - Invoice {invoice number}: PayTrace already holds invoice {PayTrace invoice id} with this number ({amount}, {status}) that this integration didn't create (it was made in PayTrace itself). It is left as it is and nothing was sent. Give the iPaaS.com transaction a different number, or delete the invoice in PayTrace, then update the transaction.

  • Description: The integration only reuses, replaces or deletes PayTrace invoices it created itself. An invoice made in PayTrace itself (for example in the Virtual Terminal) with the same invoice number is never changed or deleted by the integration, and a second invoice with that number isn't sent, so the customer never holds two pay links for one number. Cancelling or deleting the transaction in iPaaS.com never deletes that invoice either.

  • Resolution: Give the iPaaS.com transaction a different invoice number, or, if the PayTrace invoice isn't needed, delete it in the PayTrace Virtual Terminal. Then update the transaction (or run a Manual Sync) to send it again.

PayTrace refused the request

PAYTRACE-VALD-1010 - PayTrace refused {action}: {PayTrace's field and reason}

  • Description: PayTrace answered HTTP 400 or 422 with a reason, usually about one field of the invoice. The integration's own checks (above) catch the common cases first; this is everything else PayTrace checks.

  • Resolution: Read PayTrace's field and reason in the message, correct the invoice or its mapping, and send the invoice again. If the reason isn't clear, raise it with your MiSP with the message and the invoice number.

A mapping collection of a type PayTrace doesn't support

PAYTRACE-VALD-1011 - PayTrace mapping collections can only be Transaction (invoices) or Transaction Payment; this collection's type ({type}) isn't supported. Remove the collection or change its type.

  • Description: A mapping collection on the subscription has a type the integration doesn't move (for example Customer). Nothing is sent to PayTrace for it.

  • Resolution: Remove that collection, or recreate it from the default templates (Transaction FROM iPaaS.com for invoices; Transaction TO iPaaS.com with its Transaction Payment child for payments).

PayTrace created the invoice but returned no id or pay link

PAYTRACE-EXTN-1003 - PayTrace created invoice {invoice number} but returned no invoice id or checkout link. Check PayTrace before resending it.

  • Description: PayTrace accepted the invoice but its answer carried no invoice id or pay link, so the integration can't write them back. PayTrace may already have emailed the customer.

  • Resolution: Look for the invoice in the PayTrace Virtual Terminal. Then resync the invoice FROM iPaaS.com: when PayTrace already holds an unchanged invoice for the same number (created since the iPaaS.com transaction was, and within the subscription's Reconciliation Days, default 60), the integration reuses it and writes its pay link back without emailing the customer again.

Invoice and payments TO iPaaS.com

The pay link couldn't be written onto the invoice yet

PAYTRACE-HOOK-1001 - Invoice {invoice number} was sent through PayTrace but its pay link couldn't be written back onto the iPaaS.com transaction ({reason}). The next reconciliation poll writes it (it finds the PayTrace invoice by its number); a Manual Sync of the invoice TO iPaaS.com does it now.

  • Description: A warning, not a failure. Right after a PayTrace invoice is created, replaced or cancelled, the integration starts a TO iPaaS.com transfer of the same invoice (scope invoice/created) to write PayTrace Pay Link, PayTrace Invoice ID and PayTrace Invoice Status onto the iPaaS.com transaction. That transfer couldn't be started or reported errors. The FROM iPaaS.com transfer itself succeeded, and PayTrace has the invoice (and has emailed it, when Send Email is true). A warning without a code, "No transfer handler on this connection; invoice … was not written back", is the same situation.

  • Resolution: Nothing is required: the next reconciliation poll (within 15 minutes) finds the PayTrace invoice by its number and writes its pay link, id and status. For the link right away, run a Manual Sync of the invoice number TO iPaaS.com, which does the same. Resyncing the invoice FROM iPaaS.com also works: an unchanged invoice PayTrace already holds is reused, not emailed again. If the reason names a mapping problem, fix it in Update PayTrace Invoice TO iPaaS.com.

Too many transactions changed for one reconciliation run

PAYTRACE-BIZL-1001 - The reconciliation couldn't check every iPaaS.com transaction changed in the last {N} days: this company changed more than 100,000 of them, so payments, voids, refunds and expiries on some PayTrace invoices would be missed. Lower the Reconciliation Days setting (for example to {N/2}) so each run covers them all; nothing was reconciled in this run.

  • Description: Each reconciliation poll (invoice/poll) reads every iPaaS.com transaction the company changed within Reconciliation Days, not only PayTrace ones, 500 at a time, so it can check every invoice sent through PayTrace. When the company changed more than 100,000 transactions in that window, the run stops, reconciles nothing and reports this error, rather than checking only some invoices. {N} is the Reconciliation Days setting. It isn't retried: every later poll reports it again until the setting is lowered. Payments whose silent post arrives still come back within moments in the meantime.

  • Resolution: Lower Reconciliation Days on the subscription (the message suggests half the current value) so the window holds fewer than 100,000 changed transactions. The next poll then reconciles everything in the shorter window. An invoice that hasn't changed within the shorter window can still be read at any time with a Manual Sync of its invoice number TO iPaaS.com.

An invoice was paid by a payment method the integration doesn't read

PAYTRACE-VALD-1009 - Invoice {invoice number} was paid in PayTrace by {payment type}, a payment method this integration doesn't read (it records card payments only). Nothing was recorded on iPaaS.com and nothing was re-issued. Record the payment in your source system (or on the iPaaS.com transaction), and turn off {payment type} for invoice checkout in PayTrace.

  • Description: PayTrace reports the invoice as paid (COMPLETED) by a payment method other than a card, for example ACH (bank account). The integration records card payments only, so it can't tell how much was paid. It writes nothing to the iPaaS.com transaction: it doesn't mark the invoice Paid and doesn't re-issue it. Each reconciliation poll (every 15 minutes) raises this error again until the payment is recorded on the iPaaS.com transaction (the invoice then reads as Paid) or the transaction is cancelled.

  • Resolution: Check the payment in the PayTrace Virtual Terminal, then record it in your source system so it reaches the iPaaS.com transaction (or record it on the transaction in iPaaS.com). To stop it happening again, ask PayTrace support to turn off ACH (or the payment method named) for invoice checkout. Dismiss the earlier errors once the payment is recorded.

The payment's Payment Method is not valid

VALD-1036 - Payment Method is not valid

  • Description: an iPaaS.com error. The Method mapping of PayTrace Invoice Payment TO iPaaS.com names no Payment Method in this company; the template ships with the placeholder "REPLACE with your iPaaS.com credit card Payment Method name". Nothing is written to the transaction while it fails.

  • Resolution: replace the Method value with the exact name of your company's credit card Payment Method in iPaaS.com. The next reconciliation poll records the payment with no resync. Dismiss the earlier error.

Any flow

PayTrace has no such record

PAYTRACE-NFND-1001 - PayTrace has no record for {action} (404).

  • Description: PayTrace answered HTTP 404 to a call other than reading one invoice or its pay link (those are read as "no invoice", not as an error): creating, searching or deleting invoices, or reading transactions. For example, an invoice that was already deleted in PayTrace, or a search PayTrace doesn't recognise. (A wrong API Url path is refused earlier, at sign-in, as PAYTRACE-AUTH-1002.)

  • Resolution: Check in the PayTrace Virtual Terminal that the invoice still exists, then retry the transfer. If it persists, raise it with your MiSP.

PayTrace gave an unexpected answer

PAYTRACE-EXTN-1001 - PayTrace answered {HTTP status} {status name} to {action}: {PayTrace's reason, or the start of its answer}

  • Description: PayTrace answered with an HTTP error status the integration doesn't otherwise classify: not 401 (PAYTRACE-AUTH-1002), 403 (PAYTRACE-AUTH-1004), 404 (PAYTRACE-NFND-1001), 400 or 422 (PAYTRACE-VALD-1010), 429 (PAYTRACE-RATE-1001) or 5xx (PAYTRACE-EXTN-1002).

  • Resolution: Read PayTrace's answer in the message. Retry the transfer later; if it persists, contact PayTrace support with the time of the error, or raise it with your MiSP.

PayTrace is unavailable

PAYTRACE-EXTN-1002 - PayTrace couldn't complete {action} right now ({reason}). The transfer will be retried.

PAYTRACE-EXTN-1002 - PayTrace couldn't issue an access token right now ({reason}). The transfer will be retried. If this persists, check that the API Url setting is https://api.paytrace.com (or https://api.sandbox.paytrace.com for a sandbox account).

  • Description: PayTrace answered with a server error (5xx) or didn't answer at all ({reason} gives the status or the connection error). The second form is the sign-in; its transfer error may read only "Unable to connect to subscription with id …", with this message in the company's Logs.

  • Resolution: None: iPaaS.com retries the transfer automatically. If a transfer stays failed after PayTrace is back, resend it. If it persists for more than an hour, check PayTrace's status with PayTrace support. Payments missed in the meantime are picked up by the reconciliation poll (invoice/poll).

An iPaaS.com call the integration made failed

PAYTRACE-EXTN-1004 - iPaaS.com could not complete {action} (HTTP {status} | no response). The transfer is retried; if it keeps failing, contact iPaaS.com support with the transfer's tracking id.

  • Description: The integration calls iPaaS.com's own API as well as PayTrace's, for example to read the iPaaS.com transaction it is working on. That call failed: iPaaS.com answered with an error status (HTTP {status}) or didn't answer (no response). iPaaS.com's answer is kept in the technical log only.

  • Resolution: None at first: the transfer is retried. If it keeps failing, contact iPaaS.com Support at support@ipaas.com, or ask your MiSP to, with the message and the transfer's tracking id.

PayTrace's rate limit was reached

PAYTRACE-RATE-1001 - PayTrace rate limit reached during {action}; retrying after {seconds}s.

  • Description: PayTrace answered HTTP 429. {action} names the call, for example "creating invoice {invoice number}", or "the token request" at sign-in. At sign-in the transfer's error may read only "Unable to connect to subscription with id …", with this message in the company's Logs.

  • Resolution: None: iPaaS.com holds the transfer until the limit resets (PayTrace's Retry-After when it sends one, otherwise 60 seconds) and then retries. At sign-in the transfer is retried as a failed transfer instead: resend it if it stays failed. If this error is frequent, schedule the reconciliation poll less often (missed payments, expiries, voids and refunds then arrive within the longer interval), and check whether other systems use the same merchant's PayTrace API heavily.

A record of an unexpected kind

PAYTRACE-INTL-1001 - The PayTrace integration couldn't {read the id of / set the id of / read / create / update / delete / poll for} a record of an unexpected kind (collection type {type}). Contact iPaaS.com support with this message and the transfer's tracking id.

  • Description: An internal safeguard: the integration was handed a record of a kind it doesn't move (or, for "read the id of", no record at all). Only a defect can cause it; nothing on the subscription does. The transfer is not retried.

  • Resolution: Contact iPaaS.com Support at support@ipaas.com, or ask your MiSP to, with the message and the transfer's tracking id.

Reporting an issue

If you encounter an error not covered above, capture the iPaaS.com Subscription ID, the invoice number, the PayTrace Invoice ID (on the iPaaS.com transaction, when it has one), the PayTrace transaction id of the payment if there is one, and the iPaaS.com error log entry, and raise it with your MiSP first. For PayTrace-side problems, your MiSP can escalate to PayTrace support with the merchant id, the invoice number and the time of the error.

Related Documents

Related Articles
Did this answer your question?