Developer

Partner Docs

Merchant Docs

Common Payment Scenarios

This guide provides practical examples and implementation patterns for the most common payment scenarios using Banked's account-to-account payment platform. Each scenario includes complete code examples, regional considerations, and best practices.

New to Banked Payments? Start with our Getting Started Guide for step-by-step setup instructions.

This guide will walk you through these key steps:

  1. Understanding Payment Types: Single payments vs. mandated payments
  2. Single Payment Scenarios: E-commerce, invoices, donations, service bookings
  3. Mandated Payment Scenarios: One-click checkout, express mobile payments, subscriptions, marketplace vendor payments
  4. Implementation Best Practices: Expiration strategies, webhook processing, and action handling
  5. Testing Strategies: How to test payment flows in sandbox

When to Use Each Payment Type

Choose the right payment type based on your business model and customer experience goals:

Single Payments (Pay-ins)

Best for: E-commerce checkouts, invoice payments, service bookings, donations

  • Customer experience: One-time authorization per payment
  • Settlement: Fast (minutes to hours depending on region)
  • Regions: UK, EU, Australia
  • Use when: Each payment requires individual customer approval

Mandated Payments

Best for: Subscriptions, one-click checkout, recurring billing

  • Customer experience: Authorize once, pay many times without interaction
  • Settlement: Fast (minutes to hours)
  • Regions: Australia (other regions coming soon)
  • Use when: You need recurring payments or frictionless repeat purchases

Single Payment Scenarios

Scenario 1: E-commerce Checkout

Use Case: Customer purchasing products from your online store

Implementation Strategy: Create payment session during checkout process and redirect to Banked for authorization.

United Kingdom Implementation

Settlement: Faster Payments - typically instant (within seconds to minutes) Business Hours: 24/7 availability, though some banks may have brief maintenance windows

json
POST /v2/payment_sessions
{
  "amount": 4999,
  "currency": "GBP",
  "reference": "ORDER-2024-001234",
  "external_reference": "shop_order_xyz789",
  "description": "Online store purchase - 2 items",
  "error_url": "https://yourstore.com/checkout/payment-failed",
  "success_url": "https://yourstore.com/checkout/payment-success",
  "payee": {
    "name": "Your Online Store Ltd",
    "account_number": "12345678",
    "sort_code": "123456"
  },
  "payer": {
    "name": "John Smith",
    "email": "john.smith@example.com"
  },
  "metadata": {
    "customer_id": "cust_12345",
    "order_id": "order_xyz789",
    "cart_items": "2",
    "shipping_method": "standard"
  }
}

European Union Implementation

Settlement: SEPA Instant (where available) - within 10 seconds, otherwise standard SEPA - next business day Business Hours: SEPA Instant available 24/7, standard SEPA processes on business days

json
POST /v2/payment_sessions
{
  "amount": 4999,
  "currency": "EUR",
  "reference": "ORDER-2024-001234",
  "external_reference": "shop_order_xyz789",
  "description": "Online store purchase - 2 items",
  "error_url": "https://yourstore.com/checkout/payment-failed",
  "success_url": "https://yourstore.com/checkout/payment-success",
  "payee": {
    "name": "Your Online Store GmbH",
    "account_identifier": "DE89370400440532013000",
    "identifier_type": "IBAN"
  },
  "payer": {
    "name": "Hans Mueller",
    "email": "hans.mueller@example.com"
  },
  "metadata": {
    "customer_id": "cust_12345",
    "order_id": "order_xyz789",
    "cart_items": "2",
    "shipping_method": "standard"
  }
}

Australia Example

json
POST /v2/payment_sessions
{
  "amount": 4999,
  "currency": "AUD",
  "reference": "ORDER-2024-001234",
  "external_reference": "shop_order_xyz789",
  "description": "Online store purchase - 2 items",
  "error_url": "https://yourstore.com/checkout/payment-failed",
  "success_url": "https://yourstore.com/checkout/payment-success",
  "payee": {
    "name": "Your Online Store Pty Ltd",
    "account_identifier": "123456789",
    "secondary_identifier": "062001",
    "identifier_type": "BSBAccountNumber"
  },
  "payer": {
    "name": "Sarah Wilson",
    "email": "sarah.wilson@example.com"
  },
  "metadata": {
    "customer_id": "cust_12345",
    "order_id": "order_xyz789",
    "cart_items": "2",
    "shipping_method": "standard"
  }
}

Regional Account Formats: Each region uses different account identifier formats. See the Getting Started Guide for complete regional configuration details.

Integration Options

Choose your preferred customer experience:

Hosted Checkout

Complete hosted payment experience

Embedded Checkout

Seamless in-page payment flow

