BatchPaymentItemPayload

When you Create BatchPayments, you must provide a payments array as part of your BatchPaymentPayload. The BatchPaymentPayload.payments array is populated with BatchPaymentItemPayload objects, which define the how you want your funds to be allocated.

Schema Definition

Properties in bold are required.

🚧

A few words about reference_id values

You will notice that you can supply a reference_id for BatchPayment and BatchPaymentItem objects when you create them via their relevant Payload objects. While these fields are not required, we highly recommend always providing a unique value for each reference_id property in your API request payloads. Providing a UUID is an easy way to ensure you always have unique reference_id values for your BatchPayment and BatchPaymentItem objects.

Get the most out of reference_id

Your reference_id values should be a unique identifier created and stored in your application to identify this BatchPaymentItem for your system.

We will use the reference_id, when available, to ensure idempotency across Create BatchPayment requests (ensuring you always get the same BatchPayment outcome even if you resubmit the same request).

We will associate the reference_id of an item in your BatchPaymentItemPayload if the Create BatchPayments request fails—allowing you to identify the offending item in your payload that did not pass validation.

The reference_id can be used to ensure you are able to match your platform's internal representation of a BatchPaymentItem with its Payitoff BatchPaymentItem record.

The reference_id can help facilitate auditing your BatchPayment requests between your internal systems and the Payitoff API fulfilling BatchPayment requests.

The reference_id is a string field that allows any value, to provide maximum flexibility to provide your own identification scheme.

Example

{
  "allocation": {
    "id": "75715081-e513-4008-ad68-fa195c9de9f9",
    "type": "loan"
  },
  "amount": "1.00",
  "borrower_id": "b72c6b71-5eaa-42e8-bd1b-7b0f12caea4c",
  "id": "fd3acad2-5e34-4718-bbe6-212a55cb4cbf",
  "reference_id": "b123-1"
}