Transfers

Queue overview

Based on instance-level configuration, the Internal Wire Transfer (IWT) will be placed in a queue where an external system can decide what should happen with the transfer.

The system will automatically return the transfer in cases where the destination account is:

• not found,

• closed, or

• blocked.

Once the transfer has been added to the queue, a webhook is sent to the external system carrying the token (identifier) of the queue record.

Retry policy

If the webhook is not acknowledged on the first attempt, the system will retry up to 3 more times.

An example of this webhook can be found on the TRANSACTION.SUSPENDED entry in our webhooks page.

List

{
    "code": 0,
    "data": {
        "items": [
            {
                "amount": 1.23,
                "currency": "EUR",
                "token": "d39ed40b-078c-494f-86de-1a86d4ab5f26",
                "reference": "Transfer",
                "merchant": "d39ed40b-078c-494f-86de-1a86d4ab5f26",
                "user": "d39ed40b-078c-494f-86de-1a86d4ab5f26",
                "account": "d39ed40b-078c-494f-86de-1a86d4ab5f26",
                "balance": "d39ed40b-078c-494f-86de-1a86d4ab5f26",
                "is_instant": false,
                "wires": {
                    "sender_name": "Company 123",
                    "sender_iban": "AT483200000012345864",
                    "sender_bank_name": "Bank 123",
                    "sender_bank_country": "AT",
                    "sender_bank_code": "RLNWATWWXXX",
                    "sender_sort_code": "123456",
                    "sender_account_number": "1234578",
                    "receiver_iban": "BG75PATC40022171680259",
                    "receiver_name": "John Doe",
                    "receiver_bank_name": "Paynetics AD",
                    "receiver_bank_country": "BG",
                    "receiver_bank_code": "PATCBGSFXXX",
                    "receiver_sort_code": "123456",
                    "receiver_account_number": "1234578",
                    "network": "string"
                }
            }
        ],
        "total_items": "integer"
    }
}

Paginated list of queue records waiting for an external decision.

Detail

{
    "code": 0,
    "data": {
        "amount": 1.23,
        "currency": "EUR",
        "token": "d39ed40b-078c-494f-86de-1a86d4ab5f26",
        "reference": "Transfer",
        "merchant": "d39ed40b-078c-494f-86de-1a86d4ab5f26",
        "user": "d39ed40b-078c-494f-86de-1a86d4ab5f26",
        "account": "d39ed40b-078c-494f-86de-1a86d4ab5f26",
        "balance": "d39ed40b-078c-494f-86de-1a86d4ab5f26",
        "is_instant": false,
        "wires": {
            "sender_name": "Company 123",
            "sender_iban": "AT483200000012345864",
            "sender_bank_name": "Bank 123",
            "sender_bank_country": "AT",
            "sender_bank_code": "RLNWATWWXXX",
            "sender_sort_code": "123456",
            "sender_account_number": "1234578",
            "receiver_iban": "BG75PATC40022171680259",
            "receiver_name": "John Doe",
            "receiver_bank_name": "Paynetics AD",
            "receiver_bank_country": "BG",
            "receiver_bank_code": "PATCBGSFXXX",
            "receiver_sort_code": "123456",
            "receiver_account_number": "1234578",
            "network": "string"
        }
    }
}

Fetch a single queue record by its token.

Process

{
    "code": 0
}

Decision endpoint — instructs the system to release the queued transfer to the destination account.

Return

{
    "return_reason": "beneficiary-account-closed"
}

{
    "code": 0
}

Decision endpoint — returns the funds to the originating account and removes the record from the queue.

Internal transfer

{
    "amount": 1.23,
    "currency": "EUR",
    "code": "string",
    "link": "520bec3b-8051-4a2b-928c-81d32b6bfa41",
    "reference": "Payment for goods",
    "reference2": "Items 1,2,3",
    "reference3": "Additional Info",
    "reference4": "Additional Info",
    "origin_of_funds": "salary",
    "description": "Merchant 123",
    "is_instant": false,
    "debtor": {
        "balance": "444f4f2c-6a05-43bb-93ab-7ab76ce5658c",
        "external_identifier": "123456789",
        "iban": "BG85PATC40021918158842",
        "sort_code": "123456",
        "account_number": "12345678",
        "address": "BG, Sofia, James Bouchier 76 A",
        "name": "John Doe",
        "country": "BG",
        "city": "Sofia",
        "postcode": "1000"
    },
    "creditor": {
        "balance": "444f4f2c-6a05-43bb-93ab-7ab76ce5658c",
        "external_identifier": "123456789",
        "iban": "BG85PATC40021918158842",
        "sort_code": "123456",
        "account_number": "12345678",
        "address": "BG, Sofia, James Bouchier 76 A",
        "name": "John Doe",
        "country": "BG",
        "city": "Sofia",
        "postcode": "1000"
    },
    "cop": "a5b968e4-ec62-4072-a37f-6b59e35a4e36",
    "vop": "a5b968e4-ec62-4072-a37f-6b59e35a4e36",
    "skip_fees": false,
    "value_date": "2026-10-01"
}

