Payments
BlueSnap-compatible Payment API
A mock of BlueSnap's Payment API (JSON) with sandbox semantics: card authorizations, captures, reversals, refunds and vaulted shoppers, BlueSnap's error format and IPN notifications. Only test card numbers are accepted; no real money moves.
Testlie is not affiliated with, endorsed or sponsored by BlueSnap. "BlueSnap" is used only to describe API compatibility.
Connect
Create a BlueSnap-compatible gateway under Payment gateways. Use its base URL in place of https://sandbox.bluesnap.com and authenticate with HTTP Basic auth using the mock's API username and password. Send Content-Type: application/json (the XML flavour of the API is not supported).
| Credential | Use |
|---|---|
| API username, API password | Basic auth on every call |
| Data protection key | Computes the IPN authKey |
| Contract id | Sent as contractId / productId in IPNs |
Wrong credentials answer 401 with a JSON error (no browser login prompt).
Errors use BlueSnap's shape:
{ "message": [{ "errorName": "INSUFFICIENT_FUNDS", "code": "14002", "description": "Transaction failed because of payment processing failure: Insufficient funds." }] }The mock's codes: 10001 validation (INVALID_CC_NUMBER, INVALID_EXP_DATE, INVALID_AMOUNT, ...), 14002 declines, 14016-14019 invalid capture, reversal or refund, 20008 unknown transaction, 90015 authentication.
Endpoints
| Endpoint | |
|---|---|
POST or PUT /services/2/transactions |
cardTransactionType: AUTH_ONLY, AUTH_CAPTURE (with amount, currency, creditCard or vaultedShopperId, cardHolderInfo, softDescriptor, merchantTransactionId), CAPTURE (transactionId, optional lower amount), AUTH_REVERSAL (transactionId) |
GET /services/2/transactions/{id} |
Includes refunds |
POST /services/2/transactions/refund/{id} |
{ "amount", "reason" }; full refund without an amount. Returns refundTransactionId |
PUT /services/2/transactions/{id}/refund?amount=&reason= |
The older refund call; answers 204 |
POST /services/2/vaulted-shoppers |
firstName, lastName, email, paymentSources.creditCardInfo[].creditCard |
GET / PUT /services/2/vaulted-shoppers/{id} |
PUT updates names and adds cards |
A card payment without vaultedShopperId creates a shopper, as BlueSnap does. To charge a stored card send vaultedShopperId with creditCard: { cardLastFourDigits, cardType }.
Not implemented: 3-D Secure, Hosted Payment Fields tokens, subscriptions, alternative payment methods, batch transactions and the XML API.
Test cards only
A card number must pass the Luhn check and be one of these published test numbers. Anything else, including a real card, is refused with INVALID_CC_NUMBER; card numbers and security codes are never stored (the mock keeps the brand and last four digits) and are masked in the call log. Any future expiry date works.
| Brand | Numbers |
|---|---|
| Visa | 4263982640269299, 4111111111111111, 4242424242424242, 4012888888881881, 4000056655665556 |
| Mastercard | 5425233430109903, 2222420000001113, 2223000048410010, 5555555555554444, 5105105105105100 |
| American Express | 374245455400126, 378282246310005, 371449635398431 |
| Discover | 6011000991300009, 6011111111111117 |
| JCB | 3566000020000410, 3530111333300000 |
| Diners | 3055155515160018, 30569309025904 |
Simulated declines
| Card | Decline (errorName) |
|---|---|
| 4000000000000002 | PROCESSING_GENERAL_DECLINE |
| 4000000000009995 | INSUFFICIENT_FUNDS |
| 4000000000000069 | EXPIRED_CARD |
| 4000000000000127 | CVV_ERROR |
| 4000000000000119 | GENERAL_PAYMENT_PROCESSING_ERROR |
| Amount ends in | Decline |
|---|---|
| .51 | INSUFFICIENT_FUNDS |
| .52 | PROCESSING_GENERAL_DECLINE |
| .53 | EXPIRED_CARD |
| .54 | CALL_ISSUER |
| .55 | PICKUP_CARD |
Declines answer 400 with code 14002. The Outcome scenario overrides both tables: "succeed" approves everything, "decline" declines with the chosen code.
IPNs
Set the gateway's webhook URL to receive Instant Payment Notifications: form-encoded POSTs with transactionType (CHARGE, AUTH_ONLY, AUTH_REVERSAL, REFUND, DECLINE), referenceNumber, originalReferenceNumber (refunds), contractId, contractName, productId, productName, accountId (the vaulted shopper), merchantTransactionId, firstName, lastName, email, currency, invoiceAmount, invoiceAmountUSD, paymentMethod, creditCardType, creditCardLastFourDigits, transactionDate, testMode=Y and authKey.
authKey is the MD5 hex digest of referenceNumber + contractId + data protection key; compare it to authenticate the IPN. AUTH_REVERSAL is the mock's name for a reversed authorization. The webhook scenarios (delay, drop, duplicate, bad signature) apply, and failed deliveries are retried.