Skip to main content

BlueSnap Error Messages

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

Overview

This article catalogs the error messages the iPaaS.com BlueSnap integration can record, grouped by flow. Each error carries a stable code (for example BSNP-VALD-1001) that begins the message, so you can find it on this page with Ctrl+F. Every entry lists the code and the message, what causes it, and how to resolve it. Errors appear in iPaaS.com under Dashboard / Integration Monitoring / Error Logs; warnings that are written only to the transfer's technical log never appear there, and are described in BlueSnap Integration Known Limitations instead. Words in braces, for example {invoice number}, are filled in with the record's details when the error happens.

Some resolutions refer to your Managed Integration Service Provider (MiSP): the partner who owns your integration's mappings, connection settings and credentials, and data reconciliation. When an error needs investigation rather than a self-service fix, your MiSP is the right first point of contact.

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

Supported Flows

  • Connection and Authentication

  • Invoice FROM iPaaS.com

  • Invoice and Payment TO iPaaS.com

  • Invoice/Payment Webhook

  • All Flows (BlueSnap API errors)

  • All Flows (setup and internal errors)

Error Collection

Connection and Authentication

The integration checks its settings each time it connects, before calling BlueSnap. When a setting stops the connection (BSNP-AUTH-1001, BSNP-VALD-1009 or BSNP-VALD-1010), Dashboard / Integration Monitoring / Error Logs shows only iPaaS.com's own message for the failed transfer, "Unable to connect to subscription with id {subscription id}", not the coded message below. When you see it, check each setting described in BlueSnap Connections and Settings.

A required connection setting is missing

BSNP-AUTH-1001 - These settings are required: {missing settings}. Use the API credentials from BlueSnap's Merchant Portal (Settings → API Settings), not your portal sign-in.

BSNP-AUTH-1001 - The subscription's settings couldn't be read.

  • Description: API Username or API Password is blank; the first form names which. The second form means iPaaS.com gave the integration no settings at all. Nothing is sent to BlueSnap. In Error Logs this appears as "Unable to connect to subscription with id {subscription id}".

  • Resolution: Enter the API Username and API Password of your BlueSnap API credentials (not your Merchant Portal sign-in) and save the subscription. For the second form, save the subscription settings again; if the error continues, contact your MiSP.

The API Url is not an https address

BSNP-VALD-1009 - API Url "{value}" is not an https address. Use https://ws.bluesnap.com (production) or https://sandbox.bluesnap.com (sandbox).

An optional setting can't be used

BSNP-VALD-1010 - These settings can't be used: {setting} "{value}": {what is allowed}; ….

BlueSnap refused the API credential

BSNP-AUTH-1002 - BlueSnap refused the API credential for {action} (401). Check the API Username and API Password (BlueSnap: Settings → API Settings; not your portal sign-in), that the API Url is the right environment, and that iPaaS.com's addresses are in the account's Authorized IPs.

  • Description: BlueSnap answered 401 (unauthorized). Common causes: the Merchant Portal sign-in was entered instead of the API credentials; a value is mistyped; the API Url points at the other environment (sandbox credentials do not work in production, or the reverse); or the call came from an address that is not on your account's Authorized IPs list. During the reconciliation poll this error stops the whole run, because no invoice can be read. When BlueSnap refuses the connection check that runs before a transfer, Error Logs can show iPaaS.com's "Unable to connect to subscription with id {subscription id}" instead of this message.

  • Resolution: Re-enter the API Username and API Password from BlueSnap's Settings > API Settings page and check that API Url matches the credentials' environment. On the same page, check that both iPaaS.com outbound addresses, 20.98.221.25 and 69.61.66.130, are on Authorized IPs (see BlueSnap Connections and Settings). If every value is right and the error continues, contact BlueSnap Merchant Support to check the state of the API credentials.

BlueSnap refused the call: permission or product

BSNP-AUTZ-1001 - BlueSnap refused {action} (403): the API credential lacks the permission, or BlueSnap Checkout is not enabled for the account. Use the primary API credential, or ask BlueSnap Merchant Support to add the permission.

  • Description: BlueSnap answered 403 (forbidden). A secondary API credential has only the permissions granted to it (such as Reporting and Retrieve Transactions), and making pay links needs BlueSnap Checkout on the account. A refused read is treated as an error, never as "not paid", so a paid invoice is never reverted.

  • Resolution: Use the primary API credentials, or grant the secondary credential the permission the call needs. If pay links are refused, ask BlueSnap Merchant Support to confirm that BlueSnap Checkout is enabled for your account.

BlueSnap didn't name the merchant

BSNP-EXTN-1004 - BlueSnap answered the connection check without naming the merchant the API credential belongs to. Check that the credential has the Reporting permission.

  • Description: The connection check reads BlueSnap's transaction report for today, which names the merchant the API credentials belong to. BlueSnap answered without a merchant. During the reconciliation poll this error stops the whole run. When it happens at the connection check that runs before a transfer, Error Logs can show iPaaS.com's "Unable to connect to subscription with id {subscription id}" instead of this message.

  • Resolution: Check that the API credentials have the Reporting permission in BlueSnap's Merchant Portal. If they do and the error continues, contact BlueSnap Merchant Support.

