Skip to main content
A PaymentRequest defines who is paying, who is receiving, the amount and how the payment should be processed. It is used in both the authorisation step (POST /payment-auth-requests) and the execution step (POST /payments). The object structure is consistent across countries and payment types. However, required fields vary by country, standard and individual institution. If you are using Hosted Pages, you still provide payee details and payment parameters in the request that creates the Hosted session. Hosted then handles bank selection, payer authorisation, and SCA on the user’s side. The field details below apply to both integration approaches. A UK domestic payment needs a sort code and account number. A German SEPA payment needs an IBAN. Some European banks require payer details, others do not.

​
PaymentRequest structure

FieldTypeDescription
typestringPayment type (DOMESTIC_PAYMENT, INTERNATIONAL_PAYMENT, etc.)
paymentIdempotencyIdstringYour unique reference. Prevents duplicates.
amount.amountnumberPayment amount
amount.currencystringThree-letter currency code (GBP, EUR)
referencestringPayment description visible on bank statements
payee.namestringRecipient name
payee.accountIdentifications[]arrayRecipient account details (SORT_CODE, IBAN, etc.)
payee.addressobjectRecipient address (sometimes required)
payer.namestringSender name (sometimes required)
payer.accountIdentifications[]arraySender account details (sometimes required)
payer.addressobjectSender address (sometimes required)

​
Payment types

Your ScenarioPayment TypeKey Consideration
UK to UK, standard speedSingle Domestic PaymentUses Faster Payments
EU to EU (same or different country), eurosSingle Domestic PaymentRouted via SEPA
EU to EU, euros, instantSingle Domestic Instant PaymentSEPA Instant (10 seconds). Bank may charge extra.
Cross-border, non-euro or non-SEPASingle International PaymentRequires BIC. Higher fees, slower.
Future-dated paymentSingle Domestic Scheduled PaymentSpecify execution date
Recurring fixed paymentSingle Domestic Periodic PaymentStanding order in UK. Specify frequency.
Multiple payments at onceBulk paymentUse separate authorisation endpoint
Variable recurring (VRP)Separate VRP flowSee VRP documentation
Always check the institution’s supported features first using GET /institutions/{id}. Not all banks support all payment types. See Payment Features.
For detailed SEPA/domestic/international decision logic, see: European Payments Guide

​
Payee details by country

Payer CountryPayee CountryCurrencyPayee Account ID RequiredPayee Name
UKUKGBPSORT_CODE + ACCOUNT_NUMBERRequired
Any SEPAAny SEPAEURIBANRequired
AnyEU/EEA (international)AnyIBAN + BICRequired

​
Country-specific examples

"payee": {
  "name": "Jane Smith",
  "accountIdentifications": [
    { "type": "SORT_CODE", "identification": "123456" },
    { "type": "ACCOUNT_NUMBER", "identification": "12345678" }
  ]
}

​
Payer details

Payer requirements vary by country and institution. UK: Payer details are usually not required. The bank knows the payer from the consent. Europe (Berlin Group banks): Payer IBAN is often required. The bank needs to know which account to debit. Some European banks also require: Payer name, payer address.
Payer requirements vary by institution, not just by country. Only request payer details when the institution requires them, as asking for unnecessary information adds friction to the user experience. For returning users, consider saving and pre-populating payer details to streamline subsequent payments. For institution-specific requirements, check the Yapily Console.

​
Payer examples

// Payer can be omitted for most UK payments.
// The bank determines the payer from the consent.
For institution-specific field requirements, log in to the Yapily Console to view detailed constraints.

​
Reference field

The reference field is the payment description visible on bank statements. This is what your customer will see when they review their transaction history. Character limits vary by institution, from as low as 18 characters to 140. Some banks silently truncate long references, others reject the payment outright. Recommendation: Keep references under 18 characters for maximum compatibility, or check institution-specific constraints in the Yapily Console.

​
Idempotency

The paymentIdempotencyId prevents duplicate payments if your request is retried. How it works:
  • Must be unique per payment attempt
  • If the same ID is sent twice, Yapily returns the existing payment instead of creating a new one
  • Generate a UUID for each payment attempt

​
Complete examples

{
  "applicationUserId": "user-123",
  "institutionId": "modelo-sandbox",
  "callback": "https://your-app.com/callback",
  "paymentRequest": {
    "type": "DOMESTIC_PAYMENT",
    "paymentIdempotencyId": "550e8400-e29b-41d4-a716-446655440000",
    "amount": {
      "amount": 10.00,
      "currency": "GBP"
    },
    "reference": "Invoice 1234",
    "payee": {
      "name": "Jane Smith",
      "accountIdentifications": [
        { "type": "SORT_CODE", "identification": "123456" },
        { "type": "ACCOUNT_NUMBER", "identification": "12345678" }
      ]
    }
  }
}

​
Common pitfalls

The following issues are frequently encountered when building payment requests:
  • Payment rejected for missing payer details: Some European banks require payer IBAN or other details. Check institution requirements in the Yapily Console before building your payment form. Only collect what is needed to minimise friction.
  • Reference too long: Keep under 18 characters for maximum compatibility across institutions.
  • Wrong payment type for SEPA: If both accounts are in SEPA countries and currency is EUR, use DOMESTIC_PAYMENT, not INTERNATIONAL_PAYMENT. Exception: NatWest Group requires INTERNATIONAL_PAYMENT for SEPA. See European Payments.
  • Feature not supported: Always check GET /institutions/{id} features array before initiating. See Payment Features.
  • IBAN format rejected: IBAN formats are country-specific (different length and prefix per country). Validate format before sending.
  • Duplicate payment created: Always include a unique paymentIdempotencyId. If you retry without one, you may create duplicate payments.