The iPaaS.com BlueSnap integration makes a BlueSnap Checkout pay link for each invoice (or order placed on account) sent FROM iPaaS.com, writes the link back onto the iPaaS.com transaction, and brings the card payments, refunds and expiries made on that link back TO iPaaS.com. This article lists the known limitations of the integration. They are inherent to the current design of the integration and the capabilities of the BlueSnap platform, and they apply to all subscribers at the time this documentation was written.

At the time this documentation was written, the integration is built and tested for card payments made on the pay link. BlueSnap Checkout can also offer other payment methods on the same page (BlueSnap: BlueSnap Checkout); those are outside the scope of this version.

What this means for you: turn off every payment method except cards on the BlueSnap Checkout used for pay links before you send any link to a customer, so payers can pay only by card. If your business needs bank or wallet payments on invoices, submit a feature request through your iPaaS.com partner channel describing the payment methods you need; input like this informs future releases.

At the time this documentation was written, payments, refunds and link expiries come back TO iPaaS.com through the integration's reconciliation poll, which runs on a 15-minute schedule. Polling is how this integration is designed to bring payments back; it does not use BlueSnap's instant payment notifications. Each run checks up to 100 invoices with BlueSnap and continues from where the last run stopped, so with many open invoices each one is checked less often (with 1,000 open invoices, about every 2½ hours). When an invoice cannot be read from BlueSnap, the other invoices are still reconciled and that invoice's error is shown on its own transfer, where it can be retried. When BlueSnap's rate limit is reached, the run stops at that invoice and the next run continues from there; BlueSnap does not publish fixed call limits and answers with HTTP 429 or 503 when an account exceeds its thresholds (BlueSnap: Error Handling Overview). A refused API credential (BSNP-AUTH-1002) stops the whole run, because no invoice can be read.

What this means for you: under Dashboard / Integration Monitoring / Events, add an event of type Webhook (Poll Request) for this BlueSnap subscription with scope invoice/poll and a 15-minute schedule, and keep it on: no payments, refunds or expiries come back until it is scheduled. Leave the invoice/payment webhook off. Expect a payment to appear on the invoice up to 15 minutes after it is made (longer with a very large number of open invoices). To bring one invoice up to date at once, run a Manual Sync TO iPaaS.com with its invoice number.

At the time this documentation was written, the poll checks only the invoices this subscription made a pay link for whose iPaaS.com transaction changed within the last Reconciliation Days (60 by default, at most 365); making or renewing a pay link counts as a change. To find them, each run scans up to 5,000 of the company's transactions changed in that window, from every integration; a larger set is swept over several runs, and a warning is written to the transfer's technical log. A payment, a refund made in BlueSnap, or a payment on a cancelled invoice's old link made after the invoice has gone longer than Reconciliation Days without changing in iPaaS.com is not picked up by the poll, and nothing is logged. Pay Link Lifetime Days (30 by default) and a mapped expiry date can each be set up to 365 days, independently of Reconciliation Days.

What this means for you: keep Reconciliation Days at least as long as Pay Link Lifetime Days and any expiry date your mapping sets, so an invoice is checked for as long as its link can be paid, and long enough to catch the refunds you expect to make. An invoice outside the window can be brought up to date at any time with a Manual Sync TO iPaaS.com using its invoice number. In a very busy company, a shorter window makes each sweep quicker.

At the time this documentation was written, the integration only makes the pay link and saves it on the iPaaS.com transaction in the custom field BlueSnap Pay Link. Neither BlueSnap nor the integration emails or messages the customer about the invoice or its payment. Writing the link onto the transaction is an ordinary update of the iPaaS.com transaction, so it raises the transaction/updated webhook; later updates (paid, expired, cancelled, renewed link) raise transaction/updated again.

What this means for you: before going live, choose another integrated system to deliver the link, for example your invoicing system's own invoice email with BlueSnap Pay Link mapped into it, or an email or other messaging integration on iPaaS.com. That integration must take Transaction data FROM iPaaS.com through Transaction-type mappings and the transaction/updated webhook (a Message or other data type does not see the link), and its filter should send only a transaction whose BlueSnap Pay Link is newly present, so the customer is not messaged again on every later update. A customer who is not sent the link cannot pay it.

