Skip to main content

Fundamentals

Core Concepts​

Payment Methods​

Banksy SDK supports multiple payment methods:

  • Credit/Debit Cards (Visa, MasterCard, American Express)
  • Digital Wallets (Apple Pay, Google Pay, Samsung Pay)
  • Cryptocurrencies (Bitcoin, Ethereum)
  • Bank Transfers
  • PayPal

Security Features​

  • End-to-end encryption for all transactions
  • PCI-DSS compliance
  • Tokenization of sensitive data
  • Built-in fraud detection
  • Automated compliance with regional regulations

Event System​

Real-time notifications through webhooks for:

  • Payment status changes
  • Refunds and disputes
  • System alerts
  • Settlement updates

Configuration​

Initial Setup​

import { Banksy } from "banksy-sdk";

const banksy = new Banksy("YOUR_CLIENT_KEY");
export default banksy;

Payment Status Types​

StatusDescription
awaitingPayment created, not processed
successPayment confirmed
cancelledCancelled by user
failedPayment failed
disputedUnder dispute
refundedSuccessfully refunded

Webhook Integration​

// Sample webhook payload
{
  "paymentId": "******************",
  "paymentRaw": {
    "id": "******************",
    "amount": 48.99,
    "currency": "USD",
    "status": "success",
    "environment": "live",
    "createdAt": "2024-10-30T13:34:00.535Z"
  }
}

Implementation Flow​

1. Create Payment Request​

const paymentPayload = {
    amount: 100,
    currency: "USD",
    successCallback: "https://yourdomain.com/success",
    failureCallback: "https://yourdomain.com/failure",
    currencyType: "fiat",
    isKycOptional: false
};

const paymentData = await banksy.createPayment(paymentPayload);

2. Handle Payment Response​

// Redirect to payment page
window.location.href = paymentData.paymentLink;

// Verify payment status
const paymentStatus = await banksy.getPayment(paymentId);
if (paymentStatus.success) {
    console.log("Payment Successful: ", paymentStatus);
}

3. Process Webhooks​

Configure your webhook endpoint to handle payment status updates and implement appropriate business logic for each status change.

Data Flow Diagram​

Payment Flow

Best Practices​

  1. Security

    • Store API keys in environment variables
    • Implement webhook signature verification
    • Regular key rotation

  2. Error Handling

    • Implement proper error handling
    • Use test environment for development
    • Monitor webhook deliveries

  3. Performance

    • Configure appropriate timeouts
    • Implement retry mechanisms
    • Enable logging in development