API: How to issue a CUSTOMER_REFUND from money on account

[Matt Bradley]

I have a customer with a balance on account from previous overpayments using CUSTOMER_PAYMENT payments via the API.

When I attempt to issue a partial return of money using a CUSTOMER_REFUND, the payment fails with the error "There must be at least one item allocated."

I have also tried allocating the CUSTOMER_REFUND against the previous CUSTOMER_PAYMENT as follows:

 

(
    [transaction_type_id] => CUSTOMER_REFUND
    [contact_id] => 6dfe12a7f87142819ec192df13e8b834
    [bank_account_id] => 82c245dbfef049229734f5aeb289cd3e
    [date] => 2022-03-22T00:00:00+00:00
    [total_amount] => 500
    [reference] => DA29460
    [paymentmethod_id] => CASH
    [allocated_artifacts] => Array
        (
            [0] => Array
                (
                    [artefact_id] => 9f211ddf8b4e409dacaa3a7b2b85560c <-- ID of the previous CUSTOMER_PAYMENT
                    [amount] => 500.00
                )

        )

)

This also fails with the error "There must be at least one item allocated."

Is there something wrong with the "allocated_artifacts" node on the API? Whatever I try, this data appears to be ignored!

All suggestions welcome!

Edited March 24, 2022 by Matt Bradley

[Matt Bradley]

Ok. So changing the above to "allocated_artefacts" gets me a different error: "Couldn't find Sales Payable Artefact."

How do I "withdraw" funds from a customer overpayment?

[Matt Bradley]

Interestingly, if I try to send the above as a 'OTHER_RECEIPT_REFUND' then the API actually responds with a 500 error!

[Steel, Mark]

Hi Matt, thanks for your question.

There are two scenarios where a customer_refund transaction type can be used. 

The first is to refund a sales_credit_note and the second, as in your scenario is to refund a contact_payment which has an amount outstanding.

It is usually the allocated_artefacts [artefact_id] that is set incorrectly. For sales_credit_notes, this must be set with the artefact_id and not the transaction_id. For contact_payment refunds you must use the payment_on_account_id found in the contact_payment/id 

 

{
  "contact_payment": {
    "transaction_type_id": "CUSTOMER_REFUND",
    "payment_method_id": "CREDIT_DEBIT",
    "contact_id": "d7dbc85fedd04feea1874d3b49f44860",
    "bank_account_id": "5942e91ca0ac4d13b96ed6bd9cd1f156",
    "date": "2022-03-24",
    "total_amount": "5.00",
    "allocated_artefacts": [
      {
        "artefact_id": "e1c154e02dd1422fa52faab782e7e0bf",<-payment_on_account_id
        "amount": "5.00"
      }
    ]
  }
}

It's important to note that the API will allow you to make partial refunds for a credit or payment on account and the UI will only allow a user to make a refund for the total outstanding amount.

Thanks

Mark