Getting Started with Payment Instruments

This guide walks you through creating and managing payment instruments with Banked. A payment instrument is a stored, reusable and verifiable payment method for receiving or disbursing funds on behalf of a customer or business.

This guide covers:

1. Prerequisites and Setup: Get your account and credentials ready
2. Create a Payment Instrument: Register a bank account
3. Retrieve a Payment Instrument: Fetch an existing instrument
4. Delete a Payment Instrument: Remove an instrument you no longer need
5. Next Steps: Verification and payouts

Step 1: Prerequisites and SetupCopy URL

What You'll NeedCopy URL

Before creating payment instruments, ensure you have:

• Banked merchant account - Create account here
• API credentials - Your API key and secret (authentication guide)
• Development environment - Set up for testing (environments guide)

API Request HeadersCopy URL

All payment instrument API requests require these headers:

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

Step 2: Create a Payment InstrumentCopy URL

Each instrument is created with an on_behalf_of field that records who the account belongs to — either a customer or your business — and a details object containing the account information. This lets you manage accounts independently and associate them with customer records for reuse across multiple payments.

Bank Account InstrumentsCopy URL

For BSB bank accounts, use bsb_account with a 6-digit BSB and a 6–10 digit account number:

curl --location --request POST 'https://api.banked.com/v3/payment_instruments' \
--header 'Authorization: Bearer <OAuth_short_lived_scoped_token>' \
--header 'Content-Type: application/json' \
--header 'Idempotency-Key: unique-request-id-123' \
--data-raw '{
  "on_behalf_of": "customer",
  "details": {
    "instrument_type": "bank_account",
    "currency": "AUD",
    "account_owner_name": "Jane Smith",
    "identifier": {
      "identifier_type": "bsb_account",
      "bsb": "123456",
      "account_number": "12345678"
    }
  }
}'

Associating with a CustomerCopy URL

Provide a customer_id to group the instrument and payments made using it under a customer record, enabling enhanced reporting on customer activity.

{
  "on_behalf_of": "customer",
  "customer_id": "{{customer_id}}",
  "details": { ... }
}

Successful ResponseCopy URL

A successfully created instrument returns a 201 status:

{
  "payment_instrument_id": "c3f87070-c2d8-4dbd-8943-7e280fc4c8fb",
  "on_behalf_of": "customer",
  "mode": "live",
  "status": "active",
  "created_at": "2025-12-02T16:34:00.000000Z",
  "updated_at": "2025-12-02T16:34:00.000000Z",
  "details": {
    "instrument_type": "bank_account",
    "currency": "AUD",
    "account_owner_name": "Jane Smith",
    "identifier": {
      "identifier_type": "bsb_account",
      "bsb": "123456",
      "account_number": "12345678"
    }
  }
}

Save the payment_instrument_id. You will need it for all subsequent operations on this instrument, such as retrieval, verification, deletion, or use in a payout.

Step 3: Retrieve a Payment InstrumentCopy URL

Retrieve the current state of an instrument:

curl --location --request GET 'https://api.banked.com/v3/payment_instruments/{instrument_id}' \
--header 'Authorization: Bearer <OAuth_short_lived_scoped_token>'

Replace {instrument_id} with the payment_instrument_id returned when the instrument was created.

ResponseCopy URL

{
  "payment_instrument_id": "c3f87070-c2d8-4dbd-8943-7e280fc4c8fb",
  "on_behalf_of": "customer",
  "mode": "live",
  "status": "active",
  "created_at": "2025-12-02T16:34:00.000000Z",
  "updated_at": "2025-12-02T16:34:00.000000Z",
  "details": {
    "instrument_type": "bank_account",
    "currency": "AUD",
    "account_owner_name": "Jane Smith",
    "identifier": {
      "identifier_type": "bsb_account",
      "bsb": "123456",
      "account_number": "12345678"
    }
  }
}

The status field indicates whether the instrument is usable. A newly created instrument is active; it becomes inactive if deactivated. Only active instruments can be used for payouts or verification.

If verification has been run against the instrument, a details.verification object will also be present. See the CoP Verification Results guide for details.

Step 4: Delete a Payment InstrumentCopy URL

When a recipient account is no longer valid or you no longer need a stored instrument, delete it:

curl --location --request DELETE 'https://api.banked.com/v3/payment_instruments/{instrument_id}' \
--header 'Authorization: Bearer <OAuth_short_lived_scoped_token>'

A successful deletion returns 204 No Content with no body.

Step 5: Next StepsCopy URL

With a bank account instrument created, verify the account owner's name before sending funds: