Transfer Lifecycle

Understanding the complete lifecycle of a transfer helps you build robust integrations and handle all possible scenarios correctly.

Overview

Every transfer goes through a series of states from creation to completion. Understanding these statuses helps you handle all scenarios correctly and build robust integrations.

Transfer Statuses

Status	Final?	Revocable?	Description
new	❌ No	✅ Yes	Transfer created, not yet confirmed by user
waiting	❌ No	✅ Yes	Awaiting user confirmation
waiting_funds	❌ No	✅ Yes	Insufficient balance, waiting for funds
waiting_registration	❌ No	✅ Yes	Beneficiaries not registered in system
waiting_password	❌ No	✅ Yes	Password required for authentication
reserved	❌ No	✅ Yes	Funds reserved, ready to process
done	✅ Yes	❌ No	Transfer completed successfully
failed	✅ Yes	❌ No	Transfer failed due to error
rejected	✅ Yes	❌ No	Bank rejected the transfer
revoked	✅ Yes	❌ No	Client cancelled the transfer

Final Statuses

Transfers in final statuses (done, failed, rejected, revoked) cannot transition to other states.

Complete Status Flow Diagram

                    ┌──────────────────┐
                    │   Create Transfer│
                    └────────┬─────────┘
                             │
                    ┌────────▼─────────┐
                    │       new        │
                    └────────┬─────────┘
                             │
                    ┌────────▼─────────┐
                    │   User Action    │
                    └────────┬─────────┘
                             │
           ┌─────────────────┼─────────────────┬─────────────┐
           │                 │                 │             │
    ┌──────▼──────┐   ┌──────▼──────┐   ┌─────▼────┐  ┌────▼─────┐
    │  rejected   │   │   waiting   │   │reserved  │  │ revoked  │
    │  (final)    │   │   (various) │   │          │  │ (final)  │
    └─────────────┘   └──────┬──────┘   └─────┬────┘  └──────────┘
                             │                 │
                      ┌──────┴──────┐          │
                      │             │          │
            ┌─────────▼──┐   ┌──────▼──────┐  │
            │waiting_funds│  │waiting_reg  │  │
            └─────────┬───┘  └──────┬──────┘  │
                      │             │          │
                      └──────┬──────┘          │
                             │                 │
                   ┌─────────▼─────────┐       │
                   │waiting_password   │       │
                   └─────────┬─────────┘       │
                             │                 │
                             └────────┬────────┘
                                      │
                             ┌────────▼─────────┐
                             │    reserved      │
                             └────────┬─────────┘
                                      │
                             ┌────────┴─────────┐
                             │                  │
                     ┌───────▼──────┐    ┌──────▼──────┐
                     │     done     │    │   failed    │
                     │   (final)    │    │   (final)   │
                     └──────────────┘    └─────────────┘

Status Details

new

When: Immediately after transfer creation via API

What it means: Transfer created successfully, awaiting next action (reserve, provide password, or user confirmation)

Next statuses: reserved, waiting_password, waiting, revoked

Callback: ❌ No

waiting

When: Transfer requires user confirmation

What it means: User must confirm or reject via Paysera interface

Next statuses: waiting_funds, waiting_registration, waiting_password, reserved, rejected, revoked

Callback: ✅ Yes

waiting_funds

When: User accepted transfer but account has insufficient balance

What it means: System waiting for funds to be added. Automatically moves to reserved when sufficient balance available.

Next statuses: reserved, failed, revoked

Callback: ✅ Yes

waiting_registration

When: One or more beneficiaries not registered in Paysera system

What it means: Beneficiaries will receive email invitation. Automatically progresses when all beneficiaries register.

Next statuses: waiting_password, reserved, revoked

Callback: ✅ Yes

waiting_password

When: Password authentication required

What it means: Use PUT /transfer/rest/v1/transfers/{id}/provide-password to provide password

Next statuses: reserved, failed, revoked

Callback: ✅ Yes

reserved

When: All requirements met, funds locked and ready to process

What it means: Transfer will proceed automatically. Can still be revoked before processing completes.

Next statuses: done, failed, revoked

Callback: ✅ Yes

Processing time: Paysera-to-Paysera: instant to few minutes. Bank transfers: 1-5 business days.

done

When: Transfer completed successfully, money transferred to beneficiary

What it means: ✅ Transfer successful. Cannot be reversed. Final status.

Callback: ✅ Yes (most important callback)

Action: Mark order/payment as completed in your system.

failed

When: Processing error occurred or bank rejected transfer

What it means: ❌ Transfer unsuccessful. Funds automatically returned to sender. Final status.

Callback: ✅ Yes

Action: Log failure reason, notify user, offer to retry with corrected details.

rejected

When: User manually declined transfer in confirmation page

What it means: ❌ User refused to approve. Money not transferred. Final status.

Callback: ✅ Yes

Action: Mark as cancelled, offer alternative payment method. Don't retry automatically.

revoked

When: Client cancelled transfer via API (DELETE /transfer/rest/v1/transfers/{id})

What it means: ❌ Transfer cancelled by your system. Money not transferred. Final status.

Revocable statuses: new, waiting, waiting_funds, waiting_registration, waiting_password, reserved

Cannot revoke: done, failed, rejected, revoked

Callback: ✅ Yes

Status Transition Rules

From Status	Can Transition To
new	reserved, waiting, waiting_password, revoked
waiting	waiting_funds, waiting_registration, waiting_password, reserved, rejected, revoked
waiting_funds	reserved, failed, revoked
waiting_registration	waiting_password, reserved, revoked
waiting_password	reserved, failed, revoked
reserved	done, failed, revoked
done, failed, rejected, revoked	❌ None (final statuses)

Handling Status Changes

Use Callbacks (Recommended):

• Set callback URL when creating transfer
• Handle all possible statuses in your webhook endpoint
• Return HTTP 200 to acknowledge receipt

Status Polling (Alternative):

• Use only if callbacks not feasible
• Check final statuses: done, failed, rejected, revoked
• Implement exponential backoff to avoid rate limits

Common Scenarios

Simple Paysera-to-Paysera Transfer:

Create → new → reserved → done

Transfer Requiring User Confirmation:

Create → new → waiting → reserved → done

Transfer with Insufficient Funds:

Create → new → waiting_funds → reserved (when funds added) → done

Transfer with Unregistered Beneficiary:

Create → new → waiting_registration → reserved (when registered) → done

Client Cancels Transfer:

Create → new → reserved → revoked (via DELETE API)

Related Documentation

• Callbacks (Webhooks) - Set up real-time notifications
• Creating a Transfer - Complete workflow
• Error Codes - Handle errors
• API Fundamentals - Core API concepts