The BlueSnap integration makes a BlueSnap Checkout pay link for each invoice FROM iPaaS.com, writes the link back onto the iPaaS.com invoice, and brings card payments, refunds and expiries back TO iPaaS.com by a reconciliation poll every 15 minutes. Follow the sections in order.
Before You Begin
You need the following before you start in iPaaS.com:
BlueSnap API credentials. These are not the username and password you use to sign in to the BlueSnap Merchant Portal (see Authentication Configuration). Use the primary API credentials.
iPaaS.com's outbound addresses on BlueSnap's Authorized IPs. BlueSnap only accepts API calls from the addresses listed there. Add both 20.98.221.25 and 69.61.66.130 (see Authentication Configuration).
BlueSnap Checkout on your BlueSnap account. The integration makes BlueSnap Checkout (hosted payment page) pay links. By default a BlueSnap Checkout link expires after two hours, and a longer lifetime requires a special privilege on your account (BlueSnap: Hosted Pages). This integration asks for 30 days by default (Pay Link Lifetime Days). Ask BlueSnap Merchant Support to confirm that BlueSnap Checkout and the custom link lifetime are enabled for your account before you start.
Card payments only on your BlueSnap Checkout. This version of the integration supports card payments. In the BlueSnap Merchant Portal, go to BlueSnap Checkout > Payment Methods and select Hide beside every method other than cards (BlueSnap: Enabling Payment Methods).
An invoicing system connected to iPaaS.com that sends invoices as Transactions of type Invoice with an invoice number and a total, and sets Awaiting Payment when an invoice is ready to be paid; or that sends orders placed on account, which carry an A/R payment.
A credit card Payment Method in your iPaaS.com company (Dashboard / Data Management / Payment Methods), for recording BlueSnap payments (see Placeholder Values).
A way to send the pay link to your customer. Neither BlueSnap nor this integration sends the link: you set up delivery in another system (see Delivering the Pay Link). Confirm before you install that your invoicing system's integration, or an email or messaging integration on iPaaS.com, can take Transaction data FROM iPaaS.com and carry the BlueSnap Pay Link custom field.
No merchant id, OAuth application or redirect address is needed: the integration signs in with the API credentials on every call and reads your BlueSnap merchant id from BlueSnap.
Installation Instructions for Integration Setup
In iPaaS.com, go to Subscriptions and select Search Certified Integration Marketplace & Subscribe.
Select the BlueSnap integration tile.
Select Subscribe.
Enter a unique name for the subscription and select a version.
Format: [Product Name] - [Environment/Purpose]
Example: BlueSnap - Production, or BlueSnap - Sandbox
Leave Create Default Mappings checked (recommended). It installs the three BlueSnap mapping collections and their translations, which the rest of these instructions configure. Uncheck it only if you will build every mapping yourself.
On the Subscription Settings page
Enter the API Url, the BlueSnap environment your API credentials belong to.
Test/Sandbox: https://sandbox.bluesnap.com
Production: https://ws.bluesnap.com (the default)
Enter the API Username and API Password (see Authentication Configuration).
Enter the Payment Success Url, the page on your website the payer lands on after paying, for example https://www.example.com/thank-you. Every pay link needs one: leave it blank only if your FROM iPaaS.com mapping supplies a success page for every invoice.
Review the optional settings Payment Cancel Url, Pay Link Lifetime Days, Reconciliation Days and Pay Page Url (see Operational Configuration). Blank uses each one's default.
Review the throttle settings. They are pre-populated with the defaults below; reduce them if you see rate limit errors. For details, see Subscription Configuration – Edit.
API Throttle Limit (default 500): the most calls the integration makes to BlueSnap in each throttle window.
API Throttle Seconds (default 60): the length of that window, in seconds.
API Throttle Limit (To iPaaS) (default 500) and API Throttle Seconds (To iPaaS) (default 60): the same limit for calls back to iPaaS.com.
Concurrent Connections (default 10): the most simultaneous connections.
Concurrent Batch Executions (default 10): the most batches processed at once.
Select Apply to save the settings. Saving is the authorization: there is no separate Authorize step.
Authentication Configuration
BlueSnap API Credentials
API Username: the API User Key shown under API Credentials on the BlueSnap Merchant Portal's Settings > API Settings page. It identifies your BlueSnap account to the integration on every call.
API Password: the API password you entered when you requested the API credentials on the same page. It signs the integration in to BlueSnap, and is masked once saved.
To get the API credentials and authorize iPaaS.com's addresses (BlueSnap: How to get your BlueSnap API credentials):
Sign in to the BlueSnap Merchant Portal for the environment you will connect (sandbox or production).
Go to Settings > API Settings.
Under API Credentials, enter an API password and select Request API credentials. BlueSnap shows the new key under API User Key. If your account already has API credentials that another system uses, ask whoever manages that system for them rather than changing the password.
Under Authorized IPs, add 20.98.221.25 and 69.61.66.130, keep any addresses already listed for your other software, and save.
Enter the API User Key as API Username and the password as API Password in the subscription settings, and select Apply.
Important Notes
Use the primary API credentials. The integration reads BlueSnap's Transaction Detail report, retrieves transactions and creates BlueSnap Checkout pay links. BlueSnap's secondary credentials can have at most the primary credentials' permissions, and a credential without the permission a call needs is refused with BSNP-AUTZ-1001. If you use a secondary credential, grant it at least Reporting and Retrieve Transactions, and contact BlueSnap Merchant Support for any further permission it needs.
Authorized IPs apply to the whole account. BlueSnap's secondary credentials have the same authorized addresses as the primary credentials. BlueSnap allows up to 15 addresses or a subnet, and you must always keep at least one address on the list, so add only addresses you intend to keep. Do not select Disable IP Checking on a production account: BlueSnap advises against it unless you cannot provide a static IP address. Without both iPaaS.com addresses, BlueSnap refuses the integration's calls, and Error Logs show "Unable to connect to subscription" (or BSNP-AUTH-1002).
Environments do not mix. Sandbox credentials work only with https://sandbox.bluesnap.com, and production credentials only with https://ws.bluesnap.com (BlueSnap: Sandbox & Production Environments).
Locked credentials. When the primary API credentials' account is locked, BlueSnap locks every secondary credential too; contact BlueSnap Merchant Support to unlock them.
Changing credentials. To rotate the API password, update it in BlueSnap's API Settings, then enter the new value in API Password in iPaaS.com and select Apply.
Revoking access. Change or remove the API credentials iPaaS.com uses in BlueSnap's API Settings. Pay links already sent stay payable until they expire.
Operational Configuration
Payment Success Url and Payment Cancel Url
Description: the pages the payer lands on after paying, or after selecting Cancel on the BlueSnap pay page. Each must be a web address (https:// or http://). A blank Payment Cancel Url uses the Payment Success Url.
Purpose: return the payer to your own website after the payment.
Note: with no success page from the setting or the mapping, the invoice is refused with BSNP-VALD-1008, even when your BlueSnap Checkout Settings have a success page. A value that is not a web address stops the connection with BSNP-VALD-1010.
Pay Link Lifetime Days
Description: how many days a new pay link can be paid, when the invoice does not set its own expiry date. A whole number from 1 to 365; blank uses 30.
Purpose: limit how long a link stays payable. BlueSnap cannot revoke a link once it is sent, so a shorter lifetime also limits how long a replaced or cancelled invoice's old link can still be paid.
Example: 30 means a link made today stops working in 30 days. A link expiring within a day is renewed on the invoice's next update FROM iPaaS.com.
Recommended values: initial setup: 2 while you test (see Post-Installation Verification). Ongoing operations: your payment terms plus a few days' grace.
Reconciliation Days
Description: how far back, in days, the reconciliation poll looks for invoices to check. The poll checks the invoices whose iPaaS.com transaction changed within this window; making or renewing a pay link counts as a change. A whole number from 1 to 365; blank uses 60.
Purpose: paid, refunded and cancelled invoices stay watched until their last change is older than the window, so a late refund or a payment on a cancelled invoice still comes back within it.
Example: 60 means an invoice whose transaction has not changed for more than 60 days is no longer reconciled automatically; a Manual Sync still brings it up to date.
Recommended values: keep it longer than Pay Link Lifetime Days and than any expiry date your mapping sets, so an invoice is checked for as long as its link can be paid.
Pay Page Url
Description: the BlueSnap page a pay link opens.
Default Value: blank (recommended): BlueSnap's own Checkout page for the API Url's environment, https://pay.bluesnap.com/checkout for production or https://sandpay.bluesnap.com/checkout for sandbox.
Range/Format: when set, an https address on BlueSnap's Checkout host for that environment. Any other host stops the connection with BSNP-VALD-1010.
When changes take effect. A changed Payment Success Url, Payment Cancel Url or Pay Link Lifetime Days applies to the next pay link made; links already sent keep the pages and expiry they were made with. A changed Reconciliation Days applies from the next poll. See BlueSnap Connections and Settings for every setting.
Additional Configuration Options
Custom Fields
Create Default Mappings adds these iPaaS.com custom fields to your company with the default mappings. The mappings write them, and the integration reads several of them back, so each must exist with exactly the name shown before the first transfer. After the subscription is created, confirm that all eight are in your company's custom fields. If any is missing, contact your MiSP or iPaaS.com Support before enabling the flows.
Name | Module | Holds |
BlueSnap Pay Link | Transaction | The pay link to send to the customer while it can be paid. |
BlueSnap Link Expires At | Transaction | When the pay link stops working, in UTC. |
BlueSnap Status | Transaction | The invoice's BlueSnap status, for example Open, PartiallyPaid or Paid. |
BlueSnap Amount Paid | Transaction | How much has been paid through BlueSnap, net of refunds. |
BlueSnap Transaction ID | Transaction Payment | BlueSnap's transaction id, which finds the payment in the Merchant Portal. |
BlueSnap Card Type | Transaction Payment | The card brand. |
BlueSnap Card Last Four | Transaction Payment | The last four digits of the card. |
BlueSnap Paid At | Transaction Payment | When the payment was approved, as BlueSnap records it. |
Placeholder Values
Review these values in the default mappings before enabling the flows.
Placeholder value — replace during implementation: the Method mapping on Add/Update BlueSnap Invoice Payment TO iPaaS.com writes the Payment Method name CRCARD. A Payment Method with that exact name must exist in your iPaaS.com company before the first payment comes back: create it under Dashboard / Data Management / Payment Methods, or change the Method mapping to the name of 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, and nothing about the paid invoice lands.
Currency on Add/Update BlueSnap Invoice FROM iPaaS.com: the template maps the static value USD. If you invoice in another currency, replace it with your invoices' currency, a 3-letter code your BlueSnap account accepts.
Mapping Filter
Review the filter of Add/Update BlueSnap Invoice FROM iPaaS.com before enabling the flows; it decides which transactions get a pay link. As shipped, it passes a transaction of type Invoice with status Awaiting Payment, an order placed on account (a payment whose Payment Method name is A/R or AR) whose status is not Complete, and a Cancelled invoice or order on account, so its pay link is cleared. The shipped filter has no test condition: adjust it to your business.
If your invoicing system uses a different type or status for an unpaid invoice, change those values in the filter.
Placeholder value — replace during implementation: if your system records on-account payments under a Payment Method name other than A/R, change AR in the filter to that name, without the slash and in capitals.
Leave the Cancelled condition as it is.
See iPaaS.com to BlueSnap Invoice Mapping Documentation for the full filter. Leave the filter of Update BlueSnap Invoice TO iPaaS.com as shipped: only invoices this subscription made a pay link for ever come back.
Keep the TO iPaaS.com mappings. An update TO iPaaS.com sends the whole transaction header, so most mappings of Update BlueSnap Invoice TO iPaaS.com exist to keep values BlueSnap does not own. Keep every mapping marked Required, and keep Total in particular: paid in full is measured against it. Do not add a second TO iPaaS.com collection for transactions: each matching collection writes the record.
Orders placed on account. An order on account gets a pay link and keeps its own status. Its A/R payment stays 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.
Reconciliation Poll
Payments, refunds and expiries come back TO iPaaS.com by the reconciliation poll, which is how this integration is designed to work. No payment comes back until the poll is scheduled. Under Dashboard / Integration Monitoring / Events, add an event:
Field | Value |
Name | a name you will recognize, for example BlueSnap Payment Poll |
Event Type | Webhook (Poll Request) |
Description | what the event is for, for example "BlueSnap payments, refunds and expiries" |
Then, under Event Rules, select Add for each rule:
Rule name | Expression |
SystemId | this BlueSnap subscription |
Scope | invoice/poll |
Interval | the custom expression 0 0/15 * * * ? (every 15 minutes, on the quarter hour) |
The Interval list has no 15-minute preset, so enter the expression above as a custom value rather than choosing a preset such as Every hour: an hourly poll brings payments back up to an hour late.
Never turn the event off. After 15 minutes, check that the event has run and that no BlueSnap error appears under Dashboard / Integration Monitoring / Error Logs.
Leave the invoice/payment webhook off: payments come back by the poll, and turning it on only logs BSNP-EXTN-1006. The invoice/link scope needs nothing: the integration starts that transfer itself to write the pay link onto the invoice a few seconds after it is made.
Outbound Webhooks
Enable these last. In the subscription configuration's Outbound Data Flows section, subscribe to the iPaaS.com Transaction webhooks transaction/created and transaction/updated. They send each invoice FROM iPaaS.com, so the integration makes, keeps, renews or clears its pay link. No pay links are made until they are enabled.
Invoices that already exist when you install get a pay link only when they next change, or when you send them with a Manual Sync on Add/Update BlueSnap Invoice FROM iPaaS.com using the iPaaS.com Transaction id.
Delivering the Pay Link
Neither BlueSnap nor this integration sends the pay link to your customer: the integration only saves it on the iPaaS.com invoice, in BlueSnap Pay Link. A customer who is not sent the link cannot pay. Set up delivery in another system, such as your invoicing system's invoice email or an email or messaging integration on iPaaS.com:
Writing the link onto the invoice is an ordinary update of the iPaaS.com transaction and raises transaction/updated. The delivering integration must take Transaction data FROM iPaaS.com, through a Transaction-type mapping collection and the transaction/updated webhook; a Message or another data type never sees the link.
Map BlueSnap Pay Link into the message, for example as a "Pay now" link or button.
Filter the delivering collection to a transaction whose BlueSnap Pay Link is newly present. Later polls (paid, expired, cancelled or renewed link) raise transaction/updated again, so without that filter the customer is sent the same link repeatedly.
A changed amount makes a new pay link, written back onto the invoice: send the customer the new link. BlueSnap cannot revoke a link, so an earlier link stays payable until it expires.
Post-Installation Verification
Connection Test
Each transfer first checks the settings and the API credentials by reading today's BlueSnap Transaction Detail report, so the first transfer is the connection test.
Run the Data Sync Test's first transfer (step 3 below).
Under Dashboard / Integration Monitoring / Error Logs, confirm there is no "Unable to connect to subscription" entry for this subscription.
If there is one, check each setting against Operational Configuration, then the API credentials and Authorized IPs, and send the invoice again.
Data Sync Test
A pay link cannot be switched off, so a test link stays payable until it expires. Before you test:
Set Pay Link Lifetime Days to 2, so the test link expires two days later. (A link expiring within a day is replaced on every update, so 1 would make a new link at step 5.) Set it back afterwards.
Test before the delivery integration is enabled, or use a test customer whose email address is your own.
In your invoicing system (or in iPaaS.com), create an invoice with a unique invoice number that is clearly a test, for example TEST-0001, and a small total, and set it to Awaiting Payment.
Within a few seconds, verify that the transaction carries a BlueSnap Pay Link, BlueSnap Link Expires At, and BlueSnap Status Open.
Update the transaction without changing its amount. Verify the BlueSnap Pay Link stays the same.
Cancel the test invoice. Verify that its BlueSnap Pay Link is cleared within seconds.
Functionality Test
On a sandbox subscription, open a test invoice's pay link and pay it with one of BlueSnap's published Test Card Numbers. Never pay a production link with a test card, or a sandbox link with a real card.
After the next poll (up to 15 minutes), or a Manual Sync of the invoice number on Update BlueSnap Invoice TO iPaaS.com, verify a Completed payment on the invoice with the BlueSnap Transaction ID, BlueSnap Card Type and BlueSnap Card Last Four, BlueSnap Status Paid, and an invoice status of Complete.
Before going live, pay one small live invoice through its pay link on your production subscription and confirm the payment comes back onto the invoice in iPaaS.com before sending pay links to your customers.
Error Messages
Errors appear in iPaaS.com under Dashboard / Integration Monitoring / Error Logs. Every code is described in BlueSnap Error Messages; these are the ones most often seen during installation.
"Unable to connect to subscription": A setting stopped the connection (BSNP-AUTH-1001, BSNP-VALD-1009 or BSNP-VALD-1010), or BlueSnap refused the connection check. Resolution: Check each setting against Operational Configuration, then the API credentials and Authorized IPs, and retry the failed transfers.
BSNP-AUTH-1001: API Username or API Password is blank. (In Error Logs this appears as "Unable to connect to subscription".) Resolution: Enter both and select Apply.
BSNP-AUTH-1002: BlueSnap refused the API credentials: the Merchant Portal sign-in was entered instead, a value is mistyped, the API Url is the other environment, or the call came from an address that is not on Authorized IPs. When BlueSnap refuses the connection check, Error Logs can show "Unable to connect to subscription" instead. Resolution: Re-enter the API credentials from Settings > API Settings, check the API Url, and check that both iPaaS.com addresses are on Authorized IPs. If every value is right, contact BlueSnap Merchant Support to check the state of the credentials.
BSNP-VALD-1009: The API Url is not an https address. (In Error Logs this appears as "Unable to connect to subscription".) Resolution: Set it to https://ws.bluesnap.com, or https://sandbox.bluesnap.com for a sandbox account.
BSNP-AUTZ-1001: The API credentials lack a permission, or BlueSnap Checkout is not enabled for the account. Resolution: Use the primary API credentials, or ask BlueSnap Merchant Support to enable BlueSnap Checkout or the permission.
BSNP-EXTN-1004: BlueSnap answered the connection check without naming the merchant. Resolution: Check that the API credentials have the Reporting permission; contact BlueSnap Merchant Support if it continues.
BSNP-VALD-1010: An optional setting cannot be used: days outside 1 to 365, a URL that is not a web address, or a Pay Page Url that is not on BlueSnap's Checkout host. (In Error Logs this appears as "Unable to connect to subscription".) Resolution: Correct the setting, or clear it to use its default.
BSNP-VALD-1006: A mapping on Add/Update BlueSnap Invoice FROM iPaaS.com still holds a value that starts with REPLACE with. Resolution: Replace the value of the mapping the message names, or remove that mapping.
BSNP-VALD-1008: No page for the payer to land on after paying, or a success or cancel page that is not a web address. Resolution: Set Payment Success Url (or map SuccessUrl), and check that each page is a full web address.
"VALD-1036 - Value (CRCARD) provided for Payment Method is not valid": The Method mapping names no Payment Method in your company. Resolution: Create the Payment Method or change the Method mapping (see Placeholder Values); the next poll records the payment.
BSNP-EXTN-1006: The invoice/payment webhook was turned on. Resolution: Turn it off; payments come back by the reconciliation poll.
Payments do not come back: The invoice/poll event is not scheduled, or the invoice has not changed in iPaaS.com within Reconciliation Days. Resolution: Schedule the poll (see Reconciliation Poll), or run a Manual Sync of the invoice number on Update BlueSnap Invoice TO iPaaS.com.
Support and Troubleshooting
Support Portal: https://support.ipaas.com/en/
Contact Information: https://ipaas.com/contact-us/
BlueSnap support: contact BlueSnap Merchant Support through BlueSnap Support to enable BlueSnap Checkout or a custom link lifetime, to add a permission to secondary API credentials, or to unlock locked credentials.
Known limitations: see BlueSnap Integration Known Limitations for the integration's scope and design decisions.
Related Documents