Bulk Payments

This s a documentation page for our shiny new REST API - you weren't meant to find it. This API isn't ready for public use yet. We're chopping and changing it a LOT as we grow it. So if you build something that uses it then it's very likely to break in a future update. Don't say you weren't warned!

URL:

https://api.kashflow.com/v2/{objecttype}/bulk/payments

Method(s):

POST,GET, PUT, DELETE

Response Formats:

JSON or XML

Description:

These methods allow you to retrieve, create, update and delete bulk payments.
{objecttype} can be invoices/purchases.

Parameters

NameTypeDescription
NumberNumericUnique number of bulk invoice payment
DateDatePayment date. For e.g. JSON Format :2012-06-28 12:00:00, XML Format : 2012-06-28 12:00:00
CommentStringComment.
AccountIdNumericAccount to be used for making the payment.
MethodNumericPayment mode.
ReconciledBooleanIf the bulk payment items are part of any successful bank reconcillation.
ExportDetailsObjectInformation required for different ways to export the bulk payment like printing, emailing, etc. This property is only for purchase batch payment not invoice batch payment, so will be retrieved as null for invoice batch payment.
PaymentItemsCollection of type ‘BulkPaymentItem’Collection of the payments to be added for multiple invoices/purchases
BulkPayment Item collection parameters
IdNumericUnique id of payment item.
AmountNumericPayment amount for this invoice/purchase.
ContactNameStringName of the customer/supplier.
ContactReferenceStringCustomer/supplier reference of the invoice/purchase for which the payment in intended for.
ObjectIssuedDateDateThe date on which the invoice/purchase (for which the payment is made) was issued.
ObjectNumberNumericUnique number of the invoice/purchase for which the payment is to be made.
PaidDateNumericPayment date.
ExportDetails object fields
PermalinkStringPermanent url of purchase batch payment document that can be shared.
EmailIdString‘EmailId’ to which the purchase bulk payment is mailed.
ObjectNumberNumericObject number for the purchase bulk payment that appears in the file name of the email attachment.

GET Operation


This method allows to GET details of a particular invoice/purchase bulk payment.

URL : invoices/bulk/payments/{number}
purchases/bulk/payments/{number}

{number} is the unique identifier of the bulk payment.

Example response for GET of Invoice Bulk Payment


{
  "AccountId": 131609,
  "Comment": "October Payments",
  "Date": "2013-10-24 12:00:00",
  "Method": 727693,
  "Number": 29,
  "PaymentItems": [{
    "Amount": 2349.0000,
    "ContactName": "01",
    "ContactReference": "Order543",
    "ObjectIssuedDate": "2013-10-24 12:00:00",
    "Id": 27729944,
    "ObjectNumber": 63,
    "PaidDate": "2013-10-24 12:00:00"
  }, {
    "Amount": 1866.0000,
    "ContactName": "01",
    "ContactReference": "Order545",
    "ObjectIssuedDate": "2013-10-24 12:00:00",
    "Id": 27729945,
    "ObjectNumber": 64,
    "PaidDate": "2013-10-24 12:00:00"
  }, {
    "Amount": 1680.0000,
    "ContactName": "01",
    "ContactReference": "Order546",
    "ObjectIssuedDate": "2013-10-24 12:00:00",
    "Id": 27729941,
    "ObjectNumber": 68,
    "PaidDate": "2013-10-24 12:00:00"
  }, {
    "Amount": 1514.0000,
    "ContactName": "01",
    "ContactReference": "Order547",
    "ObjectIssuedDate": "2013-10-24 12:00:00",
    "Id": 27729942,
    "ObjectNumber": 69,
    "PaidDate": "2013-10-24 12:00:00"
  }, {
    "Amount": 1601.0000,
    "CustomerName": "01",
    "ContactReference": "Order548",
    "ObjectIssuedDate": "2013-10-24 12:00:00",
    "Id": 27729943,
    "ObjectNumber": 70,
    "PaidDate": "2013-10-24 12:00:00"
  }],
  "Reconciled": false,
  "Permalink": null
}

Example response for GET of Purchase Bulk Payment


