Summary
This documentation covers the BlueSnap Invoice collections that bring what BlueSnap knows about an invoice's pay link back into iPaaS.com (transfer TO iPaaS.com). The parent collection, Update BlueSnap Invoice TO iPaaS.com, updates an existing iPaaS.com invoice (or an order placed on account) with its BlueSnap pay link and when it expires, the BlueSnap status and the amount paid. Its child collection, Add/Update BlueSnap Invoice Payment TO iPaaS.com, adds each payment made on the pay link, and each refund of it, as a payment on the same transaction.
These collections never create a transaction: an invoice number that is not linked to an iPaaS.com transaction for this subscription is skipped. They are the inbound counterpart to Add/Update BlueSnap Invoice FROM iPaaS.com (documented in iPaaS.com to BlueSnap Invoice Mapping Documentation), which makes the pay link.
An update TO iPaaS.com sends the whole transaction header, so most of the parent collection's mappings exist only to keep values BlueSnap does not own (customer, email, parent, type, number, system and every amount) exactly as they are on the transaction. The Status mapping is the one header field it changes: a paid invoice becomes Complete.
ID Format
Manual Sync ID: the BlueSnap invoice number, for example BSNAPTEST-QA-20261027121544, exactly as it appears as the iPaaS.com transaction number and as the merchant transaction id (BlueSnap's reference for the payment) BlueSnap records on its payments. Enter it on the iPaaS.com Manual Sync page of the parent collection.
Invoice external ID: iPaaS.com saves the invoice number as the external ID on a dedicated external-ID record, which is the primary match that routes each update to the right transaction. The TransactionNumber mapping keeps the same number on the transaction, which also serves as the fallback match when no external-ID record exists yet.
Payment external ID: each payment is saved with the invoice number and the BlueSnap transaction id joined by a vertical bar (invoice number|transaction id), for example BSNAPTEST-QA-20261027121544|1120203437. This link routes a later transfer of the same payment to an update instead of a new payment. A refund uses its own BlueSnap refund transaction id. Payments are transferred with their invoice and have no standalone Manual Sync ID.
Deleted Record Support
Deletion is not supported in this direction. The parent collection only updates transactions, and BlueSnap payments can't be deleted through the integration: refund a payment in BlueSnap and the refund comes back on the next poll as its own negative payment.
Cancelling an invoice is handled on the iPaaS.com side: when the invoice is cancelled in iPaaS.com, its pay link is cleared within seconds, by the integration's own write-back TO iPaaS.com when the cancellation is sent FROM iPaaS.com, and the transaction stays Cancelled.
Custom Field Support
Parent collection: the parent maps the four BlueSnap transaction custom fields shown in its table. It does not bring other BlueSnap values into transaction custom fields.
Child collection: what the payer types into your BlueSnap checkout's custom fields comes with each payment as a custom field named by its BlueSnap label. To keep a value, add a mapping from that source field to an iPaaS.com payment custom field. Values are read as BlueSnap returns them; validate the result in a staging environment before relying on it in production.
Mapping Collection Status
Status: Enabled (both collections).
Trigger: the reconciliation poll (required). Payments, refunds and expiries come back by the invoice/poll reconciliation poll, every 15 minutes. Polling is how this integration is designed to bring payments back. 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. No payments, refunds or expiries come back until this event is scheduled.
Trigger: after a pay link is made or cleared. When Add/Update BlueSnap Invoice FROM iPaaS.com makes a new pay link (or re-sends one the transaction doesn't show yet), or clears the link of a cancelled invoice, the integration runs the parent collection for that invoice a few seconds later (scope invoice/link, an internal step) to write the link onto the transaction. The invoice/link scope does not need to be turned on.
Manual Sync: enter the invoice number on the parent collection's Manual Sync page to bring the invoice's current BlueSnap state and payments into iPaaS.com now. The child collection runs as part of that transfer.
Leave invoice/payment off. The invoice/payment webhook is not used: payments come back by the reconciliation poll.
Duplicate or Conflicting Mappings
Add/Update BlueSnap Invoice FROM iPaaS.com reads the same transactions and makes their pay links. The parent collection's write-back is an ordinary update of the transaction and raises transaction/updated; the FROM collection is designed not to make a new link for an unchanged invoice, so the two do not loop.
Other integrations writing the same transactions. Any other integration that writes the same transactions (for example your invoicing system) should not overwrite the BlueSnap Pay Link, BlueSnap Status, BlueSnap Link Expires At and BlueSnap Amount Paid custom fields. BlueSnap is the source of truth for them; your invoicing system remains the source of truth for every other field. If BlueSnap Status or BlueSnap Amount Paid is edited by hand or by another system, the next reconciliation poll reads BlueSnap again and restores them, and a paid invoice never gets a new link from the edit. Don't clear BlueSnap Status: the poll only checks transactions that carry one.
One TO iPaaS.com invoice collection. Do not add a second TO iPaaS.com transaction collection for BlueSnap invoices: each matching collection writes the record.
Payments the integration did not write. The child collection only adds and updates the BlueSnap payments it links by their external ID. Payments written by another system or a user (such as an A/R payment) are left unchanged beside them.
Unmapped Field Overwrite Risk: The iPaaS.com update sends the whole transaction header. The template keeps every header field BlueSnap does not own by reading the transaction's current value with the DestinationValue function, for example DestinationValue.TaxAmount mapped to TaxAmount, so an update carries the stored value through unchanged. The header fields the template does not map (CompanyId and the transaction's created date) are sent empty, and iPaaS.com keeps their stored values. Don't rely on that for other fields: an amount field without its keep mapping can be sent as 0. Unmapped child collections on the transaction (lines, addresses, taxes, notes, tracking) are not touched. Keep the template's keep-value mappings, and to preserve a field map it with DestinationValue.<FieldName> as the template does.
Collision handling does not apply: the parent collection only updates transactions already linked to a BlueSnap invoice number.
Supported Child Collections
Parent: Update BlueSnap Invoice TO iPaaS.com
Add/Update BlueSnap Invoice Payment TO iPaaS.com: each payment made on the invoice's pay link, and each refund of it, as a payment on the transaction. Each payment is linked by the invoice number and the BlueSnap transaction id, so a later poll updates it instead of adding it again.
System Caveats
BlueSnap Caveats
Card payments only: this version supports card payments. Turn off the other payment methods on your BlueSnap checkout so payers can only pay by card.
Payments are made by the payer: payments are created only by the payer on BlueSnap's pay page and cannot be created, changed or deleted from iPaaS.com. Refund a payment in BlueSnap; the refund comes back on the next poll.
Pay links can't be revoked: BlueSnap still accepts a link that was already sent after its invoice is cancelled, or after its amount changed and a new link was made. The old link is cleared on the iPaaS.com transaction, and a payment on it is recorded so you can refund it in BlueSnap.
Paid At on a refunded sale: 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.
More than one paid link on one invoice: when two pay links of the same invoice were both paid, the payments are read from BlueSnap's transaction report, which can run an hour or more behind. Until the report lists them, the invoice is left unchanged and checked again on the next poll.
iPaaS.com Caveats
The credit card Payment Method must exist: the child collection's Method mapping writes a fixed Payment Method name, shipped as the example CRCARD. A Payment Method with that exact name MUST exist in iPaaS.com before the first payment comes back: create it, or change the Method mapping to your own credit card Payment Method. Otherwise iPaaS.com refuses the whole invoice transfer with VALD-1036 - Value (CRCARD) provided for Payment Method is not valid, nothing about the paid invoice lands (including the parent's status and amount paid), and the error appears in Dashboard / Integration Monitoring / Error Logs.
BlueSnap transaction custom fields must exist: the parent collection writes BlueSnap Pay Link, BlueSnap Status, BlueSnap Link Expires At and BlueSnap Amount Paid, and the child writes BlueSnap Transaction ID, BlueSnap Card Type, BlueSnap Card Last Four and BlueSnap Paid At. They must exist in iPaaS.com, with exactly these names, before the first transfer; they are part of the integration's setup (see the BlueSnap Installation Instructions).
Orders on account: an order placed on account keeps its A/R payment beside the card payment, so its payment lines total twice the order until the A/R payment is closed in the system that owns it. BlueSnap Status and BlueSnap Amount Paid show what the integration has read from BlueSnap for the invoice, so use them, not the payment lines, to tell whether it is paid.
Keep the keep-value mappings: removing a mapping that keeps a header field lets the update change a value BlueSnap does not own. Keep Total in particular: whether an invoice is paid in full is measured against the iPaaS.com transaction's Total.
Setup Requirements
iPaaS.com Configuration
Confirm the transaction custom fields BlueSnap Pay Link, BlueSnap Status, BlueSnap Link Expires At and BlueSnap Amount Paid, and the payment custom fields BlueSnap Transaction ID, BlueSnap Card Type, BlueSnap Card Last Four and BlueSnap Paid At, exist.
Confirm a credit card Payment Method exists whose name matches the child collection's Method mapping (CRCARD by default), or change that mapping to the name you use.
Under Dashboard / Integration Monitoring / Events, add a Webhook (Poll Request) event for this BlueSnap subscription with scope invoice/poll and a 15-minute schedule.
Leave the parent collection's mapping filter as shipped (see Mappings): it applies no conditions, because only invoices this subscription made a pay link for come back.
Review the BlueSnap Payment Status TO iPaaS.com lookup translation (see Lookup Translations).
Optionally, set the Reconciliation Days subscription setting (60 days by default, at most 365): how far back the poll looks for invoices that changed in iPaaS.com. Keep it at least as long as Pay Link Lifetime Days (and any ExpireAt mapped on the FROM collection), so an invoice is checked for as long as its link can be paid.
BlueSnap Configuration
Turn off every payment method except cards on the BlueSnap checkout used for pay links.
The BlueSnap API credential must be allowed to read transactions; the connection itself is covered in the BlueSnap Installation Instructions.
Integration Flow
The invoice is chosen. Every 15 minutes the reconciliation poll looks at the iPaaS.com transactions linked to this subscription that hold a BlueSnap Status and changed within Reconciliation Days, and compares BlueSnap's status and amount paid with the values the transaction holds. Only invoices that differ are transferred. Each run checks up to 100 invoices and continues from where the last run stopped, so a larger set is covered over several runs. A transfer also starts a few seconds after the FROM collection makes, re-sends or clears a pay link, or on Manual Sync.
The invoice number is matched to its iPaaS.com transaction through the external ID, and the pay link, total and cancelled state the transaction holds are read. An invoice number with no linked transaction is skipped and nothing is transferred.
BlueSnap is read for the payments and refunds made on the invoice's pay link (the invoice number is the merchant transaction id).
The parent collection updates the transaction with the pay link, its expiry, the BlueSnap status and the amount paid, keeping every header field BlueSnap does not own; a paid invoice's status becomes Complete.
The child collection runs in the same transfer and adds or updates each BlueSnap payment and refund on the transaction.
An invoice whose BlueSnap read fails during a poll does not stop the others: it is sent as its own transfer, where its error shows and the transfer is retried.
Prerequisite Handling
No records are transferred as prerequisites. The transaction must already exist in iPaaS.com and hold a pay link made by Add/Update BlueSnap Invoice FROM iPaaS.com, and the payments' Payment Method must already exist in iPaaS.com (see iPaaS.com Caveats).
Mappings
Update BlueSnap Invoice TO iPaaS.com (Parent — Update)
iPaaS.com data type: Transaction
Mapping Filter
// Leave as is: only invoices this subscription made a BlueSnap pay link for ever come back. return true;
Filter Description. The filter applies no conditions: every invoice that reaches this collection is processed. Only invoices this subscription made a BlueSnap pay link for ever come back, because an invoice number not linked to an iPaaS.com transaction for this subscription is skipped before the filter runs. Leave the filter as it is.
Mapping Type | Source (BlueSnap) | Destination (iPaaS.com) | Description |
Field | PayLink | BlueSnap Pay Link (custom field) | Required. The pay link to send to the customer; for a partly paid or refunded invoice whose amount changed, a link for the balance. Blank once the invoice is paid, expired or cancelled. The integration reads the link the transaction holds on each transfer. |
Field | Status | BlueSnap Status (custom field) | Required. Open, Pending (a bank payment not yet settled; v1 supports cards only), PartiallyPaid, Paid, Refunded, Expired or Cancelled. The poll only watches transactions with a BlueSnap status and compares BlueSnap against it. The reliable paid state for an order placed on account. |
Field | LinkExpiresAt | BlueSnap Link Expires At (custom field) | Recommended. When the pay link stops working, in UTC. |
Field | AmountPaid | BlueSnap Amount Paid (custom field) | Required. The amount paid through BlueSnap, net of refunds. The poll compares BlueSnap against it. |
Dynamic Formula |
| SystemId | Recommended; keep it. Keeps the system that owns the transaction (normally your invoicing system). The transaction's system can't be changed by an update. |
Dynamic Formula |
| TransactionNumber | Required. Keeps the transaction number, which is the BlueSnap invoice number and the fallback match when no external-ID record exists yet. Changing it would renumber the transaction and break that fallback. |
Dynamic Formula |
| ParentId | Recommended; keep it. Keeps the transaction's parent (for example the order an invoice was made from). |
Dynamic Formula |
| CustomerId | Recommended; keep it. Keeps the customer already on the transaction. An invoice tied only to a company is updated without it, and its company is kept. |
Dynamic Formula |
| Type | Required. Keeps the transaction type (Invoice, or Order for an order placed on account); the Status mapping reads it. |
Dynamic Formula | Status formula (below) | Status | Required. iPaaS.com refuses a transaction update without a status. See Status mapping below. |
Dynamic Formula |
| EmailAddress | Recommended; keep it. Keeps the email address already on the transaction. An invoice tied only to a company is updated without it. |
Dynamic Formula |
| DiscountAmount | Recommended; keep it. Keeps the stored discount amount. |
Dynamic Formula |
| TaxAmount | Recommended; keep it. Keeps the stored tax amount. |
Dynamic Formula |
| ShippingAmount | Recommended; keep it. Keeps the stored shipping amount. |
Dynamic Formula |
| Subtotal | Recommended; keep it. Keeps the stored subtotal. |
Dynamic Formula |
| Total | Recommended; keep it. Keeps the stored total; whether an invoice is paid in full is measured against it. |
Dynamic Formula |
| TotalQty | Recommended; keep it. Keeps the stored total quantity. |
Status mapping. A paid invoice becomes Complete, and reopens (Awaiting Payment) if a refund takes it below its total. A cancelled invoice stays Cancelled even when an old pay link is paid: the payment is recorded on it and BlueSnap Status shows Paid, so you can refund it in BlueSnap. Anything else keeps the transaction's own status: an order placed on account keeps its order status, and its paid state travels on its payments and on BlueSnap Status.
// A paid invoice becomes Complete, and reopens (Awaiting Payment) if a refund takes it below its total; an order keeps its own status (its paid state travels on the payments). // A cancelled invoice stays Cancelled even if an old link is paid: the payment is recorded and BlueSnap Status shows Paid, so you can refund it in BlueSnap. if (DestinationValue == null) return Status == "Paid" ? "Complete" : "Awaiting Payment"; if (DestinationValue.Type != "Invoice") return DestinationValue.Status; if (DestinationValue.Status == "Cancelled") return DestinationValue.Status; if (Status == "Paid") return "Complete"; if ((Status == "Open" || Status == "PartiallyPaid" || Status == "Refunded") && DestinationValue.Status == "Complete") return "Awaiting Payment"; return DestinationValue.Status;
Link delivery. Neither BlueSnap nor this integration sends the pay link to the customer. Send it, as a link or pay button, with your invoicing system's invoice email or an email or other messaging integration on iPaaS.com. Writing the link raises transaction/updated, so the delivering integration must take Transaction data FROM iPaaS.com (Transaction-type mappings and webhooks only; a Message or other data type does not see it), and its filter should send only a newly present link: later updates (paid, expired, cancelled, renewed link) raise transaction/updated again.
Add/Update BlueSnap Invoice Payment TO iPaaS.com (Child — Add/Update)
iPaaS.com data type: Transaction Payment
A refund is added 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.
Mapping Type | Source (BlueSnap) | Destination (iPaaS.com) | Description |
Static |
| Method | Required. The exact name of your credit card Payment Method in iPaaS.com; every BlueSnap payment and refund is recorded with it. Placeholder value — replace during implementation: CRCARD is an example name. Pre-install prerequisite — transfer fails without it: create a Payment Method named CRCARD with a credit card payment type, or change this value to the credit card Payment Method you already use. |
Dynamic Formula |
| Description | Recommended. BlueSnap refund or BlueSnap invoice payment, followed by the card brand and last four when BlueSnap returns them, for example "BlueSnap invoice payment (MASTERCARD ending 9903)". |
Field | Amount | Amount | Required. The payment amount; negative for a refund. |
Lookup Translation | Lookup Translation: BlueSnap Payment Status TO iPaaS.com (Status) | Status | Required. Approved becomes Completed, the only status that counts as money received. |
Field | TransactionId | BlueSnap Transaction ID (custom field) | Recommended. BlueSnap's transaction id for the payment, or for a refund its refund transaction id. Use it to find the payment in the BlueSnap Merchant Portal. |
Field | CardType | BlueSnap Card Type (custom field) | Optional. The card brand (for example VISA or MASTERCARD), when BlueSnap returns one. A refund carries the brand of the card it was refunded to. |
Field | LastFour | BlueSnap Card Last Four (custom field) | Optional. The last four digits of the card, when BlueSnap returns them. |
Field | PaidAt | BlueSnap Paid At (custom field) | Optional. When the payment was approved, as BlueSnap records it (Pacific time). On a refund it is the refund date, without a time; on a refunded sale it moves to the time of the refund. |
Lookup Translations
BlueSnap Payment Status TO iPaaS.com
BlueSnap value | iPaaS.com value |
Approved | Completed |
Pending | Pending |
Declined | Declined |
Refunded | Refunded |
You may add or change translation values to match the payment statuses used by other integrations, but keep Approved translated to the status those integrations treat as paid.
Error Handling
Errors appear in Dashboard / Integration Monitoring / Error Logs. The full list is in BlueSnap Error Messages.
Payment Method missing: VALD-1036 - Value (CRCARD) provided for Payment Method is not valid. iPaaS.com refuses the whole invoice transfer and retries it. Create the Payment Method, or change the child's Method mapping (see iPaaS.com Caveats).
Payments not yet in BlueSnap's report: BSNP-EXTN-1003 when more than one link of an invoice was paid and BlueSnap's transaction report doesn't list the payments yet. Nothing is changed on the invoice; the poll checks it again on each run, or send it again later with Manual Sync.
API credential refused or missing permission: BSNP-AUTH-1002 (credential refused) or BSNP-AUTZ-1001 (permission missing). Check the API credential and its permissions as described in the BlueSnap Installation Instructions. A refused read is treated as an error, never as "not paid", so a paid invoice is never reverted. A refused credential stops the whole poll run, so no invoice's payments come back until it is fixed.
BlueSnap busy or unreachable: BSNP-EXTN-1007 (rate limit) or BSNP-EXTN-1002 (BlueSnap couldn't complete the request). The transfer is retried and nothing is written twice.
Invoice not linked: a Manual Sync for an invoice number that is not linked to an iPaaS.com transaction for this subscription transfers nothing.
Two conditions are recorded without an error: an overpaid invoice (more than one of its pay links was paid) and a payment on a cancelled invoice. Both are recorded normally, and the warning about them is written only in the transfer's technical log. Refund what isn't owed in BlueSnap.
Testing & Validation
Link write-back: make a pay link with Add/Update BlueSnap Invoice FROM iPaaS.com and confirm the transaction shows BlueSnap Pay Link, BlueSnap Link Expires At and BlueSnap Status Open, with every other header field unchanged.
Card payment: pay the link by card and, after the next poll (or a Manual Sync with the invoice number), confirm the transaction is Complete, BlueSnap Status is Paid, BlueSnap Amount Paid equals the total, the pay link is blank, and one payment is recorded with the credit card Payment Method, the description with card brand and last four, and status Completed.
Refund: refund part of the payment in BlueSnap and confirm a negative refund payment is added, the sale keeps its full amount, BlueSnap Status is PartiallyPaid and the invoice reopens to Awaiting Payment.
No duplicates: run Manual Sync on the same invoice again and confirm the payments are updated, not added again.
Other payments kept: on an order placed on account, confirm the card payment lands beside the A/R payment, the A/R payment is unchanged and the order keeps its status.
Cancelled invoice: cancel an unpaid invoice in iPaaS.com and send the cancellation FROM iPaaS.com, and confirm within a few seconds that its pay link is cleared and the transaction stays Cancelled.
Payment Method prerequisite: confirm the Payment Method named in the Method mapping exists before the first payment; without it the transfer fails with VALD-1036.
Validation checklist: the custom fields and Payment Method exist, the invoice/poll event is scheduled every 15 minutes, and non-card payment methods are off on your BlueSnap checkout.
Additional Notes
Up to one poll of delay: a payment, refund or expiry appears in iPaaS.com on the next reconciliation poll, up to 15 minutes later. A cancelled invoice's link is cleared within seconds of the cancellation being sent FROM iPaaS.com.
Creating transactions is out of scope: these collections only update transactions that already hold a BlueSnap pay link.
Sending the pay link is out of scope: delivery to the customer belongs to another integrated system (see Link delivery).
Payments outside the pay link are out of scope: only payments made on the invoice's BlueSnap pay link are brought back, and payments are never sent FROM iPaaS.com to BlueSnap.
Related Documents
Related Mapping Documentation