Fiat Pay-outs Integration Guide

Introduction

This guide explains how to integrate the Paybis Send Fiat Payouts API into your platform to programmatically initiate and manage fiat transfers. The API enables you to send EUR local payouts (via SEPA) to beneficiary bank accounts using your pre-funded fiat balance.

Paybis Send Fiat Payouts supports a wide range of partners, including PSPs, Acquirers, Merchants, payroll providers, e-commerce platforms, and other payout-driven platforms.

📘

Note: Support for international transfers and additional currencies is coming soon.

Prerequisites

• Implement request signing: Secure all API requests by implementing request signing. See our Signing Requests Guide for details.
• (Optional) Client-facing UI: Build a user interface that uses Paybis Send APIs to allow your customers initiate payouts, track transactions, and view payout history.
• (Optional) Admin panel integration: Integrate Paybis Send into your admin or operations panel to enable your team to initiate payouts on behalf of the customers and monitor transaction statuses.

Send Fiat Flow

1. Check Pre-funded Balance

Ensure that sufficient funds are available in your pre-funded fiat balance (EUR) to cover the payout amount plus commission.

Balance Check:

Available Balance >= (Payout Amount + Commission Amount)

See the Get Available and Hold Balances reference for balance endpoints.

2. Execute Fiat Payout Transaction

Use the Execute API to submit the payout request to Paybis. Paybis will debit your pre-funded balance and execute the fiat transfer to the specified IBAN.

API Call:

POST /event

Request Body:

{
    "event_id": "3f6c8e92-5a41-4d7b-b2e4-9c1f7a6d8b53",
    "name": "payout_execute",
    "payout": {
        "amount": {
            "amount": "5",
            "currency": "EUR"
        },
        "beneficiary": {
            "type": "business",
            "companyName": "Company Name",
            "iban": "ES7921000813610123456789"
        },
        "reference": "Invoice 12345"
    },
    "timestamp": "2023-09-16T18:07:55+00:00",
}

See the Execute API Endpoint reference.

3. Transaction Statuses and Reconciliation

Paybis notifies you about payout status changes via the Transaction Data Webhook. Implement webhook handling to update transaction states, reconcile balances, and keep your system in sync.

Status Flow:

initialized → validating → processing → in_transit → completed
                                    ↓
                                  failed

Webhook Examples:

{
  "event_type": "payout.completed",
  "transaction_id": "txn-fiat-123456",
  "status": "completed",
  "payout_amount": "100.00",
  "commission_amount": "2.50",
  "total_deduction": "102.50",
  "beneficiary": {
    "iban": "DE89370400440532013000",
    "name": "John Doe"
  },
  "timestamp": "2026-03-27T10:25:00Z"
}

{
  "event_type": "payout.failed",
  "transaction_id": "txn-fiat-123456",
  "status": "failed",
  "failure_reason": "INVALID_IBAN",
  "failure_message": "Bank validation failed: Invalid IBAN checksum",
  "timestamp": "2026-03-27T10:05:00Z"
}

See the Transaction Data Webhook reference.

4. Retrieve Transactions via API

In addition to webhooks, you can actively retrieve a paginated list of payout transactions associated with your account using the Get Payouts endpoint. This is useful for history and reporting, reconciliation, and dashboard display.

API Call: GET https://cs-api.sandbox.paybis.com/v1/event/payout

Available Environments

Sandbox

A testing environment for your integration.

• Use the provided sandbox API key and base URL.
• IP whitelisting is not enforced in the sandbox.
• Fiat payouts use test banking rails. See the Sandbox Testing section for more details.
• Test with small amounts and various IBAN formats.

Production

The live environment for processing real transactions.

• Use the production API key and base URL.
• IP whitelisting is enforced and must be configured before going live.
• Real fiat balances and live SEPA transfers are used.
• Commission percentages are live and charged to your balance.

Key Points

• Responsibility: You are responsible for ensuring that your pre-funded fiat balance remains sufficient to cover upcoming payouts.
• Currency: Balances are held in fiat currencies (EUR, USD, GBP, and others). The balance for fiat payouts is in EUR.
• Failure Prevention: Low balance is the most common cause of payout failures. Maintain sufficient buffer.

Beneficiary Management

Supported Beneficiary Types

Individual:

• First name + Last name
• IBAN (EUR SEPA)
• Latin characters only (A-Z, a-z, spaces)

Corporate:

• Company name
• IBAN (EUR SEPA)
• Latin characters only (A-Z, a-z, spaces)

Beneficiary Caching

After the first successful payout to a beneficiary IBAN:

1. Beneficiary name and type are cached in your system
2. On subsequent payouts to the same IBAN, pre-fill cached data
3. User can confirm or update before resubmitting
4. This improves UX for repeat payouts to frequent recipients

Support

For assistance with Paybis Send Fiat Payouts API integration, request signing, webhooks, sandbox setup, balance management, or commission configuration, please contact your Paybis account manager or designated support team.