Getting Started with Payments

This guide walks you through everything you need to accept payments with Banked, from initial setup to processing your first transaction. Whether you're implementing single payments for e-commerce or recurring payments for subscriptions, this guide covers both payment types.

This guide will walk you through these key steps:

1. Prerequisites and Setup: Get your account and credentials ready
2. Choose Your Payment Type: Understand single payments vs mandates
3. Create Your First Payment: Make your first API call
4. Handle Customer Flow: Guide customers through authorization
5. Monitor and Test: Check payment status and test scenarios
6. Error Handling: Implement robust error handling
7. Go Live: Deploy to production with confidence

Step 1: Prerequisites and SetupCopy URL

Account RequirementsCopy URL

Before you begin, ensure you have:

• A Banked merchant account (create account here)
• Access to your API credentials (view authentication guide)
• A development environment for testing (development environment)

API CredentialsCopy URL

You'll receive two sets of credentials:

• Test Credentials: For sandbox environment testing
• Live Credentials: For production payments (available after due diligence)

API Request HeadersCopy URL

All API requests require these headers:

{
  "Authorization": "Basic <base64_encoded_credentials>",
  "Content-Type": "application/json",
  "Idempotency-Key": "unique-request-uuid"
}

Test Account DetailsCopy URL

Use these details for sandbox testing (UK region):

{
  "account_number": "12345678",
  "sort_code": "010203",
  "bank_name": "Mock Bank"
}

Base URLCopy URL

The base URL for all API requests in sandbox or production is:

https://api.banked.com

Step 2: Choose Your Payment TypeCopy URL

Banked supports two payment types, each suited for different scenarios and regions:

Single Payments (Pay-ins)Copy URL

Best for: E-commerce transactions, invoice payments, service fees, donations

• One-time, immediate payments
• Customer authorizes each payment individually
• Settles within minutes
• No ongoing authorization required

Mandate-based PaymentsCopy URL

Best for: Subscription services, membership fees, installment payments

• Ongoing payments using pre-authorized mandates
• Customer authorizes once, then payments process automatically
• Requires mandate setup before first payment
• Currently available in Australia, expanding to other regions

Step 3: Create Your First PaymentCopy URL

Option A: Single Payment ImplementationCopy URL

For one-time payments, create a payment session with complete payment details:

curl --location --request POST 'https://api.banked.com/v2/payment_sessions' \
--header 'Authorization: Basic base64(YOUR_API_KEY:YOUR_API_SECRET)' \
--header 'Content-Type: application/json' \
--header 'Idempotency-Key: unique-request-id-123' \
--data-raw `{
  "error_url": "http://example.com/error",
  "success_url": "http://example.com/success",
  "reference": "oioiWI09",
  "external_reference": "external-reference",
  "line_items": [
    {
      "name": "Jeans",
      "amount": 100,
      "amount_cents": 100,
      "amount_formatted": "£1.00",
      "quantity": 4,
      "currency": "GBP",
      "description": "Size 4 low-cut jeans."
    }
  ],
  "payee": {
    "name": "Gerald Wiley",
    "account_number": "12345678",
    "sort_code": "123456"
  },
  "payer": {
    "name": "John Doe",
    "email": "john.doe@banked.com"
  },
  "metadata": {
    "internal_identification": "custom_id"
  }
}`

Option B: Mandated Payments ImplementationCopy URL

For recurring payments, you'll need to set up a mandate first, then create payments against it.

curl --location --request POST 'https://api.banked.com/v2/payment_sessions' \
--header 'Authorization: Basic base64(YOUR_API_KEY:YOUR_API_SECRET)' \
--header 'Content-Type: application/json' \
--header 'Idempotency-Key: unique-request-id-123' \
--data-raw '{
  "reference": "oioiWI09",
  "external_reference": "external-reference",
  "line_items": [
    {
      "name": "Jeans",
      "amount": 100,
      "amount_cents": 100,
      "amount_formatted": "£1.00",
      "quantity": 4,
      "description": "Size 4 low-cut jeans.",
      "currency": "AUD"
    }
  ],
  "mandate": {
    "token": "550e8400-e29b-41d4-a716-446655440000"
  },
  "actions": [
    {
      "action_type": "init_attempt",
      "payload": {
        "customer_ip_address": "127.0.0.1"
      }
    }
  ]
}'

Key Differences:

• Mandate payments don't require payee or payer fields (inherited from mandate). You can still override them if needed if the mandate allows it.
• No customer interaction needed after mandate is active
• Must include init_attempt action to process automatically other you will have to manually initiate each payment using the actions endpoint.

Regional ConfigurationCopy URL

Banked supports payments in multiple regions, each with specific requirements for account formats and currencies. When creating payment sessions, you must configure the payee details according to the region where your business operates.

The API structure remains consistent across regions, but account formats and currencies differ. Here are the key differences:

United KingdomCopy URL

• Currency: GBP (amounts in pence)
• Payee: Sort code + Account number

{
  "currency": "GBP",
  "payee": {
    "name": "UK Business Ltd",
    "account_number": "12345678",
    "sort_code": "010203"
  }
}

European UnionCopy URL

• Currency: EUR (amounts in cents)
• Payee: IBAN

