Skip to main content

Sombrero

Overview​

Sombrero is a fiat payment provider that enables businesses to accept payments across multiple countries through various payment methods. It supports 6 major currencies (USD, GBP, EUR, AUD, CAD, JPY) and offers extensive payment options including card-present transactions, online payments, digital wallets, and bank transfers for specific regions. The platform provides flexible integration with optional KYC requirements and secure transaction processing.

Sombrero Logo

Features​

  • Comprehensive currency support (AUD, CAD, EUR, GBP, JPY, USD)
  • Multiple payment method support:
    • Card-present payments (Visa, Mastercard, Amex, and regional cards)
    • Online card payments
    • Digital wallets (Apple Pay, Google Pay, Cash App Pay)
    • ACH Bank Transfer (US only)
  • Global coverage across 8 countries (Australia, Canada, France, Ireland, Japan, Spain, UK, US)
  • Optional KYC verification system
  • Secure payment processing with test environment
  • Real-time payment notifications
  • Customizable success and failure callbacks
  • Developer-friendly SDK integration

Integration Requirements​

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

Supported Currencies​

Currencies
  • AUD - Australian Dollar
  • CAD - Canadian Dollar
  • EUR - Euro (France, Ireland, Spain)
  • GBP - British Pound Sterling
  • JPY - Japanese Yen
  • USD - United States Dollar

Payment Methods by Country​

CountryPayment Cards
AustraliaVisa, Mastercard, American Express, JCB, EFTPOS
CanadaVisa, Mastercard, American Express, Discover, Discover Diners, Interac, JCB, UnionPay
FranceVisa, Mastercard, American Express
IrelandVisa, Mastercard, American Express
JapanVisa, Mastercard, American Express, Discover, JCB, Transportation IC
SpainVisa, Mastercard, American Express
UKVisa, Mastercard, American Express
USVisa, Mastercard, American Express, Discover, JCB, UnionPay

Implementation​

Payment Payload Structure​

const payload = {
  amount: number, // Payment amount
  currency: string, // Currency code (USD/GBP/EUR)
  currencyType: "sombrero", // 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 createSombreroPayment() {
  try {
    const paymentPayload = {
      amount: 100,
      currency: "USD",
      currencyType: "sombrero",
      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 createSombreroPaymentWithKYC() {
  try {
    const paymentPayload = {
      amount: 1000,
      currency: "GBP",
      currencyType: "sombrero",
      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);
  }
}

Testing​

  1. Use test API keys for development
  2. Test with different currency combinations
  3. Verify callback handling for both success and failure scenarios
  4. Test KYC flows when isKycOptional is set to false

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": "sombrero",
    "isKycOptional": true,
    "customerEmail": "parth@gmail.com",
    "successCallback": "http://domain.com/success",
    "failureCallback": "http://domain.com/failure"
}'

Test Cards​

For testing payments in the development environment, you can use the following test card:

Card Number: 4111 1111 1111 1111
CVV: 111
Expiry Date: Any future date

This test card will always result in successful payments.

Security Considerations​

  • Always use HTTPS for API calls
  • Validate all input parameters
  • Store sensitive data securely
  • Implement proper authentication for callback endpoints
  • Monitor transactions for suspicious activity

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.