At the time this documentation was written, a BlueSnap pay link cannot be changed or switched off: BlueSnap's pay link parameters set only how long a link lasts, up to 8,760 hours (one year), and offer no way to end a link early (BlueSnap: Secure payment parameters). The integration therefore works as follows:

What this means for you: keep Pay Link Lifetime Days as short as your payment terms allow, or map ExpireAt to the invoice's due date, so a replaced or cancelled invoice's old link stops being payable sooner. When an old link is paid, the payment is recorded so you can see it and refund it in BlueSnap (see the next section).

At the time this documentation was written, when a customer pays a cancelled invoice's old link, or pays both an old and a new link of the same invoice, every payment is recorded on the invoice and the transfer succeeds. The warning about it (BSNP-BIZL-1002 for a paid cancelled invoice, BSNP-BIZL-1003 for an overpaid invoice) is written only to the transfer's technical log, which is not kept for webhook- and poll-driven transfers, and it does not appear in Dashboard / Integration Monitoring / Error Logs. A paid cancelled invoice stays Cancelled, with BlueSnap Status Paid (or PartiallyPaid) and a BlueSnap Amount Paid. An overpaid invoice is Complete, and its BlueSnap Amount Paid is more than its total.

What this means for you: do not rely on the warning. BlueSnap Status and BlueSnap Amount Paid show what the integration has read from BlueSnap: check for these invoices regularly with a filter or report on those fields: status Cancelled with a BlueSnap Amount Paid, or a BlueSnap Amount Paid greater than the invoice total. Refund in BlueSnap whatever isn't owed.

In the same way, when a pay link is made (or, for a cancelled invoice, cleared) but writing it back onto the iPaaS.com transaction fails, the transfer FROM iPaaS.com still succeeds. The warning (BSNP-INTL-1003) is written only to the transfer's technical log. The invoice then shows no (or an outdated) BlueSnap Pay Link or BlueSnap Status, or a cancelled invoice still shows its link.

What this means for you: if an invoice sent FROM iPaaS.com shows no current BlueSnap Pay Link, or a cancelled invoice still shows one, send it FROM iPaaS.com again with a Manual Sync: an unchanged link is written again. Check that the BlueSnap transaction custom fields exist with their exact names (see BlueSnap Installation Instructions).

At the time this documentation was written, when more than one pay link of the same invoice has been paid, the integration reads the payments from BlueSnap's Transaction Detail report, whose data is delayed by approximately one hour (BlueSnap: Get Report Data). Until the report lists every payment, the invoice is left unchanged: the poll skips it without an error and checks it again on each run, and a Manual Sync TO iPaaS.com shows BSNP-EXTN-1003.

What this means for you: no action is needed; the payments are written once BlueSnap's report lists them, usually within about an hour. In BlueSnap's Merchant Portal you will see two payments on one invoice number; if together they are more than the invoice total, see the previous section and refund in BlueSnap whatever isn't owed. If BSNP-EXTN-1003 still appears the next day, contact your MiSP.

At the time this documentation was written, the integration makes pay links and reads the payments made on them. It never charges a card, refunds, voids, or runs subscriptions or recurring payments, and it never sends a payment FROM iPaaS.com to BlueSnap. A refund made in BlueSnap comes back on the next poll as its own payment with a negative amount, while the original sale keeps its full amount, so the payments on the invoice net to what was actually collected. A refund that takes a paid invoice below its total reopens it to Awaiting Payment.

What this means for you: make every refund in BlueSnap's Merchant Portal. Make it while the invoice is still within Reconciliation Days (see section 3), or bring it back with a Manual Sync TO iPaaS.com afterward.

At the time this documentation was written, an order placed on account keeps its A/R payment beside the BlueSnap card payment, and the integration does not close or change payments it did not write. Until the A/R payment is closed in the system that owns it, the order's payment lines total twice the order (for example, a 20.00 order shows an A/R payment of 20.00 and a card payment of 20.00). The order keeps its own status.

What this means for you: use BlueSnap Status and BlueSnap Amount Paid to see what the integration has read from BlueSnap for the order, and close the A/R payment in the system that owns it. Make sure anything downstream that sums payment lines does not count such an order as paid twice.

