DEVELOPER GUIDE

How To Return Receivable Contact Payments?

This article will guide you on on how to return PayID payments from contacts.

There can be times when the merchants may have a need to reject some payments coming through PayId. This article outlines the process that you need to follow in order to reject these payments.

Step 1 - Listen To Relevant Webhooks

By subscribing to our webhook events, you can monitor the status of every transaction and trigger the appropriate events. We have some great articles that explain how you can subscribe to webhook events and which events should be expected in certain scenarios.

Extract the relevant fields

In this instance, we are extracting the "ref": "C.518k"from the original Receivable PayID Payment event.

{
    "data": [
      {
        "ref": "C.518k",
        "type": "credit",
        "amount": 5,
        "status": "cleared",
        "bank_ref": "CT.4fqn",
        "category": "payout",
        "channels": ["float_account"],
        "metadata": {
          "npp_alias_type": "/EMAL",
          "npp_alias_value": "[email protected]",
          "npp_debtor_name": "Hunter Thompson",
          "npp_debtor_legal_name": "Hunter Thompson",
          "npp_payment_reference": "Test Payment",
          "npp_debtor_branch_code": "014209",
          "npp_payment_description": "Test Payment",
          "npp_debtor_account_number": "12345678",
          "npp_payment_transaction_id": "SPPYAU22XXXN20210219"
        },
        "cleared_at": "2021-02-19T05:25:32Z",
        "created_at": "2021-02-19T05:25:24Z",
        "matures_at": "2021-02-19T05:25:25Z",
        "parent_ref": "PR.18eu",
        "party_name": "PayID_contact",
        "description": "Payment from Hunter Thompsom 014209 12345678",                         
        "party_bank_ref ": DT.4 uyw ", 
        "party_nickname ":null,
        "bank_account_id": "17256c62-7787-4df4-b315-d31aa537b9ca",
        "current_channel": "float_account",
        "party_contact_id": "6014bb59-2b6a-49ae-8d5b-84962ab70305", 
        "status_changed_at": "2021-02-19T05:25:32Z"
      }
    ],
    "event": {
      "at": "2021-02-19T05:25:32Z",
      "who": {
        "account_id": "a2982a3b-1c9d-42bb-bb6d-ea79d3211fba",
        "account_type": "Account",
        "bank_account_id": "17256c62-7787-4df4-b315-d31aa537b9ca",
        "bank_account_type": "BankAccount"
      },
      "type": "credit.cleared"
    }
  }

These fields or a combination of fields can be used to identify if a payment can be accepted or needs to be rejected, based on your business rules. For example, you can reject payments from a particular BSB or Account number or set a pre-defined payment amount that will be accepted, anything other than that will be rejected by your system.

Step 2 - Issue a refund

Use the /credits/{credit_ref}/refunds endpoint to issue the refund.

{
    "amount": 100,
    "reason": "Amount Mismatch",
    "your_bank_account_id": "{{floatAccount}}",
     "channels": [
      "new_payments_platform", "direct_entry"
    ]
}

{
    "data": {
        "ref": "PRF.dijh",
        "for_ref": "C.5hoat8",
        "debit_ref": "D.5h5gz6",
        "your_bank_account_id": "019582ba-ef67-79be-a5c6-c42027936667",
        "channels": [
            "new_payments_platform",
            "direct_entry"
        ],
        "created_at": "2026-04-24T02:02:27Z",
        "amount": 100,
        "reason": "Amount Mismatch",
        "contacts": {
            "source_contact_id": "0197e849-a0c6-7a35-aad1-e68b771151af",
            "target_contact_id": "019dbd39-6239-7da6-a0ad-524d41b94c07"
        }
    }
}

Keep the PRF.xxxxfrom the api response to keep track of the transaction lifecyle in the webhook events.

Webhooks Event Flow

Refer to this article to learn more about the webhooks event flow when you make a payment.