Scenario 2: Invoice Payment

Use Case: B2B customer paying an outstanding invoice

Implementation Strategy: Generate payment session for invoice with appropriate expiration, then send payment link to customer via email or customer portal.

json
POST /v2/payment_sessions
{
  "amount": 150000,
  "currency": "GBP",
  "reference": "INV-2024-5678",
  "external_reference": "invoice_5678_payment",
  "description": "Professional services - Invoice INV-2024-5678",
  "error_url": "https://yourcompany.com/invoices/payment-failed?invoice=5678",
  "success_url": "https://yourcompany.com/invoices/payment-success?invoice=5678",
  "expires_at": "2024-07-15T23:59:59Z",
  "payee": {
    "name": "Professional Services Ltd",
    "account_number": "87654321",
    "sort_code": "654321"
  },
  "payer": {
    "name": "Client Company Ltd",
    "email": "accounts@clientcompany.com"
  },
  "metadata": {
    "invoice_number": "INV-2024-5678",
    "due_date": "2024-07-15",
    "client_id": "client_456",
    "payment_terms": "net_30"
  }
}

Key Features:

  • Set expires_at aligned with invoice payment terms
  • Include invoice number in both reference and metadata for reconciliation
  • Use business-appropriate success/error URLs that display payment status
  • Store invoice details in metadata for automated accounting integration

Scenario 3: Charitable Donations

Use Case: Accepting charitable donations with simple, fast checkout

Implementation Strategy: Streamlined payment flow with minimal required information to reduce donor friction.

json
POST /v2/payment_sessions
{
  "amount": 2500,
  "currency": "GBP",
  "reference": "DONATION-20240601-001",
  "external_reference": "donor_campaign_xyz",
  "description": "Charity donation - Save the Environment Campaign",
  "error_url": "https://charity.org/donate/failed",
  "success_url": "https://charity.org/donate/thank-you",
  "payee": {
    "name": "Save Environment Charity",
    "account_number": "11223344",
    "sort_code": "112233"
  },
  "payer": {
    "name": "Sarah Johnson",
    "email": "sarah.johnson@example.com"
  },
  "metadata": {
    "campaign": "save_environment",
    "donor_id": "donor_789",
    "donation_type": "one_time",
    "anonymous": "false"
  }
}

Donation-Specific Considerations:

  • Keep checkout process simple and fast
  • Consider gift aid implications for UK donations
  • Store campaign information for reporting
  • Provide clear thank-you experience

Scenario 4: Service Booking Payment

Use Case: Customers paying for booked appointments or services

Implementation Strategy: Create payment session when service is booked, with booking details included.

json
POST /v2/payment_sessions
{
  "amount": 8500,
  "currency": "EUR",
  "reference": "BOOKING-SPA-20240615-14",
  "external_reference": "spa_appointment_456",
  "description": "Spa treatment booking - Premium package",
  "error_url": "https://luxuryspa.com/booking/payment-failed?booking=456",
  "success_url": "https://luxuryspa.com/booking/confirmed?booking=456",
  "payee": {
    "name": "Luxury Spa & Wellness",
    "account_identifier": "FR1420041010050500013M02606",
    "identifier_type": "IBAN"
  },
  "payer": {
    "name": "Marie Dubois",
    "email": "marie.dubois@example.com"
  },
  "metadata": {
    "booking_id": "booking_456",
    "service_date": "2024-06-15",
    "service_time": "14:00",
    "treatment_type": "premium_package",
    "therapist": "anna_smith"
  }
}

Mandated Payment Scenarios

Mandated payments are currently available in Australia with additional regions coming soon. These scenarios require active mandates to be set up first.

Mandated payments enable frictionless repeat transactions where customers authorize once and payments process automatically. Perfect for subscriptions, one-click checkout, and recurring billing.

Scenario 1: One-Click Checkout for Returning Customers

Use Case: Returning customers making repeat purchases without re-entering bank details

Implementation Strategy: Set up mandate during first purchase, then use for future one-click payments.

Step 1: Create One-Click Payment Mandate

json
POST /v2/mandates
{
  "currency": "AUD",
  "external_reference": "one_click_mandate_customer_123",
  "description": "One-click checkout mandate for returning customer",
  "destination": {
    "account_type": "banked_bank_account",
    "bank_account_id": "your_business_account_id",
    "ultimate_party": {
      "name": "Your Online Store Pty Ltd"
    }
  },
  "payment_terms": {
    "terms_type": "variable",
    "frequency": "adhoc",
    "max_amount": 500000,
    "count": 50
  },
  "validity_start_date": "2024-06-01",
  "validity_end_date": "2025-05-31",
  "metadata": {
    "customer_id": "customer_123",
    "payment_type": "one_click_checkout",
    "setup_reason": "faster_checkout"
  }
}

