Getting Started with Confirmation of Payee

This guide walks you through running a Confirmation of Payee (CoP) verification against a bank account instrument. If you're new to CoP, start with the Confirmation of Payee overview for an introduction to how it works and its benefits.

1. Prerequisites: What you need before starting
2. Create a Payment Instrument: Register the recipient's bank account
3. Initiate CoP Verification: Trigger the name check
4. Receive the Result: Handle the webhook or poll for the result
5. Interpret the Result: Understand what each outcome means
6. Go Live with confidence

Step 1: PrerequisitesCopy URL

What You'll NeedCopy URL

Before initiating a CoP verification, ensure you have:

• Banked merchant account with CoP enabled - 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 CoP 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

CoP is run against a stored payment instrument. If you haven't created one yet, follow the Payment Instruments guide first:

Once you have an instrument, save the payment_instrument_id to use in the next step.

Step 3: Initiate CoP VerificationCopy URL

Call the verification endpoint with method: "cop":

curl --location --request POST 'https://api.banked.com/v3/payment_instruments/{instrument_id}/bank_account_verify' \
--header 'Authorization: Bearer <OAuth_short_lived_scoped_token>' \
--header 'Content-Type: application/json' \
--header 'Idempotency-Key: unique-request-id-456' \
--data-raw '{
  "method": "cop"
}'

Replace {instrument_id} with the payment_instrument_id from step 2.

ResponseCopy URL

A successful initiation returns 200 OK with no body. The verification runs asynchronously.

Re-running VerificationCopy URL

CoP can be run again on an existing instrument at any time. Common reasons to re-run include:

• Periodic checks: Re-verify every few months to confirm account details are still valid
• Retrying after a transient failure: If status was failed due to a transient error such as the verification service being temporarily unavailable, retry once the issue is resolved

If the account_owner_name on the instrument is wrong (typically indicated by a no_match result), note that payment instruments cannot be updated. Create a new instrument with the correct name and run verification against that instead.

If a verification is already in progress, the endpoint returns 409 Conflict. Wait for the current verification to complete before re-running.

Step 4: Receive the ResultCopy URL

CoP verification is asynchronous. You can receive the result via webhook or by polling.

{
  "id": "3a7e0e66-3b15-496a-8948-458a0a50488e",
  "type": "payment_instrument_bank_account_verification_completed",
  "version": "v3",
  "data_version": 1,
  "data": {
    "payment_instrument_id": "c3f87070-c2d8-4dbd-8943-7e280fc4c8fb",
    "on_behalf_of": "customer",
    "mode": "live",
    "created_at": "2025-12-02T16:34:00.000000Z",
    "updated_at": "2025-12-02T16:35:01.987654Z",
    "status": "active",
    "details": {
      "instrument_type": "bank_account",
      "currency": "AUD",
      "account_owner_name": "Jane Smith",
      "identifier": {
        "identifier_type": "bsb_account",
        "bsb": "123456",
        "account_number": "12345678"
      },
      "verification": {
        "status": "completed",
        "result": "match",
        "registered_account_name": "Jane Smith",
        "verified_at": "2025-12-02T16:35:01.987654Z",
        "method": "cop"
      }
    }
  }
}

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

{
  "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:35:01.987654Z",
  "details": {
    "instrument_type": "bank_account",
    "currency": "AUD",
    "account_owner_name": "Jane Smith",
    "identifier": {
      "identifier_type": "bsb_account",
      "bsb": "123456",
      "account_number": "12345678"
    },
    "verification": {
      "status": "completed",
      "result": "match",
      "registered_account_name": "Jane Smith",
      "verified_at": "2025-12-02T16:35:01.987654Z",
      "method": "cop"
    }
  }
}

Step 5: Interpret the ResultCopy URL

When status is completed, the result is either match, close_match, or no_match — each indicating whether to proceed with the payment or review the account details. A failed status means the verification could not be completed — for example, if the verification service was temporarily unavailable.

For detailed guidance on each outcome, recommended actions, and error codes:

Step 6: Go LiveCopy URL

Pre-Launch ChecklistCopy URL

• [ ] Confirm CoP is enabled on your merchant account
• [ ] Implement handling for all three result types: match, close_match, and no_match
• [ ] Implement handling for failed verification status
• [ ] Configure live webhook endpoints with signature verification
• [ ] Test the complete verification flow in the live environment

Best PracticesCopy URL

• Use webhooks rather than polling for verification results
• Store the payment_instrument_id against your customer records so the same instrument can be reused
• Implement a clear UX flow for close_match results that allows review before proceeding
• Never proceed with a payout on a no_match result without first confirming the account details directly with the recipient
• A failed status does not mean the account details are wrong — check latest_error.code to determine whether to retry or investigate further

Next StepsCopy URL

• Verification Results - Detailed guide to interpreting all CoP outcomes
• CoP Webhooks - Full webhook payload reference