Skip to main content
This guide will walk you through creating and executing your first payout using the Zuba API. You’ll learn how to set up a beneficiary and send them a payment via SEPA.

​
Prerequisites

Before you start, make sure you have:
  • Valid API credentials (see Authentication)
  • Your API base URL
  • Test or production account with sufficient balance

​
Step 1: Create a Beneficiary

First, you need to create a beneficiary who will receive the payout. A beneficiary represents a person or entity with their payment account details. 
const beneficiaryData = {
  name: "John Doe",
  email: "john.doe@example.com",
  country: "DE",
  address: "Hauptstraße 123, Berlin, 10115",
  accounts: [
    {
      type: "iban",
      currency: "EUR",
      data: {
        iban: "DE89370400440532013000",
        accountHolderName: "John Doe",
        bic: "DEUTDEFF"
      }
    }
  ]
};

const response = await fetch('https://api-test.zuba.com/v1/beneficiaries', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer YOUR_ACCESS_TOKEN'
  },
  body: JSON.stringify(beneficiaryData)
});

const beneficiary = await response.json();
console.log('Beneficiary created:', beneficiary.id);
​
id
string
Unique UUID for the created beneficiary
​
accounts
array
Array of payment accounts with their IDs and details

​
Step 2: Create Your First Payout

Now you can create a payout to your beneficiary. RECOMMENDED: Reference the beneficiary by ID (from Step 1). Currency Fields: inputCurrency is the currency from your account you’ll be paying from, while currency is what the beneficiary will receive (automatic conversion if different): 
const payoutData = {
  clientRef: "PAYOUT-2024-001",
  amount: "100.50",
  inputCurrency: "EUR",
  currency: "EUR",
  route: "sepa_inst", // Use "sepa_credit" for regular SEPA
  beneficiary: {
    id: beneficiary.id // Reference the beneficiary created in Step 1
  },
  senderInfo: {
    firstName: "Your",
    lastName: "Company",
    address: "123 Business Street",
    city: "London",
    postalCode: "EC1A 1BB",
    country: "GB"
  },
  reference: "Invoice payment",
  description: "Payment for services rendered"
};

const payoutResponse = await fetch('https://api-test.zuba.com/v1/payouts', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer YOUR_ACCESS_TOKEN'
  },
  body: JSON.stringify(payoutData)
});

const payout = await payoutResponse.json();
console.log('Payout created:', payout.id);
Alternatively, you can provide the full beneficiary object to create a new beneficiary inline: 
const payoutData = {
  clientRef: "PAYOUT-2024-001",
  amount: "100.50",
  inputCurrency: "EUR",
  currency: "EUR",
  route: "sepa_inst",
  beneficiary: {
    name: "John Doe",
    email: "john.doe@example.com",
    country: "DE",
    accounts: [{
      type: "iban",
      currency: "EUR",
      data: {
        iban: "DE89370400440532013000",
        accountHolderName: "John Doe",
        bic: "DEUTDEFF"
      }
    }]
  },
  senderInfo: {
    firstName: "Your",
    lastName: "Company",
    address: "123 Business Street",
    city: "London",
    postalCode: "EC1A 1BB",
    country: "GB"
  },
  reference: "Invoice payment",
  description: "Payment for services rendered"
};
See Payment Routes for available routes and their characteristics.

​
Step 3: Monitor Payout Status

Track your payout’s progress by checking its status: 
const statusResponse = await fetch(`https://api-test.zuba.com/v1/payouts/${payout.id}`, {
  headers: {
    'Authorization': 'Bearer YOUR_ACCESS_TOKEN'
  }
});

const payoutDetails = await statusResponse.json();
console.log('Status:', payoutDetails.status);
See Payout Statuses for detailed status definitions.

​
Step 4: Handle the Response

A successful payout response includes: 
{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "reference": "Invoice payment",
  "description": "Payment for services rendered",
  "amount": "100.50",
  "currency": "EUR",
  "route": "sepa_inst",
  "type": "fiat",
  "status": "created",
  "fee": "2.50",
  "beneficiary": {
    "id": "456e7890-e89b-12d3-a456-426614174000",
    "name": "John Doe",
    "email": "john.doe@example.com",
    "country": "DE",
    "accounts": [{
      "id": "123e4567-e89b-12d3-a456-426614174001",
      "type": "iban",
      "currency": "EUR",
      "status": "active",
      "data": {
        "iban": "DE89370400440532013000",
        "accountHolderName": "John Doe",
        "bic": "DEUTDEFF"
      },
      "createdAt": "2024-01-15T10:25:00Z",
      "updatedAt": "2024-01-15T10:25:00Z"
    }],
    "status": "active",
    "createdAt": "2024-01-15T10:25:00Z",
    "updatedAt": "2024-01-15T10:25:00Z"
  },
  "createdAt": "2024-01-15T10:30:00Z",
  "updatedAt": "2024-01-15T10:30:00Z"
}

​
Error Handling

Common errors when creating payouts: 
try {
  const response = await fetch('https://api-test.zuba.com/v1/payouts', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': 'Bearer YOUR_ACCESS_TOKEN'
    },
    body: JSON.stringify(payoutData)
  });

  if (!response.ok) {
    const error = await response.json();
    throw new Error(error.message);
  }

  const payout = await response.json();
} catch (error) {
  console.error('Payout failed:', error.message);
  // Handle specific errors:
  // - Insufficient funds
  // - Invalid beneficiary
  // - Invalid IBAN
  // - Currency not supported
}

​
Next Steps

​
Complete Example

Here’s a complete example combining all steps: 
async function sendFirstPayout() {
  const baseURL = 'https://api-test.zuba.com/v1';
  const headers = {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer YOUR_ACCESS_TOKEN'
  };

  try {
    // 1. Create beneficiary
    const beneficiary = await fetch(`${baseURL}/beneficiaries`, {
      method: 'POST',
      headers,
      body: JSON.stringify({
        name: "John Doe",
        email: "john.doe@example.com",
        country: "DE",
        address: "Sonnenstrasse 15 80331 Muenchen Germany",
        accounts: [{
          type: "iban",
          currency: "EUR",
          data: {
            iban: "DE89370400440532013000",
            accountHolderName: "John Doe",
            bic: "DEUTDEFF"
          }
        }]
      })
    }).then(r => r.json());

    console.log('Beneficiary created:', beneficiary.id);

    // 2. Create payout using beneficiary ID (recommended)
    const payout = await fetch(`${baseURL}/payouts`, {
      method: 'POST',
      headers,
      body: JSON.stringify({
        clientRef: "FIRST-PAYOUT",
        amount: "100.50",
        inputCurrency: "EUR",
        currency: "EUR",
        route: "sepa_inst",
        beneficiary: {
          id: beneficiary.id // Reference the beneficiary by ID
        },
        senderInfo: {
          firstName: "Your",
          lastName: "Company",
          address: "123 Business Street",
          city: "London",
          postalCode: "EC1A 1BB",
          country: "GB"
        },
        reference: "Welcome payment",
        description: "First payout to new beneficiary"
      })
    }).then(r => r.json());

    console.log('Payout successful:', payout.id);
    return payout;

  } catch (error) {
    console.error('Error:', error);
    throw error;
  }
}