Skip to main content

iPaaS.com to BlueSnap Invoice Mapping Documentation

How iPaaS.com Transaction data makes a BlueSnap Checkout pay link for an invoice or an order placed on account, and how the link is written back onto the transaction.

Summary

BlueSnap Checkout pay links can be made from iPaaS.com Transaction data through the Add/Update BlueSnap Invoice FROM iPaaS.com collection. An invoice awaiting payment in iPaaS.com, or an order placed on account (it carries an A/R payment), gets a BlueSnap pay link for its number and amount; the link is written back onto the transaction by the Update BlueSnap Invoice TO iPaaS.com collection, into the BlueSnap Pay Link, BlueSnap Link Expires At, BlueSnap Status and BlueSnap Amount Paid custom fields. An unchanged invoice keeps its link, a changed amount gets a new link, and a cancelled one has its link cleared.

Neither BlueSnap nor the integration sends the link to the customer: another integrated system (the invoicing system's email, or an email or messaging integration) must deliver it. Version 1 collects card payments only.

ID Format

Manual Sync ID.

On the iPaaS.com Manual Sync page, enter the iPaaS.com Transaction id to make or refresh that invoice's pay link, for example 173244.

External ID.

After a successful sync, iPaaS.com saves the invoice number (the iPaaS.com transaction number) as the external ID on a dedicated external-ID record for this BlueSnap subscription (iPaaS.com's link between the transaction and BlueSnap). It is your own invoice number, for example BSNAPTEST-QA-20261027121544. BlueSnap records the same number as the payment's merchant transaction id (BlueSnap's reference for the payment), so payments made on the link are matched back to the transaction by this number.

Deleted Record Support

The template ships no Delete collection, so deleting a transaction in iPaaS.com does nothing in BlueSnap, and BlueSnap pay links can't be revoked. To stop a transaction offering its link, set its status to Cancelled: no new link is made, and within seconds the integration's own write-back TO iPaaS.com clears BlueSnap Pay Link and sets BlueSnap Status to Cancelled. A link that was already sent to the customer stays payable in BlueSnap until it expires.

Custom Field Support

No custom field values are sent to BlueSnap with the pay link: the integration never sends values to the checkout fields you add in BlueSnap's Checkout Settings. What the payer types into those fields comes back with each payment, but the shipped template does not map it.

Mapping Collection Status

  • Status: Enabled. Adjust the mapping filter to your business before turning this collection on (see Mapping Filter under Mappings).

  • Trigger Events: the iPaaS.com Transaction outbound webhooks transaction/created and transaction/updated (enabled per Setup Requirements below). Whether a transfer makes a new link or keeps the current one is decided by the invoice's state, not by which webhook fired.

Duplicate or Conflicting Mappings

Companion collections.

These collections work as a set on the same transaction:

  • Update BlueSnap Invoice TO iPaaS.com: writes the pay link, its expiry, the payments and the BlueSnap status back onto the same transaction.

  • Add/Update BlueSnap Invoice Payment TO iPaaS.com: writes each BlueSnap payment onto the transaction.

The write-back is an ordinary update of the iPaaS.com transaction and raises transaction/updated. Even when that update reaches this collection again, an unchanged invoice keeps its link, so no new link is made and the two collections do not loop. iPaaS.com is the source of truth for the invoice's number, total and status; BlueSnap is the source of truth for its payments.

Unmapped fields.

This collection never updates an existing BlueSnap record: a pay link can't be changed in BlueSnap, so every new link is a new BlueSnap Checkout token, and fields left unmapped here are never cleared in BlueSnap. The write-back onto the iPaaS.com transaction is made by Update BlueSnap Invoice TO iPaaS.com, whose mappings keep every header field BlueSnap does not own; its mapping documentation covers that collection's overwrite behavior.

Important: Review the mapping filter and the companion collections' filters before enabling automatic transfers. Keep this collection's filter consistent with the filter on Update BlueSnap Invoice TO iPaaS.com, or pay links will be made for invoices whose payments never come back.

Supported Child Collections

None. This collection has no child collections.

System Caveats

BlueSnap Caveats.

  • Pay links can't be changed or revoked. A changed amount makes a new link, and a link already sent stays payable in BlueSnap even after the invoice is cancelled.

  • Invoice number rules. BlueSnap records the invoice number as the merchant transaction id: at most 50 characters, unique per merchant. The integration also refuses the characters comma, slash, backslash, question mark, hash and percent, because a payment can't be looked up by a number that contains them.

  • Link lifetime. A BlueSnap pay link lasts at most a year.

  • Accepted currencies. The currency must be one your BlueSnap account accepts; BlueSnap refuses a pay link in any other currency.

  • Card payments only. Version 1 supports card payments only. Turn off other payment methods on your BlueSnap checkout.

iPaaS.com Caveats.

  • The TO iPaaS.com collection must be in place. The link is written onto the transaction by Update BlueSnap Invoice TO iPaaS.com; without it the transaction never shows its link.

  • BlueSnap custom fields. BlueSnap Pay Link, BlueSnap Link Expires At, BlueSnap Status and BlueSnap Amount Paid must exist as transaction custom fields in iPaaS.com, with exactly these names, before the first transfer.

  • Orders on account. An order on account keeps its A/R payment beside the card payment, so its payment lines total twice the order until the A/R 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.

  • Payments come back by the poll. Payments, refunds and expiries reach iPaaS.com through the invoice/poll reconciliation poll, every 15 minutes, so a payment made on the link appears on the transaction usually by the next poll, up to 15 minutes later (a very large number of open invoices is checked over several runs).

  • Errors. Errors are shown under Dashboard / Integration Monitoring / Error Logs.

Setup Requirements

iPaaS.com Configuration.

Automatic transfers are enabled in the subscription configuration's Outbound Data Flows section. Subscribe to the iPaaS.com Transaction webhooks transaction/created and transaction/updated. No automatic transfers occur until those outbound subscriptions are enabled. Pay links can also be made on demand from the Manual Sync page using the iPaaS.com Transaction id.

For payments to come back onto the transaction, schedule the reconciliation poll: 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.

These subscription settings shape every pay link (see BlueSnap Connections and Settings):

  • Payment Success Url: where the payer lands after paying. Required: without it (and without a SuccessUrl mapping) the transfer stops with BSNP-VALD-1008 before anything is sent.

  • Payment Cancel Url: where the payer lands on Cancel. Blank: the success page.

  • Pay Link Lifetime Days: how long a link works, a whole number of days from 1 to 365. Blank: 30 days. Keep Reconciliation Days at least as long as Pay Link Lifetime Days (and any ExpireAt you map), so the reconciliation poll keeps checking an invoice for as long as its link can be paid.

  • Pay Page Url: the BlueSnap payer page links are made on. Leave it blank for BlueSnap's own page for your API Url; a Pay Page Url on any other host is refused. A link made on a different page is replaced on the next transfer.

A value the integration can't use stops every transfer; Dashboard / Integration Monitoring / Error Logs then shows only "Unable to connect to subscription". Check these settings first (see BlueSnap Connections and Settings).

BlueSnap Configuration.

  • Turn off payment methods other than cards on your BlueSnap checkout.

  • Use a currency your BlueSnap account accepts for your invoices.

Integration Flow

  1. The mapping filter selects the transaction (see Mapping Filter under Mappings). No other records are transferred first.

  2. Find the iPaaS.com transaction by its id and read the pay link, status and amount paid it already holds.

  3. When the status is Cancelled, no link is made, and the transaction's pay link is cleared within seconds, by the integration's own write-back TO iPaaS.com.

  4. Check the invoice's values (number, amount, currency, landing pages, link expiry). A value BlueSnap would refuse stops the transfer with a BSNP-VALD error before anything is sent.

  5. Ask BlueSnap for the payments already made on the invoice number. A Paid invoice, or one with a bank payment still settling (Pending), gets no new link; its payment state is written back instead.

  6. When the transaction already holds a link on the current payer page for the same number, amount and currency that is not expiring within a day, keep it. Nothing new is made.

  7. Otherwise make a new pay link in BlueSnap (for a partly paid or refunded invoice, a link for its balance) and write it back onto the transaction.

  8. A few seconds later the integration runs Update BlueSnap Invoice TO iPaaS.com for the invoice (scope invoice/link, an internal step; nothing to turn on), which writes BlueSnap Pay Link, BlueSnap Link Expires At, BlueSnap Status and BlueSnap Amount Paid onto the transaction.

The external ID is the invoice number in every case (your own invoice number, for example BSNAPTEST-QA-20261027121544).

Mappings

Add/Update BlueSnap Invoice FROM iPaaS.com

iPaaS.com data type: Transaction

Mapping Filter

// Which transactions get a BlueSnap pay link. 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 pay link is 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: As the filter's own comments say, adjust it to your business before turning this collection on: the invoice Type and Status your invoicing system uses for an unpaid invoice, and the name of your on-account payment method. The filter is checked in order, and a transaction it does not pass is skipped without an error:

  • onAccount is true when the transaction carries a payment whose Payment Method name is A/R or AR. The check ignores slashes, surrounding spaces and letter case, so A/R, AR and a/r all match, but a name such as On Account does not. Placeholder value — replace during implementation: A/R is the shipped name of the on-account Payment Method; if your system records on-account payments under a different Payment Method name, change AR in the filter to that name, without "/" and in capitals.

  • A Cancelled transaction passes when it is an Invoice or is placed on account, so its pay link is cleared.

  • An Invoice passes only while its status is Awaiting Payment.

  • Any other transaction type (for example an order) passes when it is placed on account and its status is not Complete.

All other transactions are skipped.

Description: Makes, keeps or clears the BlueSnap pay link for the transaction and queues its write-back onto the transaction.

Mapping Type

Source (iPaaS.com)

Destination (BlueSnap)

Description

Field

TransactionNumber

InvoiceNumber

Required. The invoice number: BlueSnap records it as the payment's merchant transaction id, the payer sees it on the pay page, and it is saved as the external ID. At most 50 characters, unique per merchant, without , / \ ? # or % (letters, digits, -, _ and . are safest).

Field

Total

Amount

Required. The amount to collect, more than 0. Paid in full is measured against the transaction's Total, so mapping a smaller amount leaves a paid link PartiallyPaid.

Static

USD

Currency

Optional. The 3-letter ISO 4217 currency code of the pay link (for example USD, EUR or GBP); blank makes the link in USD. Placeholder value — replace during implementation: USD is the shipped default; replace it with the currency your invoices are issued in, or with a Dynamic Formula that reads the currency your invoicing system records on the transaction (for example a transaction custom field).

Field

Id

IpaasTransactionId

Required. The iPaaS.com transaction id. A transfer does not fail without it, but the link state is unreadable on the first transfer: until the invoice is linked by its first write-back, the integration can't read the pay link, status and amount paid the transaction holds. After that it finds the transaction by its invoice number. Keep it mapped to Id.

Dynamic Formula

return Type == "Invoice" ? null : "Order " + TransactionNumber;

LineDescription

Optional. A line under the item on the pay page: "Order {number}" for an order placed on account, nothing for an invoice. Remove it or map your own (a PO number, what the invoice is for). The item itself is labelled "Invoice {number}".

Lookup Translation

Lookup Translation: BlueSnap Invoice Status FROM iPaaS.com (Status)

Status

Required. Nothing fails without it, but a cancelled invoice then never has its pay link cleared. Cancelled clears the pay link; any other status translates to blank, and a pay link is made or kept.

Optional fields not in the template: LineLabel (the item the payer sees; blank: "Invoice {number}"), ExpireAt (when the link stops working, a date in the next 365 days; blank: Pay Link Lifetime Days), SuccessUrl and CancelUrl (landing pages for this invoice; blank: the subscription settings).

Lookup Translations

BlueSnap Invoice Status FROM iPaaS.com

iPaaS.com Status

BlueSnap Status

Notes

Cancelled

Cancelled

Clears the pay link on the transaction. Keep this pair so cancelled invoices stop offering their link.

Error Handling

Errors are shown under Dashboard / Integration Monitoring / Error Logs; each one is described in BlueSnap Error Messages. The validation errors stop the transfer before anything is sent to BlueSnap.

  • BSNP-VALD-1001 - The invoice has no InvoiceNumber: map the transaction number to InvoiceNumber. The transaction has no number. Resolution: keep TransactionNumber mapped to InvoiceNumber and give the transaction a number.

  • BSNP-VALD-1002 - Invoice {invoice number} has no amount to collect (Amount must be more than 0). The amount is missing, 0 or negative (or 0 after rounding to the currency). Resolution: check the invoice total, or what the mapping sends as Amount.

  • BSNP-VALD-1003 - Invoice {invoice number}: Currency "{value}" is not a 3-letter currency code (e.g. USD). Resolution: map a 3-letter currency code to Currency, or leave it blank for USD.

  • BSNP-VALD-1004 - Invoice number "{invoice number}" is longer than BlueSnap allows (50 characters). Resolution: use an invoice number of at most 50 characters.

  • BSNP-VALD-1005 - Invoice number "{invoice number}" contains a character BlueSnap can't look a payment up by (, / \ ? # %). Map a number without them to InvoiceNumber. Resolution: use an invoice number without those characters.

  • BSNP-VALD-1006 - Invoice {invoice number}: the {mapping} mapping still holds the template placeholder "{value}". Replace it in the FROM iPaaS.com mapping collection (or remove the mapping). A mapping value still starts with REPLACE with. Resolution: replace the value the message names, or remove that mapping.

  • BSNP-VALD-1007 - Invoice {invoice number}: ExpireAt ... A mapped ExpireAt is not a date, is in the past, or is more than 365 days away. Resolution: map a future date within 365 days, or remove the mapping to use Pay Link Lifetime Days.

  • BSNP-VALD-1008 - Invoice {invoice number}: no page for the payer to land on after paying. ... No success page is set, or a mapped SuccessUrl or CancelUrl is not a web address. Resolution: set Payment Success Url (or map SuccessUrl), and correct a mapped SuccessUrl or CancelUrl that is not a web address.

  • BSNP-EXTN-1005 - BlueSnap refused the pay link for invoice {invoice number}: {reason} BlueSnap refused the pay link, for example for a currency your account doesn't accept. Resolution: correct what BlueSnap names in the message and send the invoice again.

  • BSNP-EXTN-1007 (rate limit) or BSNP-EXTN-1002 (BlueSnap couldn't complete the request): the transfer is retried and no link is made twice.

  • BSNP-AUTH-1002 (credential refused) or BSNP-AUTZ-1001 (permission missing, or BlueSnap Checkout not enabled): check the API credential as described in the BlueSnap Installation Instructions.

  • BSNP-EXTN-1001: BlueSnap gave an unexpected answer; the message quotes it.

  • BSNP-EXTN-1003 - BlueSnap holds more than one payment for invoice {invoice number}, and its transaction report doesn't list them yet ... Two links of the invoice were paid and BlueSnap's report has not caught up. Resolution: nothing changed on the invoice; send it again later.

  • No pay link on the invoice, but no error. If an invoice goes FROM iPaaS.com without an error but shows no BlueSnap Pay Link, the link couldn't be written back onto the transaction; this raises no error (see BlueSnap Integration Known Limitations). Resolution: send the invoice FROM iPaaS.com again with a Manual Sync (an unchanged link is written again), and check the BlueSnap custom fields exist with their exact names.

Testing & Validation

Test Scenarios.

  • Send an invoice awaiting payment; verify BlueSnap Pay Link, BlueSnap Link Expires At and BlueSnap Status (Open) land on the transaction and the external ID is the invoice number.

  • Pay the link on BlueSnap's hosted page with a card; verify the payer returns to the success page and the payment appears on the transaction after the next reconciliation poll.

  • Send the same invoice again unchanged; verify no new link is made and the link on the transaction is unchanged.

  • Change the invoice's amount; verify a new link for the new amount is written back.

  • Raise the total of a partly paid invoice; verify a link for its balance is written back.

  • Set an invoice's status to Cancelled; verify no new link is made and, within a few seconds, BlueSnap Pay Link is cleared and BlueSnap Status is Cancelled.

  • Send an order placed on account (with an A/R payment); verify it gets a link and keeps its own status and its A/R payment.

  • Clear Payment Success Url, or use an invoice number with a comma; verify the transfer stops with BSNP-VALD-1008 or BSNP-VALD-1005 and no link is made.

  • Before going live in production, pay one small live invoice through its link and confirm the payment lands on the transaction.

Validation Checklist.

  • The mapping filter is adjusted to your business: the unpaid-invoice Type and Status, and the on-account Payment Method name.

  • Currency is mapped to your invoices' currency.

  • Payment Success Url is set.

  • The four BlueSnap custom fields exist on transactions with their exact names.

  • Update BlueSnap Invoice TO iPaaS.com is enabled, and the invoice/poll event is scheduled every 15 minutes.

  • transaction/created and transaction/updated are subscribed under Outbound Data Flows.

  • The integration that delivers the link to the customer is in place.

Additional Notes

  • Link delivery. Another integration that delivers the link must take Transaction data FROM iPaaS.com through Transaction-type mappings and transaction/updated webhooks (Messages never see the link), and filter to a transaction whose BlueSnap Pay Link is newly present.

  • Placeholder values. The shipped template carries values to review before production use: the invoice Type and Status and the A/R on-account Payment Method name in the filter, and the static USD currency.

  • A changed label or expiry alone does not make a new link, because the customer may already have the current one. A link expiring within a day is renewed on the next update of the invoice.

  • A cancelled invoice's link stays payable in BlueSnap. At the time this documentation was written, a payment made after cancellation, and an overpayment (two links of one invoice both paid), are recorded as warnings in the transfer's technical log only.

  • No charging, refunding or voiding FROM iPaaS.com. Refunds are made in BlueSnap and come back onto the transaction by the reconciliation poll.

Related Documents

Related Mapping Documentation

Related Articles
Did this answer your question?