Getting Started with Payins

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 Payin: Make your first API call
4. Handle Customer Flow: Guide customers through authorization
5. Monitor and Test: Check payin 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 YOUR_OAUTH_TOKEN",
  "Content-Type": "application/json",
  "Idempotency-Key": "YOUR_IDEMPOTENCY_KEY",
  "Signature": "YOUR_SIGNATURE"
}

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 PayinCopy URL

curl --location --request POST 'https://api.banked.com/v3/payins' \
--header 'Authorization: Bearer YOUR_OAUTH_TOKEN' \
--header 'Content-Type: application/json' \
--header 'Idempotency-Key: YOUR_IDEMPOTENCY_KEY' \
--header 'Signature: YOUR_SIGNATURE' \
--data-raw '{
  "amount": 100,
  "currency": "AUD",
  "checkout_config": {
    "redirect_url": "http://example.com/"
  },
  "payment_identification": {
    "end_to_end_identification": "order123"
  },
  "ultimate_creditor": {
    "identity_type": "PARTY_IDENTIFICATION",
    "name": "Payments R Us"
  },
  "remittance_information": {
    "unstructured": "Description value which displays in the payers internet banking",
    "structured": {
      "creditor_reference_information": {
        "reference": "InternalMerchantID123"
      }
    }
  },
  "processing_method": {
    "method_type": "ACCOUNT_TO_ACCOUNT",
    "creditor_account": {
      "account_type": "BANKED_BANK_ACCOUNT_ENTITY",
      "bank_account_id": "YOUR_BANK_ACCOUNT_ID"
    }
  }
}'

curl --location --request POST 'https://api.banked.com/v3/payins' \
--header 'Authorization: Bearer YOUR_OAUTH_TOKEN' \
--header 'Content-Type: application/json' \
--header 'Idempotency-Key: YOUR_IDEMPOTENCY_KEY' \
--header 'Signature: YOUR_SIGNATURE' \
--data-raw '{
  "amount": 100,
  "currency": "AUD",
  "payment_identification": {
    "end_to_end_identification": "order123"
  },
  "ultimate_creditor": {
    "identity_type": "PARTY_IDENTIFICATION",
    "name": "Payments R Us"
  },
  "remittance_information": {
    "structured": {
      "creditor_reference_information": {
        "reference": "InternalMerchantID123"
      }
    }
  },
  "processing_method": {
    "method_type": "MANDATE",
    "mandate": {
      "token": "YOUR_MANDATE_TOKEN"
    },
    "creditor_account": {
      "account_type": "BANKED_BANK_ACCOUNT_ENTITY",
      "bank_account_id": "YOUR_BANK_ACCOUNT_ID"
    }
  },
  "actions": [
    {
      "action_type": "initiate_attempt"
    }
  ]
}'

Step 4: Customer Authorization FlowCopy URL

Once you create a payin, customers complete the authorization process:

Step 5: Monitor Payin StatusCopy URL

You can check the payin status at any time:

curl --location --request GET 'https://api.banked.com/v3/payins/{payin_id}' \
--header 'Authorization: Bearer YOUR_OAUTH_TOKEN' \
--header 'Signature: YOUR_SIGNATURE'

The payin status is returned in the status_details.status field of the response.

Payin StatusesCopy URL

• CREATED: Payin created, 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
• CANCELED: Payin was canceled

Testing simulated test scenarios (Mock Bank)Copy URL

See the Simulator (Mockbank) page here to see how do simulate approved and declined test scenarios.

Handle Redirect URLsCopy URL

Set a redirect_url in your payin request to return the customer to your site after the checkout journey completes. Banked will redirect the customer here for all outcomes — success, failure, and cancellation.

{
  "redirect_url": "https://yoursite.com/payment/redirect"
}

Banked appends the following query parameters to the redirect URL:

• payment_id: Unique ID of the payin
• payment_result: Status of the payin (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 payin status updates:

Key webhook events:

• payin_initiated: Payin authorized by customer
• payin_sent: Payin successful
• payin_failed: Payin failed
• payin_pending: Payin is processing
• payin_canceled: Payin was canceled

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

Payin ActionsCopy URL

The payin object includes a next_actions field that dynamically surfaces which actions are available based on the payment's current state. Check this field before calling the actions endpoint — attempting an action that isn't listed will return an invalid_action error.

next_actions has two arrays:

• completion_paths — actions that move the payment forward toward completion
• alternate_paths — alternative actions available alongside the primary completion path

The following actions are available on a payin:

Payin CancellationCopy URL

If you're 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 cancel the payin to avoid the risk of the payment being processed at a later date.

curl --location --request POST 'https://api.banked.com/v3/payins/{payin_id}/actions' \
--header 'Authorization: Bearer YOUR_OAUTH_TOKEN' \
--header 'Content-Type: application/json' \
--header 'Idempotency-Key: YOUR_IDEMPOTENCY_KEY' \
--header 'Signature: YOUR_SIGNATURE' \
--data-raw '{
  "action_type": "cancel_payment"
}'

Payin RetryCopy URL

Payments made against an active mandate that fail due to a recoverable condition may be reattempted without creating a new payin — check next_actions.completion_paths for retry_payment.

curl --location --request POST 'https://api.banked.com/v3/payins/{payin_id}/actions' \
--header 'Authorization: Bearer YOUR_OAUTH_TOKEN' \
--header 'Content-Type: application/json' \
--header 'Idempotency-Key: YOUR_IDEMPOTENCY_KEY' \
--header 'Signature: YOUR_SIGNATURE' \
--data-raw '{
  "action_type": "retry_payment"
}'

For retry limits, retryable error codes, and guidance on when to retry, see Retryable Errors.

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 creditor 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

• Use clear, descriptive payment references
• Set appropriate redirect URLs with meaningful content
• Provide alternative payment methods as fallback

Next StepsCopy URL

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

• Payin Webhooks - Set up real-time notifications
• Payin Status - Understand all possible payin statuses
• Payin Errors - Comprehensive error handling guide