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 e-commerce or 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)
• Access to the Bank account Ids that have been setup for you (create account here)
• 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": "Bearer <OAuth_short_lived_scoped_token>",
  "Content-Type": "application/json",
  "Idempotency-Key": "unique-request-uuid"
}

Test Bank AccountCopy URL

For test payments use the test bank account id provided to you by our support team.

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:

Step 3: Create Your First PaymentCopy URL

curl --location --request POST 'https://api.banked.com/v2/payment_sessions' \
--header 'Authorization: Bearer <OAuth_short_lived_scoped_token>' \
--header 'Content-Type: application/json' \
--header 'Idempotency-Key: unique-request-id-123' \
--data-raw '{
  "currency": "AUD",
  "error_url": "http://example.com/error",
  "success_url": "http://example.com/success",
  "reference": "Order123",
  "amount": 100,
  "description" : "Description value which displays in the payers internet banking",
  "payee": {
      "bank_account_id": "{{bank_account_id}}",
      "ultimate_party": {
          "name": "{{company_trading_name}}"
      }
  }
}'

curl --location --request POST 'https://api.banked.com/v2/payment_sessions' \
--header 'Authorization: Bearer <OAuth_short_lived_scoped_token>' \
--header 'Content-Type: application/json' \
--header 'Idempotency-Key: unique-request-id-123' \
--data-raw '{
  "reference": "Order123",
  "amount": 100,
  "mandate": {
    "token": "{{mandate_token_id}}"
  },
  "payee": {
    "bank_account_id": "{{bank_account_id}}",
    "ultimate_party": {
        "name": "{{company_trading_name}}"
    }
  },
  "actions": [
    {
      "action_type": "init_attempt"
    }
  ]
}'

Step 4: Customer Authorization FlowCopy URL

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

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: Bearer <OAuth_short_lived_scoped_token>'

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.

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.

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 Handling / Payment DeletionCopy 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

Payment DeletionCopy URL

If your using single payments and the payer doesn't proceed with the payment or if your website or application isn't proceeding with the payment then you should delete the payment to avoid the risk of the payment being processed at a later date.

curl --location --request DELETE 'https://api.banked.com/v2/payment_sessions/{payment_id}' \
--header 'Authorization: Bearer <OAuth_short_lived_scoped_token>' \
--header 'Content-Type: application/json' \

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:

• Payment Webhooks - Set up real-time notifications
• Payment States - Understand all possible payment states
• Payment Errors - Comprehensive error handling guide