{
  "currency": "EUR",
  "payee": {
    "name": "EU Business GmbH",
    "account_identifier": "DE89370400440532013000",
    "identifier_type": "IBAN"
  }
}

AustraliaCopy URL

• Currency: AUD (amounts in cents)
• Payee:

{
  "currency": "AUD",
  "payee": {
    "name": "Australian Business Pty Ltd",
    "account_identifier": "123456789", // Account number
    "secondary_identifier": "062001", // BSB code
    "identifier_type": "BSBAccountNumber"
  }
}

Note: All amounts are in minor currency units (cents for USD/EUR, pence for GBP).

Step 4: Customer Authorization FlowCopy URL

Once you create a payment session, customers complete the authorization process:

For Single PaymentsCopy URL

1. Redirect your customer to the payment URL from your session response
2. Customer chooses their bank from the list of available providers
3. Customer logs into their bank to authorize the payment
4. Customer returns to your success or error URL depending on the payment status - see Redirects.

Choose your integration method:

Mandate Payments FlowCopy URL

For recurring payments using mandates, the flow is slightly different:

1. One-time setup: Customer authorizes recurring payments during mandate creation
2. Automatic processing: Future payments process without customer interaction
3. Notification only: Customers receive confirmation after payment

Choose your integration method:

Step 5: Monitor Payment StatusCopy URL

You can check the payment status at any time:

curl --location --request GET 'https://api.banked.com/v2/payment_sessions/{payment_id}' \
--header 'Authorization: Basic base64(YOUR_API_KEY:YOUR_API_SECRET)'

Key Payment StatesCopy URL

• awaiting_provider: Customer hasn't selected a bank yet
• awaiting_authorization: Customer is authorizing with their bank
• initiated: Bank has accepted the payment request
• pending: Payment is processing
• sent: Payment successful - money has left customer's account
• failed: Payment unsuccessful

Testing with Mock BankCopy URL

To simulate different payment scenarios, you can use the Mock Bank provider in the test environment. Visit the Banked Demo to see the payment flow in action.

UK, EU Payments:Copy URL

For payments processed in the UK or EU, you can use the Mock Bank provider to test various scenarios without needing real bank accounts. When you select Mock Bank as your payment provider you will be taken to a mock bank demo environment. At the bottom of the page you select the payment scenario you want to test by clicking 'Developer Options'.

Available test scenarios:

• Successful Payment (Default)
• Initiated
• Pending
• Pending With Delay
• Pending External Authorization
• Failure Generic
• Failure Expired
• Failure Declined
• Failure Insufficient Funds
• Settlement Incomplete

Australian Payments:Copy URL

For payments processed in Australia, you will need to use different account numbers to trigger different scenarios.

Always use BSB 111114 with one of the following account numbers:

Available test scenarios:

• Successful Payment: 050511
• Failed Payment: 050512
• Delayed Success: 303011

Handle Success and Error URLsCopy URL

Configure your success and error URLs to handle payment outcomes:

• Success URL: Process successful payment confirmation
• Error URL: Handle payment failures and guide customer to alternative payment methods

{
  "success_url": "https://yoursite.com/payment/success",
  "error_url": "https://yoursite.com/payment/error"
}

Banked append the following query parameters to the redirect url after the authorization journey is complete:

• payment_id: Unique ID of the payment session
• payment_result: Status of the payment (sent, failed, etc.)
• banked-checkout-result: Result of the Banked checkout process

Set Up Webhook Notifications (Recommended)Copy URL

Set up webhooks to receive real-time payment status updates:

Key webhook events:

• payment_session.initiated: Payment authorized by customer
• payment_session.sent: Payment successful
• payment_session.failed: Payment failed
• payment_session.pending: Payment is processing

Step 6: Error HandlingCopy URL

Error Handling Best PracticesCopy URL

• Always implement comprehensive error handling
• Provide clear error messages to users
• Log errors for debugging and monitoring
• Have fallback payment methods available
• Monitor payment success rates and set up alerts

Step 7: Go LiveCopy URL

Pre-Launch ChecklistCopy URL

Complete these steps before accepting live payments:

• [ ] Complete due diligence process with Banked
• [ ] Receive live API credentials
• [ ] Update API endpoints to use production environment
• [ ] Configure live webhook endpoints with proper security
• [ ] Update payee account details to live accounts
• [ ] Test complete payment flow in live environment
• [ ] Set up monitoring and alerting systems
• [ ] Verify all error handling works correctly

Best Practices SummaryCopy URL

SecurityCopy URL

• Always use HTTPS for all API requests
• Store API credentials securely (use environment variables)
• Implement webhook signature verification
• Use idempotency keys for all payment creation requests

User ExperienceCopy URL

• Include customer name and email in payer field for faster checkout
• Use clear, descriptive payment references
• Set appropriate success/error URLs with meaningful content
• Provide alternative payment methods as fallback

Next StepsCopy URL

Now that you've completed your first payment integration, explore these advanced features:

• Common Payment Scenarios - Learn about different payment use cases
• Payment Webhooks - Set up real-time notifications
• Payment States - Understand all possible payment states
• Payment Errors - Comprehensive error handling guide