{
  "AccountId": 131609,
  "Comment": "October Payments",
  "Date": "2013-10-24 12:00:00",
  "ExportDetails": {
   "EmailId": "nicolas@tech.co.uk",
   "ObjectNumber": 63,
   "Permalink": "/v2/documents/purchase/payment/7b3ca0f5-ce44-4c2c-b4d7-7ecaf4411337"
 },
 "Method": 727693,
 "Number": 29,
 "PaymentItems": [{
  "Amount": 2349.0000,
  "ContactName": "01",
  "ContactReference": "Order543",
  "ObjectIssuedDate": "2013-10-24 12:00:00",
  "Id": 27729944,
  "ObjectNumber": 63,
  "PaidDate": "2013-10-24 12:00:00"
}, {
  "Amount": 1866.0000,
  "ContactName": "01",
  "ContactReference": "Order54",
  "ObjectIssuedDate": "2013-10-24 12:00:00",
  "Id": 27729945,
  "ObjectNumber": 64,
  "PaidDate": "2013-10-24 12:00:00"
}, {
  "Amount": 1680.0000,
  "ContactName": "01",
  "ContactReference": "Order540",
  "ObjectIssuedDate": "2013-10-24 12:00:00",
  "Id": 27729941,
  "ObjectNumber": 68,
  "PaidDate": "2013-10-24 12:00:00"
}, {
  "Amount": 1514.0000,
  "ContactName": "01",
  "ContactReference": "Order5423",
  "ObjectIssuedDate": "2013-10-24 12:00:00",
  "Id": 27729942,
  "ObjectNumber": 69,
  "PaidDate": "2013-10-24 12:00:00"
}, {
  "Amount": 1601.0000,
  "ContactName": "01",
  "ContactReference": "Order53443",
  "ObjectIssuedDate": "2013-10-24 12:00:00",
  "Id": 27729943,
  "ObjectNumber": 70,
  "PaidDate": "2013-10-24 12:00:00"
}],
"Reconciled": false,
"Permalink": "/v2/documents/purchase/payment/83f860a8-595e-458c-b075-5fcd50e4aede"
}

POST Operation


This method allows to make a single payment against multiple invoices/purchases at one go.
The request body should consist of list of invoice/purchase numbers and corresponding amounts for which payment is to be done.

Note:
1. All fields are mandatory except the comment field.
2. If an invalid payment method or bank account is specified, then the defaults are used.
3. If any of the specified invoice/purchase is invalid, the API will respond with 400 status code accompanied by the list of invalid invoice/purchase number(s) in the message. In such a scenario, payment will not be applied to the valid invoices/purchases and you need to retry the operation after removing the invalid invoice/purchase numbers from the list.
4. A bulk payment can have multiple payments for the same invoice/purchase.
5. API returns newly created bulk payment details with HTTP 201 status code if request is successful.
6. The POST operation fails and returns 400, if the “Date” of the bulk payment is within the TransactionLockDate for the user account or the TransactionLockDate of the bank account from which the payments are to be made.

URL : invoices/bulk/payments

Example request for POST of Invoice bulk payments


{
  "Date": "2013-10-24",
  "Comment": "October Payments",
  "AccountId": 3942,
  "Method": 2508,
  "PaymentItems":
  [{
    "ObjectNumber": 3793,
    "Amount": "1680.00"
  },
  {
    "ObjectNumber": 3438,
    "Amount": "1514.00"
  },
  {
    "ObjectNumber": 1209,
    "Amount": "1601.00"
  },
  {
    "ObjectNumber": 2531,
    "Amount": "2349.00"
  },
  {
    "ObjectNumber": 3566,
    "Amount": "1866.00"
  }]
}

Example response for POST of Invoice bulk payments


{
  "Number": 24,
  "Date": "2013-10-24",
  "Comment": "October Payments",
  "AccountId": 3942,
  "Method": 2508,
  "PaymentItems": [
  {
    "Id":1,
    "ObjectNumber": 3793,
    "Amount": "1680.00",
    "ContactName": "01",
    "ContactReference": "Order1234543",
    "ObjectIssuedDate": "2013-10-24 12:00:00",
    "PaidDate": "2013-10-24 12:00:00"
  },
  {
    "Id":2,
    "ObjectNumber": 3438,
    "Amount": "1514.00",
    "ContactName": "01",
    "ContactReference": "Order23456543",
    "ObjectIssuedDate": "2013-10-24 12:00:00",
    "PaidDate": "2013-10-24 12:00:00"
  },
  {
    "Id":3,
    "ObjectNumber": 1209,
    "Amount": "1601.00",
    "ContactName": "01",
    "ContactReference": "Order543",
    "ObjectIssuedDate": "2013-10-24 12:00:00",
    "PaidDate": "2013-10-24 12:00:00"
  },
  {
    "Id":4,
    "ObjectNumber": 2531,
    "Amount": "2349.00",
    "ContactName": "01",
    "ContactReference": "Order543",
    "ObjectIssuedDate": "2013-10-24 12:00:00",
    "PaidDate": "2013-10-24 12:00:00"
  },
  {
    "Id":5,
    "ObjectNumber": 3566,
    "Amount": "1866.00",
    "ContactName": "01",
    "ContactReference": "Order23456543",
    "ObjectIssuedDate": "2013-10-24 12:00:00",
    "PaidDate": "2013-10-24 12:00:00"
  }
  ],
  "Reconciled": false
}

URL : purchases/bulk/payments

Example request for POST of purchase bulk payments


{
  "Date": "2013-10-24",
  "Comment": "October Payments",
  "AccountId": 3942,
  "Method": 2508,
  "PaymentItems":
  [
  {
    "ObjectNumber": 3793,
    "Amount": "1680.00"
  },
  {
    "ObjectNumber": 3438,
    "Amount": "1514.00"
  },
  {
    "ObjectNumber": 1209,
    "Amount": "1601.00"
  },
  {
    "ObjectNumber": 2531,
    "Amount": "2349.00"
  },
  {
    "ObjectNumber": 3566,
    "Amount": "1866.00"
  }]
}

Example response for POST of Purchase bulk payments


{
  "Number": 24,
  "Date": "2013-10-24",
  "Comment": "October Payments",
  "AccountId": 3942,
  "Method": 2508,
  "ExportDetails": 
  {
    "EmailId": "nicolas@tech.co.uk",
    "ObjectNumber": 63,
    "Permalink": "/v2/documents/purchase/payment/7b3ca0f5-ce44-4c2c-b4d7-7ecaf4411337"
  },
  "PaymentItems": [{
    "Id":1,
    "ObjectNumber": 3793,
    "Amount": "1680.00",
    "ContactName": "01",
    "ContactReference": "Order78543",
    "ObjectIssuedDate": "2013-10-24 12:00:00",
    "PaidDate": "2013-10-24 12:00:00"
  },
  {
    "Id":2,
    "ObjectNumber": 3438,
    "Amount": "1514.00",
    "ContactName": "01",
    "ContactReference": "Order456543",
    "ObjectIssuedDate": "2013-10-24 12:00:00",
    "PaidDate": "2013-10-24 12:00:00"
  },
  {
    "Id":3,
    "ObjectNumber": 1209,
    "Amount": "1601.00",
    "ContactName": "01",
    "ContactReference": "Order53443",
    "ObjectIssuedDate": "2013-10-24 12:00:00",
    "PaidDate": "2013-10-24 12:00:00"
  },
  {
    "Id":4,
    "ObjectNumber": 2531,
    "Amount": "2349.00",
    "ContactName": "01",
    "ContactReference": "Order4578543",
    "ObjectIssuedDate": "2013-10-24 12:00:00",
    "PaidDate": "2013-10-24 12:00:00"
  },
  {
    "Id":5,
    "ObjectNumber": 3566,
    "Amount": "1866.00",
    "ContactName": "01",
    "ContactReference": "Order543",
    "ObjectIssuedDate": "2013-10-24 12:00:00",
    "PaidDate": "2013-10-24 12:00:00"
  }
  ],
  "Reconciled": false
}

PUT Operation


This method allows to update an existing bulk payment. This operation involves:
1. Update of bulk payment header information, i.e. Date, Comment, AccountId and Method.
2. Update the amounts and paid date of the existing payment items. The existing payment will be uniquely identified by the ‘Id’ field of each payment item. The paid date of the corresponding invoices are also updated.
3. Add new payment items in the collection of invoice payments. If ‘Id’ field is not specified for any payment item, then it is treated as new payment item and is added as a part of the bulk payment.
4. Delete existing payment items. If the request body does not contain any of the existing payment items, then these missing payment items will be deleted from the bulk payment.

