Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.zuba.com/llms.txt

Use this file to discover all available pages before exploring further.

Overview

Payins enable you to accept payments from customers through manual bank transfers. The Zuba platform processes these payments and credits funds to your account while maintaining full transparency and compliance.

Manual Deposits

Traditional bank transfers where customers manually send funds to your designated account. When you create a manual deposit, Zuba generates unique bank account details (IBAN and reference) for your customer to transfer funds to.
curl -X POST "https://api-test.zuba.com/v1/deposits" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": "500.00",
    "currency": "EUR",
    "clientRef": "DEPOSIT-REF-001",
    "description": "Subscription payment"
  }'

Payment Lifecycle

Payment Statuses

StatusDescriptionActions Available
pendingDeposit created, awaiting customer transferMonitor, Cancel
processingTransfer detected, being verifiedTrack status
completedFunds received and credited to your accountView receipt
failedDeposit expired or transfer failedReview, Create new
cancelledDeposit cancelled before completionView details

Checking Deposit Status

curl -X GET "https://api-test.zuba.com/v1/deposits/dep_1234567890" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Listing Deposits

Retrieve all deposits for your account, optionally filtered by status:
curl -X GET "https://api-test.zuba.com/v1/deposits?status=completed" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Cancelling Pending Deposits

Cancel deposits that haven’t been completed yet:
curl -X POST "https://api-test.zuba.com/v1/deposits/dep_1234567890/cancel" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
Only deposits in pending status can be cancelled. Once a deposit is processing or completed, it cannot be cancelled.

Supported Countries & Currencies

European Union (SEPA Zone)

  • Countries: Germany, France, Spain, Italy, Netherlands, Belgium, Austria, Portugal, Finland, Ireland, and more
  • Currency: EUR
  • Settlement: 1-2 business days

United Kingdom

  • Currency: GBP
  • Settlement: 1-2 business days via UK bank transfer

Supported Currencies

  • Major Fiat: EUR, GBP, USD, CAD
  • Settlement Times: Vary by currency and banking network

Webhooks & Notifications

Set up webhooks to receive real-time updates on deposit status changes:
Webhook Payload Example
{
  "id": "evt_1234567890",
  "type": "deposit.completed",
  "data": {
    "depositId": "dep_1234567890",
    "method": "manual_deposit",
    "amount": "500.00",
    "currency": "EUR",
    "status": "completed",
    "completedAt": "2024-03-15T10:30:00Z"
  },
  "timestamp": "2024-03-15T10:30:05Z"
}

Webhook Events

EventDescriptionWhen Triggered
deposit.createdDeposit createdWhen deposit request is initiated
deposit.processingDeposit being processedTransfer detected from customer
deposit.completedDeposit completedFunds received and credited
deposit.failedDeposit failedTransfer failed or deposit expired
deposit.cancelledDeposit cancelledUser or system cancellation

Error Handling

Common deposit errors and solutions:
Error CodeDescriptionSolution
INVALID_AMOUNTAmount is invalid or too largeCheck amount format and limits
UNSUPPORTED_CURRENCYCurrency not supportedUse supported currency (EUR, GBP, USD, CAD)
DEPOSIT_EXPIREDDeposit reference expiredCreate new deposit
INVALID_REFERENCETransfer reference doesn’t matchEnsure customer uses exact reference
DUPLICATE_CLIENT_REFClient reference already usedUse unique clientRef for each deposit

Best Practices

  • Always include unique clientRef for idempotency and reconciliation
  • Provide clear instructions to customers about IBAN and reference
  • Set reasonable timeout periods and communicate them to customers
  • Store deposit IDs for status tracking and customer support
  • Implement webhook endpoints for real-time updates
  • Use exponential backoff when polling deposit status
  • Handle all possible status transitions in your code
  • Log deposit events for audit and debugging
  • Display IBAN, BIC, and payment reference clearly
  • Show expected settlement times (1-2 business days for SEPA)
  • Send confirmation emails with payment instructions
  • Implement proper error messaging for failed deposits
  • Provide customer support contact for payment issues
  • Validate webhook signatures to prevent spoofing
  • Use HTTPS for all API communications
  • Never log sensitive customer payment data
  • Implement proper access controls for deposit endpoints

Integration Example

React Deposit Component

import { useState } from 'react';

function DepositForm() {
  const [loading, setLoading] = useState(false);
  const [deposit, setDeposit] = useState(null);

  const createDeposit = async (amount, currency) => {
    setLoading(true);
    try {
      const response = await fetch('/api/create-deposit', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({
          amount,
          currency,
          clientRef: `DEP-${Date.now()}`
        })
      });

      const data = await response.json();
      setDeposit(data);
    } catch (error) {
      console.error('Deposit creation failed:', error);
    } finally {
      setLoading(false);
    }
  };

  return (
    <div>
      <button
        onClick={() => createDeposit('500.00', 'EUR')}
        disabled={loading}
      >
        {loading ? 'Creating Deposit...' : 'Deposit €500.00'}
      </button>

      {deposit && (
        <div className="payment-instructions">
          <h3>Bank Transfer Instructions</h3>
          <div>
            <strong>IBAN:</strong> {deposit.iban}
          </div>
          <div>
            <strong>BIC:</strong> {deposit.bic}
          </div>
          <div>
            <strong>Reference:</strong> {deposit.reference}
          </div>
          <div>
            <strong>Amount:</strong> {deposit.amount} {deposit.currency}
          </div>
          <p>
            Please use the reference code exactly as shown.
            Your payment will be credited within 1-2 business days.
          </p>
        </div>
      )}
    </div>
  );
}

Next Steps

Payouts

Send money globally to beneficiaries

Webhook Setup

Configure real-time deposit notifications

Ledger System

Track transactions with double-entry accounting

API Reference

Complete API documentation