Step 2: Process One-Click Payment

json
POST /v2/payment_sessions
{
  "reference": "ORDER-2024-002468",
  "amount": 7999,
  "currency": "AUD",
  "description": "Online store purchase - One-click payment",
  "mandate": {
    "token": "mandate_token_from_step_1"
  },
  "actions": [
    {
      "action_type": "init_attempt",
      "payload": {
        "customer_ip_address": "203.0.113.1"
      }
    }
  ],
  "metadata": {
    "order_id": "order_002468",
    "customer_id": "customer_123",
    "payment_method": "one_click",
    "cart_items": "3"
  }
}

One-Click Checkout Benefits:

  • Faster checkout experience for returning customers
  • Higher conversion rates due to reduced friction
  • Customer doesn't need to re-authenticate with bank for each purchase
  • Suitable for repeat purchase scenarios

Scenario 2: Express Checkout for Mobile Apps

Use Case: Mobile app users making quick purchases with saved payment methods

Implementation Strategy: Set up mandate during app onboarding or first purchase for streamlined mobile payments.

Create Express Checkout Mandate

json
POST /v2/mandates
{
  "currency": "AUD",
  "external_reference": "mobile_express_customer_789",
  "description": "Express mobile checkout - Food delivery app",
  "destination": {
    "account_type": "banked_bank_account",
    "bank_account_id": "food_app_business_account",
    "ultimate_party": {
      "name": "Quick Eats Delivery Pty Ltd"
    }
  },
  "payment_terms": {
    "terms_type": "variable",
    "frequency": "adhoc",
    "max_amount": 20000,
    "count": 100
  },
  "validity_start_date": "2024-01-01",
  "validity_end_date": "2024-12-31",
  "metadata": {
    "customer_id": "customer_789",
    "platform": "mobile_app",
    "setup_context": "first_order"
  }
}

Process Express Mobile Payment

json
POST /v2/payment_sessions
{
  "reference": "FOOD-ORDER-20240615-789",
  "amount": 3250,
  "currency": "AUD",
  "description": "Food delivery order - Express checkout",
  "mandate": {
    "token": "mobile_mandate_token"
  },
  "actions": [
    {
      "action_type": "init_attempt",
      "payload": {
        "customer_ip_address": "203.0.113.25"
      }
    }
  ],
  "metadata": {
    "order_type": "food_delivery",
    "delivery_address": "123 Main St",
    "customer_id": "customer_789",
    "platform": "mobile_app"
  }
}

Scenario 3: Subscription Service

Use Case: Software subscription with automatic billing using pre-authorized mandates

Implementation Strategy: Set up mandate during subscription signup, then create automatic payments for billing cycles.

Step 1: Create Subscription Mandate

json
POST /v2/mandates
{
  "currency": "AUD",
  "external_reference": "subscription_mandate_user_123",
  "description": "Monthly SaaS subscription - Premium Plan",
  "destination": {
    "account_type": "banked_bank_account",
    "bank_account_id": "your_business_account_id",
    "ultimate_party": {
      "name": "SaaS Company Pty Ltd"
    }
  },
  "payment_terms": {
    "terms_type": "variable",
    "frequency": "monthly",
    "max_amount": 9900,
    "count": 12
  },
  "validity_start_date": "2024-06-01",
  "validity_end_date": "2025-05-31",
  "metadata": {
    "subscription_plan": "premium",
    "customer_id": "user_123",
    "billing_cycle": "monthly"
  }
}

Step 2: Process Monthly Subscription Payment

json
POST /v2/payment_sessions
{
  "reference": "SUB-202406-USER123",
  "amount": 9900,
  "currency": "AUD",
  "description": "Monthly subscription - Premium Plan (June 2024)",
  "mandate": {
    "token": "mandate_token_from_step_1"
  },
  "actions": [
    {
      "action_type": "init_attempt",
      "payload": {
        "customer_ip_address": "203.0.113.1"
      }
    }
  ],
  "metadata": {
    "billing_period": "2024-06",
    "subscription_id": "sub_123",
    "plan_type": "premium"
  }
}

Subscription Management Tips:

  • Set mandate validity for full subscription term or longer
  • Use clear billing period references for easier reconciliation
  • Store subscription metadata for customer support
  • Monitor failed payments and implement retry logic
  • Consider grace periods for failed payments before service suspension

Scenario 4: Marketplace Vendor Payments

Use Case: Marketplace platform enabling vendors to accept one-click payments from repeat customers

Implementation Strategy: Set up customer mandate that can be used across multiple vendors on the platform.