Note:
1. If an invalid payment method or bank account is specified, then the defaults are used.
2. If any of the specified invoice/purchase is invalid, the API will respond with 400 status code accompanied by the list of invalid invoice/purchase number(s) in the message. In such a scenario, payment will not be applied to the valid invoices/purchases and you need to retry the operation after removing the invalid invoice/purchase numbers from the list.
3. A bulk payment can have multiple payment items for the same invoice/purchase.
4. API returns updated bulk payment details with HTTP 200 status code if request is successful.
5. The PUT operation fails and returns 400, if the “Date” of the bulk payment is within the TransactionLockDate for the user account or the TransactionLockDate of the bank account from which the payments are to be made.
6. The reconciliation status of a bulk payment is updated if the Date/AccountId is changed or a new payment item is added to it.

URL : invoices/bulk/payments/{number}

Example request for PUT of Invoice bulk payments


{
  "Number": 24,
  "Date": "2013-10-24",
  "Comment": "October Payments Updated",
  "AccountId": 3942,
  "Method": 2508,
  "PaymentItems": [
  {
    "Id":1,
    "ObjectNumber": 3793,
    "Amount": "1680.00",
    "ContactName": "01",
    "ContactReference": "Order544563",
    "ObjectIssuedDate": "2013-10-24 12:00:00",
    "PaidDate": "2013-10-24 12:00:00"
  },
  {
    "Id":2,
    "ObjectNumber": 3438,
    "Amount": "1514.00",
    "ContactName": "01",
    "ContactReference": "Order546783",
    "ObjectIssuedDate": "2013-10-24 12:00:00",
    "PaidDate": "2013-10-24 12:00:00"
  },
  {
    "ObjectNumber": 1209,
    "Amount": "1601.00",
    "ContactName": "01",
    "ContactReference": "Order346543",
    "ObjectIssuedDate": "2013-10-24 12:00:00",
    "PaidDate": "2013-10-24 12:00:00"
  },
  {
    "Id":4,
    "ObjectNumber": 2531,
    "Amount": "2349.00",
    "ContactName": "01",
    "ContactReference": "Order543453",
    "ObjectIssuedDate": "2013-10-24 12:00:00",
    "PaidDate": "2013-10-24 12:00:00"
  },
  {
    "Id":5,
    "ObjectNumber": 3566,
    "Amount": "1866.00",
    "ContactName": "01",
    "ContactReference": "Order53466643",
    "ObjectIssuedDate": "2013-10-24 12:00:00",
    "PaidDate": "2013-10-24 12:00:00"
  }
  ]
}

Example response for PUT of Invoice bulk payments


{
  "Number": 24,
  "Date": "2013-10-24",
  "Comment": "October Payments Updated",
  "AccountId": 3942,
  "Method": 2508,
  "PaymentItems": [{
    "Id":1,
    "ObjectNumber": 3793,
    "Amount": "1680.00",
    "ContactName": "01",
    "ContactReference": "Order544563",
    "ObjectIssuedDate": "2013-10-24 12:00:00",
    "PaidDate": "2013-10-24 12:00:00"
  },
  {
    "Id":2,
    "ObjectNumber": 3438,
    "Amount": "1514.00",
    "ContactName": "01",
    "ContactReference": "Order546783",
    "ObjectIssuedDate": "2013-10-24 12:00:00",
    "PaidDate": "2013-10-24 12:00:00"
  },
  {
    "Id":4,
    "ObjectNumber": 2531,
    "Amount": "2349.00",
    "ContactName": "01",
    "ContactReference": "Order346543",
    "ObjectIssuedDate": "2013-10-24 12:00:00",
    "PaidDate": "2013-10-24 12:00:00"
  },
  {
    "Id":5,
    "InvoiceNumber": 3566,
    "Amount": "1866.00",
    "ContactName": "01",
    "ContactReference": "Order543453",
    "ObjectIssuedDate": "2013-10-24 12:00:00",
    "PaidDate": "2013-10-24 12:00:00"
  },
  {
    "Id":6,
    "ObjectNumber": 1209,
    "Amount": "1601.00",
    "ContactName": "01",
    "ContactReference": "Order53466643",
    "ObjectIssuedDate": "2013-10-24 12:00:00",
    "PaidDate": "2013-10-24 12:00:00"
  },
  ],
  "Reconciled": false
}

