Desc: records payments received from customers / sent to customers (refunds)
Path: http://host/api/pay
HTTP Method: POST
Input:
- action - if "action" isn't sent, payments will be recorded.
- use_deposit: going over transferred deposits and using it.
- Parameters:
- txid: array of unique identifiers ("txid") of deposits to use.
- split_bill: splitting customer debt into installments (see below related section).
It’s possible to use this action by transferring installments array or by transferring number of installments.
It’s possible also to transfer first_due_date when transferring the number of installments, if not transferred first_due_date will be equal to 1 second before the end of the billing cycle and the due date of the first installment.
Each split_bill action creates a unique id for identifying the related installments that were generated from this action.
- Parameters:
- aid: the customer’s account id.
- amount: total amount to pay.
- first_due_date: the due date of the first payment, should be transferred only when installments_num parameter is transferred and when installments parameter isn’t.
- installments_num: number of installments.
- Installments - array of installments, each installment has due_date field and optional amount, note fields. In addition, each of the installments can have custom uf (user fields), (which can be different between the installments). Their structure will be:uf:{“field_name”:”value”,”field2_name”:”value”}”
- note - note to attach to a payment.
- uf : If the user would like to add the same custom user fields to each of the bill’s new installments, it’s possible to send a list of uf fields and their values. If one of the user fields appears in this list and in the installments array (in case it exists), the value will be taken from the installment’s details.
- merge_installments: merge multiple installments into one.
works on installments that were split by split_bill action.
- Parameters:
- split_bill_id: id of the split bill action - this will identify which installments will be merged into one.
- aid: the customer’s account id.
- due_date: date to enter customer to collection.
This field is optional and if not supplied it will be equal to the due date of the first installment.
- first_charge_date: date to start charging the customer.
When looking on the customer debt, if this date is in the future
The bill amount won’t be taken into account in the customer debt.
This field is optional and if not supplied it will be equal to the earliest date defined in the installments that were merged, if still not exists will be equal to the due date of the first installment.
- method - cheque / cash / wire_transfer / credit / write_off (string, mandatory when the "action" parameter isn't set)
- uf : If the user would like to add the same custom user fields to each of the payments, it’s possible to send a list of uf fields and their values. If one of the user fields appears in this list and in the payments array (in case it exists), the value will be taken from the payment’s details.
- payments - JSON array of payments (Mandatory when the "action" parameter isn't set), each one constructed from the following fields:
- amount: the amount that was paid (positive decimal)
- aid: customer identification number associated with the payment
- payer_name: the payer name (string)
- dir: “fc” / “tc” (from / to customer, string)
- deposit_slip: number from the deposit slip (“remise”) (required only for cheque payments, string)
- deposit_slip_bank: bank name (string)
- cheque_no: cheque number (string)
- source: where the payment came from (string) (required for credit card payments)
- pays.inv: an optional object specifying the bills paid by the payment. Each key-value pair in this object represents an invoice id and the amount paid to it. Note: If this field is omitted, the oldest unpaid invoice(s) will be taken first.
Note: the sum of the amount in the array pays.inv (the values) need to be similar to the amount in the parameter “amount”. example:
payments=[{"aid":196595,"amount":66,"dir":"fc","pays.inv":{"1025613":48,"1025612":18}}]
- deposit: true - indicates that the payment is a deposit.
- note - note to attach to a payment (string)
- In addition, each of the payments can have custom user fields, (which can be different between the payments). Their structure will be: uf:{“field_name”:”value”,”field2_name”:”value”}
Output format: JSON
Output structure:
- status :
- 1 = successful
- 0 = failed
- desc = textual description of the status
- input = the raw input
- details
- payments_received: number of received payments.
- payments_saved: number of saved payments.
Examples:
Example: inserting payments.
Input:
http://host/api/pay?method=cheque&payments=[{"amount":8,"aid":325012,"deposit_slip":"","deposit_slip_bank":"","payer_name":"Yossi","dir":"fc","source":"web"}, {"amount":10,"aid":325015,"payer_name":"Yonatan","deposit_slip":"","deposit_slip_bank":"","dir":"fc","source":"web"}]
Output:
{"status":1,"desc":"success","input":[],"details":{"payments_received":2,"payments_saved":2}}
Example: inserting payments with uf.
Input:
http://host/api/pay?method=cheque&payments=[{"amount":8,"aid":325012,"deposit_slip":"","deposit_slip_bank":"","payer_name":"Yossi","dir":"fc","source":"web", “uf”:{”credit_type” : “national”}}, {"amount":10,"aid":325015,"payer_name":"Yonatan","deposit_slip":"","deposit_slip_bank":"","dir":"fc","source":"web", “uf”:{“bank” : “bank2”}}]&uf={"credit_type":"international", “bank”:”bank1”}
Output:
{"status":1,"desc":"success","input":[],"details":{"payments_received":2,"payments_saved":2}}
In this case, the 2 payments will have the 2 user fields : “credit_type” and “bank”, but with different values : the first payment’s bank is “bank1”, and credit_type is “national”, while the second’s is “bank2”, and “international”.
Example: inserting payments with invoice reference (pays.inv).
Input:
http://host/api/pay?method=cheque&payments=[{“amount”:76,”aid”:325015,”payer_name”:”Yonatan”,”dir”:fc”,”pays.inv”:{“1025613”:42,”1025612”:34},”source”:”web”}]
Output:
{ "status": 1, "desc": "success", "input": [], "details": {"payments_received": 1, "payments_saved": 1} }
Possible errors:
{"status": 0, code": 17577, message": "No payments found", display": { code": 999, desc": "General error." }}
{status": 0, code": 17577, message": "Billrun_Bill_Payment: Insufficient options supplied.", display": { code": 999, desc": "General error." }
Option to cancel existing payments. The action is cancel_payments.
- cancel_payments: cancel existing payments.
- Parameters:
- ignore_errors: when equals to 1, errors will be ignored, when equals to 0 errors will stop the API.
- cancellations: array of payments to cancel, the structure of it is the following:
- txid: the payment identifier to be cancelled.
- uf: User fields - object which represents user fields.
Example: success in cancelling payment.
Input:
http://host/api/pay?action=cancel_payments&cancellations=[{"a": 1,"txid": "0000000000078", "uf":{"payer_name":"Yossi" , "reason_code":4}}]
Output:
{"status":1,"desc":"success","input":[],"details":{"succeeded_cancels":["0000000000078"],"errors":[]}}
Example: using ignore_errors parameter to ignore errors and continue with the API call(in case there’s more than one payment cancellation) + transferring more than 1 payment to cancel.
Input:
http://host/api/pay?action=cancel_payments&cancellations=[{"a": 1,"txid": "0000000000078", "uf":{"payer_name":"Yossi" , "reason_code":4}}, {"a": 1,"txid": "0000000000079", "uf":{"payer_name":"Yonatan" , "reason_code":6}}]&ignore_errors=1
Output:
{"status":1,"desc":"success","input":[],"details":{"succeeded_cancels":["0000000000079"],"errors":["0000000000078 cannot be cancelled"]}}
Example: trying to cancel payment which have already been cancelled
Input:
http://host/api/pay?action=cancel_payments&cancellations=[{"a": 1,"txid": "0000000000077", "uf":{"payer_name":"Yossi" , "reason_code":4}}]
Output:
{"status":0,"desc":"error","input":[],"details":{"errors":["0000000000077 cannot be cancelled"]}}
Option to split payment to installments.
Example input:
http://host/api/pay?method=installment_agreement&action=split_bill&installments=[{"due_date":"2019-11-10", "amount": 2}, {"due_date":"2019-12-10", "amount":3}, {"due_date":"2019-1-10", "amount":8}]&amount=13&aid=355657
Output:
{"status":1,"desc":"","input":[],"details":"created installments successfully . parameters: {\"id\":1581956849847,\"total_amount\":13,\"installments_num\":3}"}
Input:
http://host/api/pay?method=installment_agreement&action=split_bill&installments=[{"due_date":"2019-11-10", "amount": 50}, {"due_date":"2019-12-10", "amount":8}, {"due_date":"2019-1-10", "amount":0.8, "uf":{"credit_type":"leumi2","payer_address":"bank1"}}]&amount=58.8&aid=13852&uf={"credit_type":"leumi"}
Output :
{"status": 1,"desc": "","input": [],"details": "created installments successfully. Parameters:{\"id\":1586762245251,\"installments_num\":3,\"total_amount\":58.8,\"first_due_date\":{\"sec\":1588280399,\"usec\":0},\"invoices\":null}"}
The first and second installments will have “credit_type” : “leumi” uf in the database. The third installment, will have “credit_type” : “leumi2” and “payer_address”:”bank1” uf in the database.
Merge installments from split debt action into one installment.
Input:
http://host/api/pay?method=merge_installments&action=merge_installments&aid=355657&split_bill_id=1580731473841&first_charge_date=2020/02/02
Output:
{"status":1,"desc":"","input":[],"details":"merged installments successfully"}
Desc: records payment rejections
Path: http://host/api/reject
HTTP Method: POST
Input:
- rejections - JSON array of rejections, each one constructed from the following fields:
- id: unique id of the payment to reject (string)
- rejection: (object)
- code: the rejection code (string)
Output format: JSON
Output structure:
- status :
- 1 = successful
- 0 = failed
- desc = textual description of the status
- input = the raw input
- errors = JSON array of payment ids that were not rejected.
Example:
http://host/api/reject?rejections=[{"id":"0000000000001","rejection":{"code":342}}]
Desc: retrieve payer’s details by an invoice id or account id.
Path: http://host/api/bill
HTTP Method: POST
Input:
- action: the action to execute. Here are the available actions:
- get_over_due
- get_balances - returns balances of selected aids. Optional fields are :
- date - if a date field is given, the API will return the accounts balance up to this date.
- include_future_chargeable - true/false - allows the user to also get charges, which are not chargeable yet, in the returned balance. Default value is false.
- collection_debt - returns collection information total debt for selected aids. Optional fields are :
- threshold - a custom threshold value can be sent, and override the configured collection minimum debt for this specific call. For example, if the configured collection minimum debt is 10 EUR, but you want the API to return all the customers with a smaller debt, you can sent threshold = 0.01, and the API return customers with debt that is bigger than 0.01EUR.
- search_invoice - returns all invoice information related to invoice_id.
- all_collection_debts - returns all the accounts that are in collection, and their total debt.
- query_bills_invoices - return invoices in accordance to the transferred query. For this action you'll need to add the query argument.
- query: (JSON) query to get wanted invoices (relevant and mandatory for query_bills_invoices action).
Output format: JSON
Output structure:
- status :
- 1 = successful
- 0 = failed
- desc = textual description of the status
- input = the raw input
- details: object containing the following fields:
- balance: the current balance due of the customer (float)
- bill: object containing the invoice details (if only aid is supplied then ‘bill’ will be empty)
- aid: the unique identification of the customer (int)
- amount: the amount of the invoice
- due: the amount of the invoice (equal to amount)
- payer_name: the payer name (string)
- bank_name: the bank of the payer (string)
Examples:
- Will return all invoices for account number = 46263 that he still hadn’t paid:
http://host/api/bill?action=query_bills_invoices&query={"aid":46263,"paid_by":{"$exists": 0}}
- You can also add a range of dates or add “invoice_type” (“immediate” / “regular”) field, to make the result more focused ($gte = greater than / equal, $lt = lower than).
http://host/api/bill?action=query_bills_invoices&query={"aid":10,"invoice_type":"immediate","invoice_date":{"$gte":“2019-07-01T21:00:00Z” , $lt:“2019-08-30T21:00:00Z”}}
This API request will output all the immediate invoices between 2019-07-01T21:00:00Z, including, to 2019-08-30T21:00:00Z
- http://host/api/bill?action=all_collection_debts
- http://host/api/bill?action=search_invoice&id=81000013
- http://host/api/bill?action=get_balances&aids=553620,13852
- http://host/api/bill?action=collection_debt&aids=[553620]
- http://host/api/bill?action=get_balances&aids=17983&date=2023-11-21 22:00:00&include_future_chargeable=true
- http://host/api/bill?action=collection_debt&aids=[17983]&threshold=0.03
Desc: retrieve cheque / credit payments received from customer by payment date and amount.
Path: http://host/api/payments
HTTP Method: POST
Input:
- action - either ‘query’ or ‘search’. Defaults to ‘search’
- aid - Account id (optional. Ignored when action=’query’)
- dir - Direction of the payment (‘fc’ / ‘tc’ - mandatory when action=’search’. Ignored when action=’query’)
- methods - payment methods to filter (JSON array. Optional. Ignored when action=’query’)
- payment_date - The date when the payment has been performed (YYYY-mm-dd string. Mandatory when action=’search’. Ignored when action=’query’)
- amount - the amount of the payment (Optional float. Ignored when action=’query’)
- query - A JSON string resembling a MongoDB query (Mandatory when action=’query’. Ignored when action=’search’)
Output format: JSON
Output structure:
- status :
- 1 = successful
- 0 = failed
- desc = textual description of the status
- input = the raw input
- details: = object containing the following field:
- payments: array containing the found payments
Description : allows the user to make changes to existing payments.
Path : http://host/api/adjustpayments
HTTP Method : POST
Input:
- adjustments : JSON array of adjustments:
- Structure:
- id : Billrun unique identifier of the payment [mandatory].
- amount : payment’s amount to update [mandatory if “method” is missing].
- method : payment’s method to update [mandatory if “amount” is missing]
Output format: JSON.
Output structure:
- status :
- 1 = successful
- 0 = failed
- message(in case of failure): textual description of the error.
- “No adjustments found”
- “Missing id ...”
- “Missing payment method or amount for payment ….”
- “Unknown id ...”
- “Payment …. not applicable”
- “Illegal payment method”
- display: object containing the following fields:
- code : the error code (string).
- desc : error description.
- Input (in case of success) : the raw input.
Desc: retrieve customer invoices by aid and billrun_key.
Path: http://host/api/accountinvoices
HTTP Method: POST
Input:
- action - download / query / expected_invoice / search.
- aid - account id (mandatory)
- billrun_key - billrun key of desired date (mandatory)
- iid : invoice_id (optional).
- query - A JSON string resembling a MongoDB query (Mandatory when action=’query’)
Output format: JSON
Output structure:
- details: object containing the array of invoices
Example:
http://host/api/accountinvoices?action=download&aid=3&billrun_key=201908&iid=102
Desc: retrieve the customer’s payment history (bills) between two given dates.
Path: http://host/api/paymenthistory
HTTP Method: POST
Input:
- aid - account id
- from - date to start filter from (Y-m-d, for example: 2019-11-26).
- to - date to end filter (Y-m-d, for example: 2019-11-26).
Output format: JSON
Output structure:
- details: object containing the following field:
- payments: array containing the found payments
Desc: retrieve all rejections (code + name) from the ‘rejection_codes’ collection
Path: http://host/api/rejections
HTTP Method: POST
Input: None.
Output format: JSON
Output structure:
- status :
- 1 = successful
- 0 = failed
- desc: textual description of the status
- details: object containing the following fields:
- rejections: array containing the rejections