Step 1: Create Marketplace Customer Mandate

json
POST /v2/mandates
{
  "currency": "AUD",
  "external_reference": "marketplace_customer_mandate_456",
  "description": "Marketplace one-click payments - Premium customer",
  "destination": {
    "account_type": "banked_bank_account",
    "bank_account_id": "marketplace_platform_account",
    "ultimate_party": {
      "name": "Marketplace Platform Pty Ltd"
    }
  },
  "payment_terms": {
    "terms_type": "variable",
    "frequency": "adhoc",
    "max_amount": 100000,
    "count": 200
  },
  "validity_start_date": "2024-06-01",
  "validity_end_date": "2025-05-31",
  "metadata": {
    "customer_id": "customer_456",
    "platform": "marketplace",
    "customer_tier": "premium",
    "setup_date": "2024-06-01"
  }
}

Step 2: Process Marketplace Payment Using Mandate

json
POST /v2/payment_sessions
{
  "reference": "VENDOR-PURCHASE-20240615-001",
  "amount": 12750,
  "currency": "AUD",
  "description": "Marketplace purchase - Artisan crafts",
  "mandate": {
    "token": "marketplace_mandate_token"
  },
  "actions": [
    {
      "action_type": "init_attempt",
      "payload": {
        "customer_ip_address": "203.0.113.50"
      }
    }
  ],
  "metadata": {
    "vendor_id": "vendor_123",
    "product_category": "crafts",
    "customer_id": "customer_456",
    "marketplace_fee": "1275"
  }
}

Implementation Best Practices

Payment Session Expiration Strategy

Set appropriate expiration times based on your payment scenario and customer behavior patterns:

json
{
  "expires_at": "2024-07-15T23:59:59Z"  // Example: Invoice payment
}

Recommended Expiration Times:

  • E-commerce: 24-48 hours
  • Invoices: Match payment terms (e.g., 30 days)
  • Services: Until service date
  • Donations: No expiration or long term

Webhook Processing for Different Scenarios

Universal Webhook Handler:

javascript
function handlePaymentWebHook(webHookData) {
  const { event, data } = webHookData;

  switch (event) {
    case 'payment_session.sent':
      // Payment successful - update order/invoice status
      processSuccessfulPayment(data);
      break;

    case 'payment_session.failed':
      // Payment failed - handle based on scenario
      processFailedPayment(data);
      break;

    case 'mandate.active':
      // Mandate ready for one-click payments
      enableOneClickCheckout(data);
      break;

    default:
      console.log(`Unhandled webhook event: ${event}`);
  }
}

Interacting with payments through actions

Changes to existing payment sessions happen by taking actions on them. Actions are specific operations that can be performed on a payment session to change its state or trigger certain behaviors.

Taking an action

To take an action on a payment session, you need to send a POST request to the /actions endpoint with the action type and any required payload.

In order to know which are the actions you can take on a payment session, you can check the next_actions field in the payment session response. This field contains a list of possible actions and their required input. The ones in completion_paths are actions required to be taken to move the payment closer to successful settlement. The ones in alternate_paths are optional actions that can be taken to change the payment session state.

Some actions are asynchronous and will require you to poll the action status after you take them. The action status can be checked by sending a GET request to the /actions/{id} endpoint.

The possible states of an action are:

  • in_progress: The action is being processed
  • completed: The action has been successfully completed
  • failed: The action has failed for some reason

Canceling a payment session

To cancel a payment session, you have to create a cancel action:

bash
curl --location --request POST 'https://api.banked.com/v2/payment_sessions/{id}/actions' \
--header 'Authorization: Basic base64(YOUR_API_KEY:YOUR_API_SECRET)' \
--header 'Content-Type: application/json' \
--header 'Idempotency-Key: unique-request-id-123' \
--data-raw '{
  "action_type": "cancel_payment"
}'

Testing Strategies

Scenario-Based Testing

E-commerce Testing Checklist:

  • [ ] Successful payment flow
  • [ ] Failed payment handling
  • [ ] Customer abandonment (no bank selection)
  • [ ] Expired payment session
  • [ ] Invalid customer data

One-Click Checkout Testing Checklist:

  • [ ] Mandate creation and activation
  • [ ] First one-click payment
  • [ ] Subsequent one-click payments
  • [ ] Failed one-click payment handling
  • [ ] Mandate expiration scenarios

Testing with Mock Bank

For testing with mock bank accounts see our Testing with Mock Bank section.

Next Steps

After implementing these common scenarios, explore:

For specific implementation questions or regional requirements, contact Banked Support.

Next

Payment States

Previous

Getting Started with Payments

© 2025 Banked Ltd.

Dark Theme
PrivacyTerms