BatchPaymentPayload

When you want to create a BatchPayment to transmit funds from a SourceAccount to many PortfolioLoans and/or Servicers on behalf of Borrowers, you will send a BatchPaymentPayload describing the payments you wish to make to our Create BatchPayment endpoint.

❗️

Take care when building BatchPaymentPayloads

Successfully creating BatchPayments requires careful attention to the details of your BatchPaymentPayload.

Common Pitfalls

• Your BatchPaymentPayload will be rejected if the total_amount does not equal the sum of all items in the payments array
• Your BatchPaymentPayload will be rejected if the number_of_payments does not equal the total number of items in the payments array
• Your BatchPaymentPayload will be rejected if you've re-used a reference_id

Review the Examples section to see a valid and invalid BatchPaymentPayload.

Schema Description

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 BatchPayment 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 BatchPaymentPayload (and its BatchPaymentItemPayload objects in the payments array) 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 BatchPayment with its Payitoff BatchPayment 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.

Examples

A valid BatchPaymentPayload should appear as the JSON value of a batch key in your request.

In the example below, you can see a valid BatchPaymentPayload:

• total_amount matches the sum of each amount property in the payments array
• number_of_payments matches the number of items in the payments array

{
  "batch": {
    "total_amount": "325.46",
    "number_of_payments": 2,
    "source_account_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "reference_id": "b123",
    "payments": [
      {
        "amount": "150.12",
        "allocation": {
          "type": "servicer",
          "id": "9a57055f-ae0d-4ff1-b4b8-db4e564c27d6"
        },
        "reference_id": "b123-1"
      },
      {
        "amount": "175.34",
        "allocation": {
          "type": "loan",
          "id": "9a57055f-ae0d-4ff1-b4b8-db4e564c27d6"
        },
        "reference_id": "b123-2"
      }
    ]
  }
}

In the example below, you can see an invalid BatchPaymentPayload:

• total_amount does not match the sum of each amount property in the payments array
• number_of_payments does not match the number of items in the payments array

{
  "batch": {
    "total_amount": "550.34",
    "number_of_payments": 5,
    "source_account_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "reference_id": "8b02e87d-06b1-4551-86eb-07f2e9f7b007",
    "payments": [
      {
        "amount": "150.12",
        "allocation": {
          "type": "servicer",
          "id": "9a57055f-ae0d-4ff1-b4b8-db4e564c27d6"
        },
        "reference_id": "e6275310-3f5b-43db-ab40-0c30258a10cc"
      }
    ]
  }
}