URL : purchases/bulk/payments/{number}

Example request for PUT of Purchase bulk payments


{
  "Number": 24,
  "Date": "2013-10-24",
  "Comment": "October Payments Updated",
  "AccountId": 3942,
  "Method": 2508,
  "PaymentItems": [{
    "Id":1,
    "ObjectNumber": 3793,
    "Amount": "1680.00",
    "ContactName": "01",
    "ContactReference": "Order53466643",
    "ObjectIssuedDate": "2013-10-24 12:00:00",
    "PaidDate": "2013-10-24 12:00:00"
  },
  {
    "Id":2,
    "ObjectNumber": 3438,
    "Amount": "1514.00",
    "ContactName": "01",
    "ContactReference": "Order53466644",
    "ObjectIssuedDate": "2013-10-24 12:00:00",
    "PaidDate": "2013-10-24 12:00:00"
  },
  {
    "ObjectNumber": 1209,
    "Amount": "1601.00",
    "SupplierName": "01",
    "ContactReference": "Order53466645",
    "ObjectIssuedDate": "2013-10-24 12:00:00",
    "PaidDate": "2013-10-24 12:00:00"
  },
  {
    "Id":4,
    "ObjectNumber": 2531,
    "Amount": "2349.00",
    "ContactName": "01",
    "ContactReference": "Order53466646",
    "ObjectIssuedDate": "2013-10-24 12:00:00",
    "PaidDate": "2013-10-24 12:00:00"
  },
  {
    "Id":5,
    "ObjectNumber": 3566,
    "Amount": "1866.00",
    "ContactName": "01",
    "ContactReference": "Order53466647",
    "ObjectIssuedDate": "2013-10-24 12:00:00",
    "PaidDate": "2013-10-24 12:00:00"
  }
  ]
}

Example response for PUT of Purchase bulk payments


{
  "Number": 24,
  "Date": "2013-10-24",
  "Comment": "October Payments Updated",
  "AccountId": 3942,
  "Method": 2508,
  "ExportDetails": {
    "EmailId": "nicolas@tech.co.uk",
    "ObjectNumber": 63,
    "Permalink": "/v2/documents/purchase/payment/7b3ca0f5-ce44-4c2c-b4d7-7ecaf4411337"
  },
  "PaymentItems": [{
    "Id":1,
    "ObjectNumber": 3793,
    "Amount": "1680.00",
    "ContactName": "01",
    "ContactReference": "Order53466643",
    "ObjectIssuedDate": "2013-10-24 12:00:00",
    "PaidDate": "2013-10-24 12:00:00"
  },
  {
    "Id":2,
    "ObjectNumber": 3438,
    "Amount": "1514.00",
    "ContactName": "01",
    "ContactReference": "Order53466644",
    "ObjectIssuedDate": "2013-10-24 12:00:00",
    "PaidDate": "2013-10-24 12:00:00"
  },
  {
    "Id":4,
    "ObjectNumber": 2531,
    "Amount": "2349.00",
    "ContactName": "01",
    "ContactReference": "Order53466645",
    "ObjectIssuedDate": "2013-10-24 12:00:00",
    "PaidDate": "2013-10-24 12:00:00"
  },
  {
    "Id":5,
    "ObjectNumber": 3566,
    "Amount": "1866.00",
    "ContactName": "01",
    "ContactReference": "Order53466646",
    "ObjectIssuedDate": "2013-10-24 12:00:00",
    "PaidDate": "2013-10-24 12:00:00"
  },
  {
    "Id":6,
    "ObjectNumber": 1209,
    "Amount": "1601.00",
    "ContactName": "01",
    "ContactReference": "Order53466647",
    "ObjectIssuedDate": "2013-10-24 12:00:00",
    "PaidDate": "2013-10-24 12:00:00"
  }
  ],
  "Reconciled": false
}

DELETE Operation


This method allows to DELETE a particular invoice/purchase bulk payment.
The DELETE operation fails and returns 400, if the “Date” of the bulk payment is within the TransactionLockDate for the user account or the TransactionLockDate of the bank account from which the payments are to be made.

URL : {objectypte}/bulk/payments/{number}
{number} is the unique identifier of the bulk payment.

See how KashFlow works with your business and your books