{
    "code": 0,
    "data": {
        "transaction": "8b06d551-5453-48e5-842c-c1e2d969da84",
        "trn_status": 0
    }
}

Use an internal transfer to move funds between two accounts or cards managed within the Paynetics ecosystem. This is the preferred option when both the debtor and creditor are internal Paynetics entities and can be identified using internal references such as balance identifiers.

Typical use cases

• Wallet-to-wallet transfer
• Transfer between two users on the same platform
• Transfer between internal balances
• Card / account movement within the same Paynetics program

Characteristics

• Processed as an internal Paynetics transfer
• Typically real-time
• Does not require external bank routing
• Usually identified by internal account references rather than external bank details

Notes

• Use balance as the identifier whenever both parties are Paynetics-managed.
• Use external_identifier to identify a debtor or creditor account / card.
• cop, vop, and is_instant are not typically needed for internal transfers.
• A successful response returns a transaction identifier.

{
  "amount": 25.50,
  "currency": "EUR",
  "reference": "Wallet transfer",
  "description": "Internal transfer between platform users",
  "debtor": {
    "balance": "444f4f2c-6a05-43bb-93ab-7ab76ce5658c",
    "external_identifier": "customer_001",
    "name": "John Doe",
    "country": "BG"
  },
  "creditor": {
    "balance": "555f4f2c-6a05-43bb-93ab-7ab76ce5658d",
    "external_identifier": "customer_002",
    "name": "Jane Doe",
    "country": "BG"
  }
}

SEPA transfer

Use a SEPA transfer to send a standard EUR bank transfer to an external bank account identified by IBAN. Suitable for regular EUR transfers within the SEPA area where instant execution is not required.

Typical use cases

• Supplier payments in EUR
• Payroll in EUR
• EUR payouts to customer bank accounts
• Standard bank transfer to a beneficiary in the SEPA zone

Characteristics

• External bank transfer
• currency must be EUR
• Creditor is typically identified by iban
• May require beneficiary name, address, and country
• Can optionally use Verification of Payee (vop) before sending

Notes

• Set currency to EUR.
• Use is_instant: false for standard SEPA.
• vop is recommended where beneficiary verification is required or supported.
• Additional beneficiary data may be required depending on compliance and network rules.

{
  "amount": 125.75,
  "currency": "EUR",
  "reference": "Invoice 2026-041",
  "reference2": "Customer payment",
  "description": "SEPA credit transfer",
  "origin_of_funds": "Salary",
  "is_instant": false,
  "debtor": {
    "balance": "444f4f2c-6a05-43bb-93ab-7ab76ce5658c",
    "iban": "BG85PATC40021918158842",
    "address": "BG, Sofia, James Bouchier 76 A",
    "name": "John Doe",
    "country": "BG"
  },
  "creditor": {
    "iban": "DE89370400440532013000",
    "address": "DE, Berlin, Alexanderplatz 1",
    "name": "Acme GmbH",
    "country": "DE"
  },
  "vop": "a5b968e4-ec62-4072-a37f-6b59e35a4e36"
}

SEPA Instant transfer

Use a SEPA Instant transfer to send an eligible EUR bank transfer for near real-time settlement. Use this option when the transfer is eligible for the SEPA Instant rail and immediate processing is required.

Typical use cases

• Urgent customer payout
• Real-time merchant settlement
• Emergency disbursement
• Instant EUR transfer to a verified beneficiary

Characteristics

• External EUR bank transfer
• Routed through SEPA Instant when eligible
• Uses the same transfer endpoint as standard SEPA
• Controlled by the is_instant flag

Notes

• Set currency to EUR.
• Set is_instant to true.
• Instant execution depends on beneficiary reachability, scheme support, and Paynetics program configuration.
• If a transfer cannot be routed as instant, handling depends on platform configuration and business rules.

{
  "amount": 15.00,
  "currency": "EUR",
  "reference": "Urgent payout",
  "description": "SEPA Instant transfer",
  "origin_of_funds": "Merchant settlement",
  "is_instant": true,
  "debtor": {
    "balance": "444f4f2c-6a05-43bb-93ab-7ab76ce5658c",
    "iban": "BG85PATC40021918158842",
    "address": "BG, Sofia, James Bouchier 76 A",
    "name": "Merchant 123",
    "country": "BG"
  },
  "creditor": {
    "iban": "FR7630006000011234567890189",
    "address": "FR, Paris, Rue Example 10",
    "name": "John Doe",
    "country": "FR"
  },
  "vop": "a5b968e4-ec62-4072-a37f-6b59e35a4e36"
}

