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
| Name | Type | Description |
|---|---|---|
| Number | Numeric | Unique number of bulk invoice payment |
| Date | Date | Payment date. For e.g. JSON Format :2012-06-28 12:00:00, XML Format : 2012-06-28 12:00:00 |
| Comment | String | Comment. |
| AccountId | Numeric | Account to be used for making the payment. |
| Method | Numeric | Payment mode. |
| Reconciled | Boolean | If the bulk payment items are part of any successful bank reconcillation. |
| ExportDetails | Object | Information 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. |
| PaymentItems | Collection of type ‘BulkPaymentItem’ | Collection of the payments to be added for multiple invoices/purchases |
| BulkPayment Item collection parameters | ||
| Id | Numeric | Unique id of payment item. |
| Amount | Numeric | Payment amount for this invoice/purchase. |
| ContactName | String | Name of the customer/supplier. |
| ContactReference | String | Customer/supplier reference of the invoice/purchase for which the payment in intended for. |
| ObjectIssuedDate | Date | The date on which the invoice/purchase (for which the payment is made) was issued. |
| ObjectNumber | Numeric | Unique number of the invoice/purchase for which the payment is to be made. |
| PaidDate | Numeric | Payment date. |
| ExportDetails object fields | ||
| Permalink | String | Permanent url of purchase batch payment document that can be shared. |
| EmailId | String | ‘EmailId’ to which the purchase bulk payment is mailed. |
| ObjectNumber | Numeric | Object 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": "[email protected]",
"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": "[email protected]",
"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": "[email protected]",
"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.