At the time this documentation was written, whether an invoice is Paid (and becomes Complete) is measured against the iPaaS.com transaction's Total, not against the amount the pay link was made for.

What this means for you: keep Amount on Add/Update BlueSnap Invoice FROM iPaaS.com mapped to the transaction Total (the default), and keep the Total mapping on Update BlueSnap Invoice TO iPaaS.com. If Amount is mapped to anything else, such as a balance field, a link paid in full shows PartiallyPaid and the invoice never becomes Complete.

At the time this documentation was written, BlueSnap Paid At on a payment is the approval time as BlueSnap records it, as the integration reads it from BlueSnap, not converted to UTC (BlueSnap's Transaction Detail report labels its times PST: Get Report Data). Once a sale is refunded, its BlueSnap Paid At moves to the time of the refund, so the sale's original approval time is no longer shown. A refund's own BlueSnap Paid At is its date, without a time.

What this means for you: do not use BlueSnap Paid At as the original payment time of a refunded sale. Use BlueSnap Transaction ID to look the payment up in BlueSnap's Merchant Portal when you need its full history.

At the time this documentation was written, the invoice number is the key both systems share: BlueSnap records it as the payment's merchant transaction id, and payments are matched back to the transaction by it. It must be unique for your BlueSnap merchant account, at most 50 characters (BSNP-VALD-1004), and must not contain a comma, slash, backslash, question mark, hash or percent sign (BSNP-VALD-1005), because a payment can't be looked up by a number that contains them.

What this means for you: make sure your invoicing system's invoice numbers follow these rules. Letters, digits, hyphens, underscores and periods are safest.

At the time this documentation was written, the payer sees one item for the full amount, labelled "Invoice {number}" unless you map LineLabel; the invoice's own lines are not shown. The integration sends no payer details with the link, so the payer types their name and email on BlueSnap's page. The integration also never sends values to the checkout fields you add in BlueSnap's Checkout Settings. What the payer types into those fields, and the name and email they enter, come back with each payment, but the shipped template does not map them.

What this means for you: map LineLabel and LineDescription on Add/Update BlueSnap Invoice FROM iPaaS.com if you want the payer to see more (for example a PO number). Your invoicing system's own invoice remains the detailed document. To keep a checkout field value, or the payer's PayerName or PayerEmail, map it to an iPaaS.com payment custom field on Add/Update BlueSnap Invoice Payment TO iPaaS.com, and validate the result in a staging environment before relying on it in production.

At the time this documentation was written, only payments made on the pay links this subscription made come back to iPaaS.com, not every BlueSnap sale. A subscription works with the one BlueSnap merchant account its API credentials belong to; the integration reads the merchant id from BlueSnap when it connects.

What this means for you: for several BlueSnap merchant accounts, add one BlueSnap subscription per merchant and give each subscription's FROM iPaaS.com filter only its own invoices, with no overlap, so each invoice gets exactly one pay link.

At the time this documentation was written, BlueSnap accepts API calls only from the addresses in Authorized IPs on the API Settings page. The list belongs to your BlueSnap account's API settings as a whole: secondary API credentials have the same authorized IP addresses as the primary credentials. BlueSnap allows up to 15 addresses or a subnet, and once one address is added the list can never be emptied; BlueSnap advises against Disable IP Checking unless you cannot provide a static IP address (BlueSnap: How to get your BlueSnap API credentials). BlueSnap refuses calls from an address that is not on the list; the connection is refused, and Dashboard / Integration Monitoring / Error Logs shows iPaaS.com's "Unable to connect to subscription" for the transfer (see section 17).

What this means for you: add both iPaaS.com outbound addresses, 20.98.221.25 and 69.61.66.130, to Authorized IPs in the BlueSnap Merchant Portal (Settings > API Settings), and add only addresses you intend to keep, since they count toward the account's limit. Do not select Disable IP Checking on a production account.

At the time this documentation was written, when BlueSnap locks the account of the primary API credentials, all secondary API credentials are locked too, and after the primary is unlocked each secondary must be unlocked manually; BlueSnap directs merchants to BlueSnap Merchant Support for help unlocking (BlueSnap: How to get your BlueSnap API credentials). While the credential is locked, BlueSnap refuses the integration's calls: the connection is refused, Dashboard / Integration Monitoring / Error Logs shows "Unable to connect to subscription", nothing is transferred and no payments come back.

What this means for you: there is no fix inside iPaaS.com: contact BlueSnap Merchant Support to unlock the credential. Use API credentials dedicated to iPaaS.com, and do not retry a refused password repeatedly.

At the time this documentation was written, when the integration refuses to connect because a setting can't be used (for example BSNP-VALD-1010 for a number of days outside 1 to 365, a URL that is not a web address, or a Pay Page Url that is not BlueSnap's Checkout page), or because a required setting is blank or the API Url is not an https address, or because BlueSnap refuses the API credentials when the integration connects (for example, a wrong password or an address missing from Authorized IPs), Dashboard / Integration Monitoring / Error Logs shows only iPaaS.com's own message: "Unable to process transfer. Reason: Unable to connect to subscription with id {subscription id}". The integration's coded reason is not shown, and every transfer for the subscription stops until the cause is fixed.