FPS transfer

Use an FPS transfer to send a GBP domestic bank transfer to a UK beneficiary using sort code and account number. Suitable for UK domestic payouts and account-to-account transfers over the Faster Payments rail.

Typical use cases

• GBP supplier payments in the UK
• Domestic customer payouts
• UK account-to-account transfers
• Real-time or near real-time GBP disbursements

Characteristics

• Domestic UK transfer
• currency must be GBP
• Creditor is typically identified by sort_code + account_number
• Can use Confirmation of Payee (cop) before sending

Notes

• Set currency to GBP.
• Use sort_code and account_number for UK domestic routing.
• Use cop where Confirmation of Payee verification is required or recommended.
• Do not use is_instant for FPS transfers.

{
  "amount": 85.40,
  "currency": "GBP",
  "reference": "Supplier payout",
  "reference2": "April settlement",
  "description": "FPS transfer",
  "origin_of_funds": "Business revenue",
  "debtor": {
    "balance": "444f4f2c-6a05-43bb-93ab-7ab76ce5658c",
    "sort_code": "123456",
    "account_number": "12345678",
    "address": "GB, London, 1 Example Street",
    "name": "Merchant 123 Ltd",
    "country": "GB"
  },
  "creditor": {
    "sort_code": "112233",
    "account_number": "87654321",
    "address": "GB, Manchester, 10 High Street",
    "name": "Supplier Ltd",
    "country": "GB"
  },
  "cop": "a5b968e4-ec62-4072-a37f-6b59e35a4e36"
}

Request fields & routing

Schema reference for the Transfers API: every field accepted on a transfer request, the debtor/creditor object shape, a side-by-side guide for picking the right transfer type, and the routing rules that determine the final rail.

Top-level fields

Debtor / creditor fields

The debtor and creditor objects may include one or more of the following fields depending on the transfer type.

Transfer type selection guide

Routing rules

The final transfer rail is determined by:

• Transfer currency
• Debtor and creditor account identifiers
• Whether is_instant is set for EUR transfers
• Paynetics program and network configuration
• Beneficiary validation and eligibility checks where applicable

Clients should provide the most appropriate identifiers for the intended transfer type and rely on Paynetics routing rules to determine the final execution path.

Best practices

• Use internal identifiers for transfers between Paynetics-managed accounts.
• Use IBAN for SEPA and SEPA Instant transfers.
• Use sort code + account number for UK domestic GBP transfers.
• Use VoP before SEPA transfers when beneficiary verification is required.
• Use CoP before FPS transfers when beneficiary verification is required.
• Provide name, address, and country for external transfers unless already known from the customer profile.
• Use is_instant: true only for eligible EUR instant transfers.

Confirmation of Payee

{
    "account_number": "Account Number",
    "sort_code": "Sort Code",
    "account_type": "Business|Personal",
    "account_name": "Account Owner Name",
    "secondary_reference": "Secondary Reference",
    "user": "User Token",
    "merchant": "Merchant Token"
}

{
    "code": 0,
    "data": {
        "token": "0ba5e81d-c43b-4008-b2d6-0d390f6f8c08",
        "report": {
            "match": "true",
            "reason": "Reason Code",
            "name": "Account Owner Name"
        }
    }
}

Confirmation of Payee (CoP) — verify that an account name and identifier match before initiating a transfer.

{
  "account_number": "12345678",
  "sort_code": "112233",
  "account_type": "Business",
  "account_name": "Supplier Ltd",
  "secondary_reference": "Supplier onboarding",
  "user": "User Token",
  "merchant": "Merchant Token"
}

Verification of Payee

{
    "iban": "GB82WEST12345698765432",
    "account_holder_name": "John Doe",
    "organisation_id": "549300DTUYXVMJXZNY75",
    "secondary_reference": "Secondary Reference",
    "user_token": "user_token",
    "merchant_token": "merchant_token"
}

{
    "code": 0,
    "data": {
        "vop_token": "0ba5e81d-c43b-4008-b2d6-0d390f6f8c08",
        "result": "MTCH",
        "matched_name": "Account Owner Name",
        "timestamp": "2026-03-12T10:22:11.123Z"
    }
}

Verification of Payee (VoP) — verify the legal name and account identifier of an EU SEPA payee before initiating a transfer.

{
  "iban": "DE89370400440532013000",
  "account.holder.name": "Acme GmbH",
  "secondary.reference": "Invoice payment",
  "user.token": "user_token",
  "merchant.token": "merchant_token"
}