BlueSnap

Adapter 0.1.0, documentation reviewed 2026-10-25. Overall status: limited.

Capabilities

Supported input

Notification delivery

• Repeated deliveries are recognized by transactionType, referenceNumber, reversalRefNum, cbStatus and transactionDate (BlueSnap documents no event or delivery id; this combination is the research file's suggestion); BlueSnap documents that notifications can be delivered more than once.
• Delivery order: not documented by the provider.
• BlueSnap retries a webhook up to 11 times until it receives an empty HTTP 200 OK, and a manual resend from the Merchant Portal produces a duplicate by design. Webhooks carry no event id, so make the handler idempotent per transactionType and referenceNumber (plus reversalRefNum and cbStatus for refunds and chargebacks), and retrieve the transaction before acting on an event, since the delivery order is not documented.

Known limitations

• The JSON Payment API, the XML Payment API card transaction and error documents, and form-encoded webhooks are analyzed. Other XML documents in the namespace http://ws.plimus.com (refund, alt-transaction, vaulted-shopper, recurring-subscription) and the Extended Payment API, whose element names are not in the reviewed sources, are recognized as BlueSnap XML but not analyzed. Alt transaction responses (ACH/ECP, SEPA, PayPal, BECS, Pre-Authorized Debit) are recognized but not analyzed; batch transaction results, browser callbacks (Hosted Payment Fields, 3-D Secure) and the Reporting API are not analyzed.
• XML is claimed only in BlueSnap's namespace http://ws.plimus.com; the same elements without that namespace are not attributed to BlueSnap. The XML Payment API has the same semantics as the JSON one, and its kebab-case element names are read as the corresponding JSON fields (card-transaction-type as cardTransactionType, processing-info as processingInfo, error-name as errorName, invalid-property as invalidProperty). The names of elements the reviewed sources do not list, such as the children of fraud-events, are read through that same correspondence and are an inference. Attributes are ignored, empty elements count as absent, and XML gives every value as text, so true and false are read as booleans. Errors in XML are decoded by error-name exactly like the JSON body; the XML card error page lacks four names of the JSON page, which are still decoded from the JSON table.
• Errors are decoded by errorName, not by the numeric code: 37 card error names share 14002, and some numbers mean different things on different pages (14034, 20051, 24011, 90014, 90032). When a name appears in several tables with different guidance (for example NO_AVAILABLE_PROCESSORS, EXPIRED_TOKEN, INVALID_CARD_NUMBER), the card transaction reading is used with possible confidence and all readings are listed. A code alone, or an undocumented name, is decoded only when the code belongs to a single documented row, with possible confidence.
• Processor (issuer) decline codes are not documented. A processor code and text that BlueSnap appends to description (for example after 'processing failure.:') is shown as provider text only and is not decoded.
• Category and retry guidance per error are PandaPayLens suggestions. BlueSnap's own advice is shown for card transaction errors; where its pages conflict (SYSTEM_TECHNICAL_ERROR: do not retry on the Payment API page, retry on the Extended Payment API page) the Payment API advice is used.
• Webhooks carry no event or delivery id. The delivery key combines transactionType, referenceNumber, reversalRefNum, cbStatus and transactionDate; whether transactionDate stays the same across BlueSnap's retries is not documented, and its minute precision can make two genuine events in the same minute look like one.
• No BlueSnap timestamp is used as event time: card transaction approval times are Pacific time without a zone, webhook transactionDate has no documented time zone, and refund and chargeback dates have no documented format. They are shown as sent, and events follow the input order.
• Webhook reason fields (declineReason, failureReason, cancelReason, reversalReason) are free text without a documented format. A documented errorName or ACH return code found in them is decoded with possible confidence (strong when the field holds only the ACH code); anything else is shown as provider text with an unknown category. errorProcessingCode is undescribed and shown as a sub-code only. Card brand chargeback reason codes are not decoded.
• Webhook amounts are read from invoiceChargeAmount with invoiceChargeCurrency (falling back to invoiceAmount with currency) in the documented #,###.## format, for payment and authorization events only. The research documents the format but not the exact meaning of each amount field. reversalAmount has no documented currency and is shown as an attribute only.
• transactionId and referenceNumber are the same BlueSnap ID, and originalRefNum links recurring charges to the initial transaction. Refund and chargeback IDs (refundTransactionId, chargebackTransactionId) are linked to webhook reversalRefNum on the inference, not stated by BlueSnap, that they are the same values. Declined API calls return no transaction ID and cannot be linked. merchantTransactionId is shown but never used for linking.
• The webhook security header (Bls-Ipn-Timestamp, Bls-Signature) is described inconsistently and authKey needs the merchant's Data Protection Key, so a pasted webhook is never treated as verified. Only the presence of authKey (and whether it has the shape of an MD5 hex digest) and of the Bls-Signature header is reported; their values are never copied.
• PENDING_REFUND is sent both when a pending refund starts and when it is deleted after 3 months of failed attempts; the payload does not say which, so it is shown as pending. Chargeback outcomes are left unknown; cbStatus (New, Working, Completed_Won, Completed_Lost, Completed_Pending) is shown as the provider status. RDR appears in the parameter reference without a description and is reported as an unknown event type. The PAYOUT webhook is recognized only when it carries transactionType.
• Throttling responses (HTTP 429 or 503) are recognized only when the body is plain text equal to one of the five documented messages; BlueSnap does not document the field that carries them. Bodies of HTTP 403, 404 and 500 responses are not documented and are not attributed to BlueSnap.
• acquiring is listed because BlueSnap publishes local card acquiring guides for Israel and LatAm; the scope of its own acquiring is not documented in the reviewed sources. Sectors are BlueSnap's own marketing categories and say nothing about approval.
• Kount response keys 323 and 332 are catalogued but not decoded, because where they appear in a payload is not documented. CVV, AVS and 3-D Secure values are shown as attributes and not treated as errors.

Examples

• BlueSnap: charge, refund and chargeback webhooks: Form-encoded webhooks linked into one transaction by the reference number.
• BlueSnap: declined, do not honor: An HTTP 400 decline decoded by error name, although many card errors share one numeric code.

Provider documentation

• Error handling overview
• message object
• message object (XML)
• Card transaction errors
• Alt transaction errors
• Refund errors
• Fraud errors
• Idempotency errors
• Subscription and billing plan errors
• Wallet errors
• Hosted Payment Fields errors
• Card transaction object
• processingInfo object
• Auth Capture
• Auth Capture (XML)
• Card transaction errors (XML)
• Refund
• Idempotency
• Webhooks (IPNs)
• Webhook name reference
• Webhook parameter reference
• Webhook FAQs (retries)
• Webhook setup (security header)
• Understanding your declined authorizations
• ACH/ECP return codes
• About chargebacks

PandaPayLens is not affiliated with BlueSnap. Pasted notifications are never treated as verified: PandaPayLens does not check webhook signatures.