Invoice FROM iPaaS.com

These errors stop the invoice before anything is sent to BlueSnap, so no pay link is made. The field names in the messages (InvoiceNumber, Currency, Amount, ExpireAt, SuccessUrl, CancelUrl) are the destination fields of the Add/Update BlueSnap Invoice FROM iPaaS.com mapping collection.

No invoice number

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

  • Description: The value mapped to InvoiceNumber is blank, so the invoice can't be matched to a BlueSnap payment.

  • Resolution: Keep TransactionNumber mapped to InvoiceNumber (the template does), and make sure the transaction has a number.

No amount to collect

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

  • Description: Amount is empty, 0 or negative, or rounds to 0 in the invoice's currency.

  • Resolution: Check the invoice total, or what the mapping sends to Amount.

Currency is not a currency code

BSNP-VALD-1003 - Invoice {invoice number}: Currency "{value}" is not a 3-letter currency code (e.g. USD).

  • Description: The value mapped to Currency is not a 3-letter code. A blank currency is not an error: the link is made in USD.

  • Resolution: Map a 3-letter ISO 4217 code (for example USD, EUR or GBP) to Currency, or leave it blank for USD. The currency must also be one your BlueSnap account accepts; otherwise BlueSnap refuses the pay link with BSNP-EXTN-1005.

Invoice number too long

BSNP-VALD-1004 - Invoice number "{invoice number}" is longer than BlueSnap allows (50 characters).

  • Description: BlueSnap accepts invoice numbers of at most 50 characters. A long number is shortened in the message.

  • Resolution: Use invoice numbers of at most 50 characters, or map a shorter value to InvoiceNumber.

Invoice number with a character BlueSnap can't look up

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.

  • Description: The integration finds the payment in BlueSnap by the invoice number, and these characters break that lookup.

  • Resolution: Map a number without these characters to InvoiceNumber. Letters, digits, -, _ and . are safe.

A template placeholder is still in place

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

  • Description: A mapped value still starts with REPLACE with. The integration refuses it so that an unedited template value is never shown to a payer.

  • Resolution: In the Add/Update BlueSnap Invoice FROM iPaaS.com mapping collection, replace the value of the mapping the message names with your own, or remove that mapping.

The expiry date can't be used

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

BSNP-VALD-1007 - Invoice {invoice number}: ExpireAt {date} is in the past, so the pay link would never work.

BSNP-VALD-1007 - Invoice {invoice number}: ExpireAt {date} is more than 365 days away; BlueSnap pay links last at most a year.

  • Description: The value mapped to ExpireAt (the date the pay link stops working) is not a date, is in the past, or is more than 365 days away.

  • Resolution: Map a future date within 365 days to ExpireAt, or remove the mapping so the link lasts Pay Link Lifetime Days.

No page for the payer to land on

BSNP-VALD-1008 - Invoice {invoice number}: no page for the payer to land on after paying. Set the Payment Success Url setting, or map SuccessUrl.