What this means for you: when you see "Unable to connect to subscription", check each subscription setting against BlueSnap Connections and Settings (or clear an optional setting to use its default), then check the API credentials, and retry the failed transfers.

At the time this documentation was written, the integration moves one kind of data: the iPaaS.com Transaction (an invoice, or an order placed on account) FROM iPaaS.com, and its BlueSnap status and payments (Transaction Payment) TO iPaaS.com. It transfers no customer, product or other data, and it creates no customer record in BlueSnap. It never creates a transaction in iPaaS.com: it only updates transactions it made a pay link for. A mapping collection for another data type stops with BSNP-BIZL-1001.

What this means for you: keep customers, products and invoices in your invoicing system and its own integration. Remove or turn off any BlueSnap mapping collection for another data type.

At the time this documentation was written, bulk initialization is not supported (see BlueSnap Connections and Settings). The integration makes a pay link when an invoice is created or changed in iPaaS.com after the subscription and its outbound webhooks are set up; it does not go back over invoices that were already awaiting payment.

What this means for you: to give an existing unpaid invoice a pay link, change it in your invoicing system, or send it with a Manual Sync FROM iPaaS.com using its iPaaS.com Transaction id.

At the time this documentation was written, the template ships no Delete collection, so deleting a transaction in iPaaS.com does nothing in BlueSnap. BlueSnap payments cannot be created, changed or deleted from iPaaS.com.

What this means for you: to stop an invoice offering its link, set its status to Cancelled and send it FROM iPaaS.com: its link is cleared on the transaction (an already-sent link stays payable until it expires; see section 5). To reverse a payment, refund it in BlueSnap.

At the time this documentation was written, the integration was tested end to end on a BlueSnap sandbox account. Production pay links open BlueSnap's production Checkout page, https://pay.bluesnap.com/checkout.

What this means for you: before sending pay links to your customers on a production account, pay one small live invoice through its pay link and confirm the payment comes back onto the invoice in iPaaS.com. Refund it in BlueSnap afterward if needed.

At the time this documentation was written, the overwrite behavior depends on the direction:

What this means for you: keep the template's keep-value mappings on Update BlueSnap Invoice TO iPaaS.com, especially Total; removing one lets the update change a value BlueSnap does not own. To preserve any other header field, map it with DestinationValue.<FieldName> as the template does. Do not add a second TO iPaaS.com transaction collection for BlueSnap invoices, since each matching collection writes the record. Make sure other integrations that write the same transactions (for example your invoicing system) do not overwrite the four BlueSnap custom fields, and never clear BlueSnap Status: the poll checks only transactions that carry one.

The shipped templates carry these values, which each subscriber reviews and replaces during implementation. Each one is also called out in the mapping documentation.

Defaults in Add/Update BlueSnap Invoice FROM iPaaS.com

Defaults in Add/Update BlueSnap Invoice Payment TO iPaaS.com

This article documents 22 known limitations of the BlueSnap integration, plus the placeholder values to replace before go-live. For the detailed behavior of each collection, see the BlueSnap mapping collection descriptions and mapping documentation.