Skip to main content

Whirlpool

Overview​

Whirlpool is a payment provider that enables businesses to accept payments in multiple currencies including USD, GBP, and EUR. It provides a seamless integration for processing fiat currency transactions with optional KYC requirements.

Whirlpool Logo

Features​

  • Multi-currency support (USD, GBP, EUR)
  • Optional KYC verification
  • Secure payment processing
  • Instant payment notifications
  • Customizable success and failure callbacks

Integration Requirements​

  • Banksy API Key
  • Valid callback URLs for success and failure scenarios
  • Customer email for transaction notifications

Supported Currencies​

Currencies
  • AUD
  • BTC
  • CAD
  • CNY
  • CZK
  • EUR
  • GBP
  • HKD
  • IDR
  • INR
  • JPY
  • KHR
  • MXN
  • MYR
  • PHP
  • PLN
  • SGD
  • THB
  • USD
  • VND
  • NGN

Accepted Payment Methods​

Process payments via Credit Cards

  • Visa
  • MasterCard
  • American Express

Implementation​

Payment Payload Structure​

const payload = {
  amount: number, // Payment amount
  currency: string, // Currency code (USD/GBP/EUR)
  currencyType: "whirlpool", // Fixed value for fiat transactions
  isKycOptional: boolean, // Whether KYC is required
  customerEmail: string, // Customer's email address
  successCallback: string, // URL for successful payments
  failureCallback: string, // URL for failed payments
};

Example Implementation​

import { Banksy } from "banksy-sdk";

// Initialize the Banksy SDK with your API key
const banksy = new Banksy("your-api-key");

async function createWhirlpoolPayment() {
  try {
    const paymentPayload = {
      amount: 100,
      currency: "USD",
      currencyType: "whirlpool",
      isKycOptional: true,
      customerEmail: "customer@example.com",
      successCallback: "https://your-domain.com/success",
      failureCallback: "https://your-domain.com/failure",
    };

    const payment = await banksy.createPayment(paymentPayload);
    console.log("Payment Created:", payment);

    // Redirect to payment page
    window.location.href = payment.paymentLink;
  } catch (error) {
    console.error("Payment creation failed:", error);
  }
}

Example with KYC Required​

import { Banksy } from "banksy-sdk";

const banksy = new Banksy("your-api-key");

async function createWhirlpoolPaymentWithKYC() {
  try {
    const paymentPayload = {
      amount: 1000,
      currency: "GBP",
      currencyType: "whirlpool",
      isKycOptional: false, // KYC will be required
      successCallback: "https://your-domain.com/success",
      failureCallback: "https://your-domain.com/failure",
    };

    const payment = await banksy.createPayment(paymentPayload);
    console.log("Payment Created:", payment);

    // Redirect to payment page with KYC flow
    window.location.href = payment.paymentLink;
  } catch (error) {
    console.error("Payment creation failed:", error);
  }
}

Test Cards​

Card TypeCard NumberExpiryCVV
Visa424242424242424201/30123
Mastercard555555555555444401/30123
American Express37828224631000501/301234

Error Handling​

Common error codes and their meanings:

  • 101: Invalid Public Key
  • 102: Inactive Terminal
  • 151: Invalid Card Number
  • 154: Invalid CVV
  • 666: Duplicate Reference ID

API Testing with cURL​

You can test the payment creation endpoint using the following cURL command:

curl --location 'https://sandbox-api.banksy.id/sdk/payment/create' \
--header 'Content-Type: application/json' \
--header 'X-AUTH: ck_test_************738139' \
--data-raw '{
    "amount": 100,
    "currency": "GBP",
    "currencyType": "whirlpool",
    "isKycOptional": true,
    "customerEmail": "parth@gmail.com",
    "successCallback": "http://domain.com/success",
    "failureCallback": "http://domain.com/failure"
}'

Best Practices​

  1. Amount Validation

    • Ensure the amount is a positive number
    • Validate against minimum and maximum transaction limits
    • Use proper decimal handling for different currencies

  2. Currency Handling

    • Always verify the currency is supported before creating the payment
    • Use proper currency formatting based on the selected currency
    • Consider exchange rate implications for international transactions

  3. Callback URLs

    • Use HTTPS for callback URLs
    • Implement proper validation in callback endpoints
    • Handle both success and failure scenarios gracefully

  4. Error Handling

    • Implement comprehensive error handling
    • Log all payment attempts and responses
    • Provide clear error messages to users

Support​

For technical support or integration assistance, please contact the Banksy support team through the official channels.