BSNP-VALD-1008 - Invoice {invoice number}: {SuccessUrl or CancelUrl} "{value}" is not a web address (https://…).

  • Description: The first form fires whenever neither a SuccessUrl mapping nor the Payment Success Url setting gives a page, even when your BlueSnap Checkout Settings have a success page. The second form fires when a mapped SuccessUrl or CancelUrl is not a web address. (A Payment Success Url or Payment Cancel Url setting that is not a web address is refused at connection instead: see BSNP-VALD-1010.)

  • Resolution: Set Payment Success Url to a page on your website (or map SuccessUrl for each invoice). For the second form, correct the mapping the message names so it gives a full web address starting with https:// or http://.

Invoice and Payment TO iPaaS.com

Several payments on one invoice, not yet in BlueSnap's report

BSNP-EXTN-1003 - BlueSnap holds more than one payment for invoice {invoice number}, and its transaction report doesn't list them yet (it can run an hour or more behind). Nothing was changed on the invoice; the reconciliation poll checks it again on each run, or send it again later (Manual Sync).

  • Description: More than one pay link of the invoice was paid (BlueSnap accepts payment on an older link as well as the current one). BlueSnap reports several payments for one invoice number only through its transaction report, which runs behind. Writing only some of them would show a paid invoice as unpaid, so nothing changes on the invoice until the report lists them all. The reconciliation poll skips such an invoice without logging this error and checks it again on each run; the error appears on a Manual Sync TO iPaaS.com.

  • Resolution: Wait: 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; refund in BlueSnap whatever isn't owed. If the error still appears the next day, contact your MiSP.

Invoice/Payment Webhook

BlueSnap's IPN settings couldn't be changed

BSNP-EXTN-1006 - BlueSnap's IPN settings couldn't be {updated with / cleared of} this subscription's endpoint: {reason} Payments still come back by the reconciliation poll: leave the invoice/payment webhook off (see the installation instructions).

BSNP-EXTN-1006 - BlueSnap's IPN settings couldn't be {updated with / cleared of} this subscription's endpoint: {reason}

  • Description: Turning the invoice/payment webhook on or off reads and saves BlueSnap's instant payment notification (IPN) settings. The first form means BlueSnap refused one of those calls; {reason} quotes BlueSnap's answer. BlueSnap refuses iPaaS.com's address ("IPN url is not valid"), so turning the webhook on ends here. The second form means the integration couldn't connect to BlueSnap at all; {reason} names the connection problem, such as a setting that can't be used.

  • Resolution: Leave the invoice/payment webhook off: payments come back by the reconciliation poll, which is how this integration is designed to work. For the second form, correct the problem the message names (see BlueSnap Connections and Settings).

All Flows (BlueSnap API errors)

These errors can come from any call to BlueSnap. In the messages, {action} names what the integration was doing, for example "the pay link for invoice {invoice number}", "the payment for invoice {invoice number}", "the bank (ACH) or other payment for invoice {invoice number}", "the transaction report", "the webhook (IPN) settings" or "the connection check (today's transaction report)". During the reconciliation poll, an invoice BlueSnap can't return is sent as its own transfer, so its error appears on that invoice in Error Logs, where it can be retried, while every other invoice is still reconciled.

BlueSnap refused the request

BSNP-EXTN-1005 - BlueSnap refused {action}: {BlueSnap's reason}

BSNP-EXTN-1005 - BlueSnap couldn't return {action} ({status}): {BlueSnap's reason}

  • Description: BlueSnap answered 400 or 422 and its reason is quoted. The first form is for a request that makes or saves something, such as a pay link; for example, BlueSnap refuses a currency your account does not accept ("currency is not supported by merchant's processors"). The second form is for a read, such as the payment for an invoice.

  • Resolution: For the first form, correct what BlueSnap names (for example, map a currency your BlueSnap account accepts) and send the invoice again. For the second form, retry the transfer from Error Logs; if it continues, contact your MiSP with the invoice number and the time of the error.

BlueSnap has no record

BSNP-NFND-1001 - BlueSnap has no record for {action} (404).

  • Description: BlueSnap answered 404 (not found) for a call where a record was expected.

  • Resolution: Check that API Url points at the environment (production or sandbox) where your BlueSnap account and its invoices live. If it does and the error continues, contact your MiSP with the invoice number and the time of the error.

An unexpected answer from BlueSnap

BSNP-EXTN-1001 - BlueSnap answered {HTTP status} to {action}: {BlueSnap's reason}

BSNP-EXTN-1001 - BlueSnap answered the pay link request for invoice {invoice number} without a token.

  • Description: BlueSnap gave an answer the integration doesn't expect: an HTTP status not covered by the other errors on this page, or a pay link request that BlueSnap accepted without returning the token the link needs. BlueSnap's reason is quoted when it gives one.

  • Resolution: Read BlueSnap's reason in the message and retry the transfer from Error Logs. If it continues, contact BlueSnap Merchant Support with the invoice number and the time of the error.

BlueSnap is unavailable

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

  • Description: BlueSnap didn't answer, or answered with a server error (5xx). The error comes before anything is written, so nothing is half-written.

  • Resolution: No action is needed: iPaaS.com retries the transfer automatically.

BlueSnap's rate limit was reached

BSNP-EXTN-1007 - BlueSnap rate limit reached during {action}; retrying after {seconds}s.

  • Description: BlueSnap answered 429 or 503 because the account reached its call limits. The transfer is held and retried after the wait BlueSnap gives, or after 60 seconds. During the reconciliation poll, the run stops at that invoice and the next run continues from there.

  • Resolution: No action is needed: iPaaS.com retries the transfer after the wait.

All Flows (setup and internal errors)

A mapping collection the integration doesn't support

BSNP-BIZL-1001 - The BlueSnap integration has no {data type} data (mapping collection type {number}): it supports Transaction (invoices) FROM and TO iPaaS.com and Transaction Payment TO iPaaS.com. Remove or turn off this mapping collection.

  • Description: A mapping collection for a data type the BlueSnap integration does not support (for example Customer) was added to the subscription. iPaaS.com may add a technical note in parentheses after the message.

  • Resolution: Remove or turn off that mapping collection.

A call to iPaaS.com failed

BSNP-INTL-1001 - iPaaS.com couldn't complete a call the integration makes ({action}, HTTP {status}). Send the record again; if it keeps failing, contact iPaaS.com support with this error's reference id.

  • Description: A call the integration makes to iPaaS.com, such as reading the invoice it is working on or saving its external id, failed.

  • Resolution: Send the record again with a Manual Sync. If it repeats, contact your MiSP, or iPaaS.com Support at support@ipaas.com, with the error's reference id.

Internal error

BSNP-INTL-1002 - Internal error: {operation} was called with data the integration doesn't handle ({details}). Contact iPaaS.com support with this error's reference id.

BSNP-INTL-1002 - Internal error: the iPaaS.com API endpoint {endpoint} isn't handled. Contact iPaaS.com support with this error's reference id.

  • Description: A defect in the integration. Nothing in your setup causes it.

  • Resolution: Contact iPaaS.com Support at support@ipaas.com with the error's reference id.

Related Documents

Related Articles
Did this answer your question?