Split Payments offers merchants the ability to receive payments, in real-time, from their customers using a unique email PayId. We have a great article that describes the steps on how to set up a PayId associated with your account.

But, 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.

High-Level Flow

Step 1 - Listen to the relevant webhooks

Step 2 - Extract the relevant fields and decide if this payment should be rejected

Step 3 - Credit rejected Payment back to the sending account

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 any webhook events and which events should be expected in certain scenarios.

Setting Up Your Webhooks

Webhook Event Flows

Fig 1: Webhook events that you can subscribe to

Extract the relevant fields

Every webhook will include a body that contains various fields such as account id, BSB, account number, amount etc. Please find an example of the webhook body below.

{
"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": "payid123@gmail.com",
"npp_debtor_name": "Incoming Test Payment Contact",
"npp_debtor_legal_name": "Incoming Test Payment Contact",
"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 Incoming Test Payment Contact 014209 12345678 (Test Payment)",
"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.processing"
}
}

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.

Reject Chosen Payments To A PayId

If for any reason the payment cannot be accepted, the amount needs to be credited back to the account where the payment was generated from. To do so, you'll need to add the sending bank account as a contact and then create a payment for the relevant amount to that contact.

Retrieve Details Needed To Create From the Webhook

In order to create a contact, you'll need to retrieve the senders BSB, Account Number and Name from the webhook event.

This can be done by pulling required information from the metadata in the received credit.cleared webhook delivery.

"metadata":{
"npp_alias_type":"/EMAL",
"npp_alias_value":"payid123@gmail.com",
"npp_debtor_name":"Incoming Test Payment Contact",
"npp_debtor_legal_name":"Incoming Test Payment Contact",
"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"
}

Or by parsing the description field also sent in the credit.cleared webhook delivery

"description":"Payment from Incoming Test Payment Contact 014209 12345678 (Test Payment)"

The description is a string that is generated using the following format

"Payment from {debtor_name} {debtor_bsb} {debtor _account_number} ({user supplied description})"

Create The Contact

Once you have extracted all the relevant fields, you will need to add this bank account as a contact. This can be done using our Add A Contact endpoint. We don't use the email address supplied here for anything and is purely for your reconciliation needs. This means that you could supply a fake email if required.

Example Payload to the above-mentioned endpoint.

{
"name": "Hunter Thompson",
"email": "hunter@batcountry.com",
"branch_code": "014209",
"account_number": "12345678",
"metadata": {
"custom_key": "Custom string",
"another_custom_key": "Maybe a URL"
}
}

Paying This New Contact

You can now go ahead and make a payment to the contact you just added, by using our Make a Payment API endpoint. Ensure that the your_bank_account_id is the id related to the float account that the rejected payment was settled into.

Example Payload to the above-mentioned endpoint

{
"description": "Return Payment",
"matures_at": "2021-02-19T00:00:00Z",
"your_bank_account_id": "83623359-e86e-440c-9780-432a3bc3626f",
"payouts": [
{
"amount": 50,
"description": "Returing the Payment SB23094",
"recipient_contact_id": "48b89364-1577-4c81-ba02-96705895d457",
}
]
}


I hope this has helped, and if you have any further questions please contact us through the speech bubble in the corner of this screen.

Did this answer your question?