Getting Started with Confirmation of Payee

This guide walks you through running a Confirmation of Payee (CoP) verification, starting with creating a bank account payment instrument for the recipient. 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 YOUR_OAUTH_TOKEN",
  "Content-Type": "application/json",
  "Idempotency-Key": "YOUR_IDEMPOTENCY_KEY",
  "Signature": "YOUR_SIGNATURE"
}

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 YOUR_OAUTH_TOKEN' \
--header 'Content-Type: application/json' \
--header 'Idempotency-Key: YOUR_IDEMPOTENCY_KEY' \
--header 'Signature: YOUR_SIGNATURE' \
--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",
      "verification": {
        "status": "completed",
        "verified_at": "2025-12-02T16:35:01.987654Z",
        "details": {
          "method": "cop",
          "result": "match",
          "can_receive_npp_payments": true,
          "can_send_npp_payments": true
        }
      }
    }
  }
}

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

{
  "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",
    "identifier": {
      "identifier_type": "bsb_account",
      "bsb": "123456",
      "account_number": "12345678",
      "account_owner_name": "Jane Smith"
    },
    "verification": {
      "status": "completed",
      "verified_at": "2025-12-02T16:35:01.987654Z",
      "details": {
        "method": "cop",
        "result": "match",
        "registered_account_owner_names": ["Jane Smith"],
        "can_receive_npp_payments": true,
        "can_send_npp_payments": true
      }
    }
  }
}

Step 5: Interpret the ResultCopy URL

When status is completed, details.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 cannot be completed — for example, if the verification service is temporarily unavailable, or the account is closed or cannot be found.

A completed verification may also include details.can_receive_npp_payments and details.can_send_npp_payments, which show whether the account can receive and send NPP payments.

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
• Check latest_error.code on a failed status to decide whether to retry or confirm the account details with the recipient
• Check can_receive_npp_payments before sending a payout; if it is false, confirm the account details with the recipient. See NPP Capabilities

Next StepsCopy URL

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