Assign money from a payment or credit note to invoices and/or refunds.
All transactions must be 'cleared' by having money assigned to/from them. For example, when an invoice is raised and a corresponding payment is added, money from the payment needs to be assigned to the invoice in order to 'pay' the invoice and 'use up' the payment.
Money must be assigned from a 'credit type transaction (a payment or credit note) to a 'debit' type transaction (an invoice or refund).
| arg | required? | syntax | info |
|---|---|---|---|
paymentID | Y | posint | |
type | Y | enum:payment|creditnote | defines whether paymentID relates to a payment or credit note |
custID | Y | posint | customer ID of customer account |
assignto | Y | array | array of assignment instructions |
This field holds the ID of the payment from which money is being assigned.
To assign money from a payment (ie pay things with a payment), the 'type' argument should be set to 'payment' and the 'paymentID' argument should be set to
the paymentID of the payment record (this is returned to you by the payment.create and payment.take functions at the time
the payment is made, and also by the payment.list function.
To assign money from a credit note (ie pay things with a credit note), the 'type' argument should be set to 'creditnote' and the 'paymentID' argument should be set to
the creditnoteID of the credit note (this is returned to you by the invoice.create function at the time the
credit note is raised, and also by the invoice.list function.
This is an array of assignment instructions. You can assign money to more than one 'thingy' in one function call (a thingy being an invoice or refund).
The assignto argument should be an array consisting of one or more sub-arrays, each consisting of:
This function will process each assignment instruction in turn. If all of the payment money gets used up before all of the assignment instructions have been processed, it will stop processing any further assignment instructions. This will not result in an error. The return values of this function will indicate how much money was actually assigned to each 'thingy'.
Pay all remaining money from payment 17275 to the invoice with invoiceID 108490 (this is NOT the invoice number).
Perl example request:
POST https://live.apicontrol.co.uk/1/json
my %args =
(
'custID'=>16526,
'paymentID'=>17275,
'type'=>'payment',
'assignto' =>
[
{ 'invoiceID'=>108490 }
]
);
my $res = $api->payment_assign(%args);XML example request:
POST https://live.apicontrol.co.uk/1/json
We can see from the below response that
Perl example response:
{
'success' => '1',
'assignmentIDinv108490' => '108675',
'num_payments_made' => '1',
'money_left_unallocated' => '0.00',
'errordiags' => '',
'error' => undef,
'remaining_on_inv108490' => '56.52',
'errornum' => '',
'paid_on_inv108490' => '0.57',
'results' => []
};XML example response:
Use payment 17277 to pay
Perl example request:
POST https://live.apicontrol.co.uk/1/json
my %args =
(
'custID'=>16526,
'paymentID'=>17277,
'type'=>'payment',
'assignto' =>
[
{ 'invoiceID'=>108490, 'amount'=>'12.00' },
{ 'invoiceID'=>108491 },
{ 'invoiceID'=>108492 },
{ 'refundID'=>92428 },
]
);
my $res = $api->payment_assign(%args);XML example request:
POST https://live.apicontrol.co.uk/1/json
We can see from the below response that
Perl example response:
{
'paid_on_inv108491' => '5.75',
'assignmentIDinv108491' => '108677',
'assignmentIDinv108490' => '108676',
'paid_on_inv108492' => '5.69',
'remaining_on_ref92428' => '0.00',
'remaining_on_inv108490' => '44.52',
'error' => undef,
'assignmentIDinv108492' => '108678',
'paid_on_ref92428' => '10.00',
'success' => '1',
'num_payments_made' => '4',
'remaining_on_inv108491' => '0.00',
'money_left_unallocated' => '66.69',
'errordiags' => '',
'remaining_on_inv108492' => '0.00',
'errornum' => '',
'paid_on_inv108490' => '12.00',
'results' => []
};XML example response: