Explore Payments endpoints in Swagger.

Overview

Payments include all accounts receivable transaction data. This includes invoices and credit notes.

A payment in Codat usually represents an allocation of money within any customer accounts receivable account. This includes, but is not strictly limited to:

  • A payment made against an invoice, like a credit card, cheque, or cash payment.
  • An allocation of a customer's credit note, either to an invoice or maybe a refund.
  • A payment made directly to that accounts receivable account. This might be an overpayment or a prepayment. It might also be the refund of a payment made directly to an accounts receivable account.

Depending on the payments allowed by the underlying accounting package, some payment types may be combined. Please see the Example data below for more details.

In Codat a payment contains details of:

  • When the payment was recorded in the accounting system.
  • How much it is for and in what currency that amount is in.
  • Who the payment has been paid by, the customer.
  • The breakdown of the types of payments, the line items.

📘

Payments or bill payments?

In Codat, payments represent accounts receivable only. For accounts payable, see bill payments. These include bills and credit notes against bills.

Data model

Field

Type

Description

id

string

Identifier for the payment, unique to the company in the accounting platform.

customerRef

customerRef

Customer the payment is recorded against in the accounting platform.

accountRef

accountRef

Account the payment is recorded against in the accounting platform.

totalAmount

decimal

Amount of the payment in the payment currency. This value should never change and represents the amount of money paid into the customer's account.

currency

string
See currency

ISO currency code recorded for the payment in the accounting platform.

currencyRate

decimal
See currency rate

Rate to convert the total amount of the payment into the base currency for the company at the time of the payment.

date

string
See date

Date the payment was recorded in the accounting software.

note

string

Any additional information associated with the payment.

lines

An array of PaymentLines.

ModifiedDate

string
See date

Date the record was last updated in the Codat system.

sourceModifiedDate

string
See date

Date the record was last changed in the accounting system.

reference

string

Friendly reference for the payment.

Customer reference

Field

Type

Description

id

string

Unique identifier for the customer that the payment is recorded against in the accounting platform.

companyName

string

Name of the customer that the payment is recorded against in the accounting platform.

Payment lines

A payment line is an allocation of the portion of the payment. The sum of the amount on the lines should be equal to the total Amount.

Field

Type

Description

amount

decimal

Amount in the payment currency.

links

See PaymentLineLinks.

Payment links

The allocations of the payment. The sum of amount in links plus the line amount must be equal to zero.

Field

Type

Description

type

string

Types of payment line links, either:

  • Unknown

  • Unlinked - Not used

  • Invoice - ID refers to the invoice

  • CreditNote - ID refers to the credit note

  • Refund - ID refers to the sibling payment

  • Payment - ID refers to the sibling payment

  • PaymentOnAccount - ID refers to the customer

  • Other - ID refers to the customer

  • Manual Journal

  • Discount

id

string

Unique identifier of the transaction represented by the link.

amount

decimal

Amount by which the balance of the linked entity is altered, in the currency of the linked entity.

  • A negative link amount reduces the outstanding amount on the accounts receivable account.

  • A positive link amount increases the outstanding amount on the accounts receivable account.

currencyRate

decimal

Calculated as the amount of the payment allocated in the currency of the payment divided by the amount of the linked entity in the currency of the entity. When payment currencies and linked entity currencies are the same, the currencyRate is 1.

🚧

Requirements for reference fields

The customer reference fields are only populated if the corresponding data type has been synchronised. If you see null values for these fields, please complete a new sync for the corresponding data type. For example, sync the customers data type for customerRef.

Payment types

Payment of an invoice

A payment paying a single invoice has one entry in its lines array. This line has the following properties:

  • An amount that indicates the amount of the invoice that was paid. This is always positive.
  • A links array containing one element with the following properties:
    • A type that indicates the type of link, in this case an Invoice.
    • An id that contains the ID of the invoice that was paid.
    • An amount for the link is 0 totalAmount or the amount of the payment allocated to the invoice.

The amount field on the line equals the totalAmount on the payment.

Payment of multiple invoices

A single payment can pay multiple invoices. This can be represented in one of two formats depending on how the customer keeps their books:

  • The payment has multiple entries in its lines array, one for each invoice that is paid. Each line follows the example and rules described in Payment of an invoice.
  • The payment has a line with multiple links to each invoice. This occurs when the proportion of the original payment allocated to each invoice is not available.

Each line has the same properties as those described in Payment of an invoice, with the amount indicating how much of the payment was allocated to the invoice. The amount on lines equals the totalAmount on the payment.

Payments and refunds on account

A payment on account, that is a payment that doesn’t pay a specific invoice, has one entry in its lines array. The line has the following properties:

  • A totalAmount that indicates the amount paid by a customer or refunded to them by a company. A payment to the customer is always negative. A refund is always positive.
  • A links array containing one element with the following properties:
  • A type that indicates the type of link. For a payment this is PaymentOnAccount. For a refund this is Refund.
  • The id containing the ID of the customer.
  • An amount for the link is 0 - totalAmount or the amount of the payment or refund.

It is possible to have a payment that is part on account and part allocated to an invoice. Each line should follow the examples above.

Using a credit note to pay an invoice

The payment of an invoice using a credit note has one entry in its lines array. This line has the following properties:

  • An amount that indicates the amount of money moved, which in this case is 0, as the credit note and invoice allocation must balance each other.
  • A links array containing two elements:
    • The first link has:
      • A type that indicates the type of link, in this case an Invoice.
      • An id that contains the ID of the invoice that was paid.
    • The second link has:
      • A type that indicates the type of link, in this case a CreditNote.
      • An id that contains the ID of the credit note used by this payment.

The amount field on the line equals the totalAmount on the payment.

Refunding a credit note

A payment refunding a credit note has one entry in its lines array. This line has the following properties:

  • An amount that indicates the amount of the credit note that was refunded. This is always negative for a refund.
  • A links array that contains one element with the following properties:
    • A type that indicates the type of link, in this case a CreditNote.
    • An id that contains the ID of the credit note that was refunded.

The totalAmount field on the payment equals the amount field of the line. These are both negative, as this is money leaving accounts receivable.

Refunding a payment

If a payment is refunded, for example, if a customer overpaid an invoice and the overpayment is returned to the customer, there are two payment records:

  • One for the incoming over payment.
  • Another for the outgoing refund.

The payment issuing the refund has a negative totalAmount. This payment also has one entry in its lines array with the following properties:

  • An amount that indicates the amount that was refunded. This is always negative.
  • A links array that contains one element with the following properties:
    • A type that indicates the type of link, in this case a Payment.
    • An id that contains the ID of the payment that was refunded.

The amount field on the line equals the totalAmount on the payment and is negative, as this is money leaving accounts receivable.

The payment that was refunded has a line where the amount is positive and the type of the link is Refund. This payment may have several entries in its lines array if it was used to partly pay an invoice.

For example: A £1,050 payment on a £1,000 invoice with a refund of £50 has two lines:

  • One for £1,000 linked to the invoice that was paid.
  • Another for £50 linked to the payment that refunded the overpayment with a type of Refund and an ID that corresponds to the payment.

The line linked to the payment has the following properties:

  • An amount that indicates the amount that was refunded. This is positive as its money that was added to accounts receivable. Its balanced out by the negative amount of the refund.
  • A links array containing one element with the following properties:
    • A type that indicates the type of link, in this case a Refund.
    • An id that contains the ID of the payment that refunded this line.

📘

Support for linked payments

Not all accounting packages support linking payments in this way. In some platforms, you may see a payment on account and a refund on account.

Foreign currencies

There are two types of currency rate that are included in the payments data type:

Payment currency rate:

  • Base currency of the accounts receivable account.
  • Foreign currency of the payment.

Payment line link currency rate:

  • Base currency of the item the link represents.
  • Foreign currency of the payment.

These two rates allow the calculation of currency loss or gain for any of the transactions affected by the payment lines. The second rate is used when a payment is applied to an item in a currency that doesn't match either:

  • The base currency for the accounts receivable account.
  • The currency of the item.
{
    "id": "123",
    "note": ""
    "totalAmount": 99.99,
    "currency": "GBP",
    "lines": [
        {
            "amount": 99.99,
            "links": [
                {
                    "type": "Invoice",
                    "id": "178",
                    "amount": -50,
                    "currencyRate":  1.9998,
                }
            ]
        }
    ]
}

Example data

📘

Object properties

For the sake of brevity, the examples here may omit properties from objects. For the full object definition, see Payments.

Simple examples

{
    "totalAmount": 1000,
    "lines": [
        {
            "amount" : 1000,
            "links" : [
                {
                    "type" : "Invoice",
                    "id" : "x",
                    "amount" : -1000
                }
            ]
        }
    ]
}
{
    "totalAmount": 0,
    "lines": [
        {
            "amount" : 0,
            "links" : [
                {
                    "type" : "Invoice",
                    "id" : "x",
                    "amount" : -1000
                },
                {
                    "type" : "CreditNote",
                    "id" : "y",
                    "amount" : 1000
                }
            ]
        }
    ]
}
{
    "totalAmount": 2000,
    "lines": [
        {
            "amount" : 1000,
            "links" : [
                {
                    "type" : "Invoice",
                    "id" : "x",
                    "amount" : -1000
                }
            ]
        },
        {
            "amount" : 1000,
            "links" : [
                {
                    "type" : "PaymentOnAccount",
                    "id" : "y",
                    "amount" : -1000
                }
            ]
        }
    ]
}
{
    "totalAmount": -1000,
    "lines": [
        {
            "amount" : -1000,
            "links" : [
                {
                    "type" : "CreditNote",
                    "id" : "y",
                    "amount" : 1000
                }
            ]
        }
    ]
}
{
    "totalAmount": -1000,
    "lines": [
        {
            "amount" : -1000,
            "links" : [
                {
                    "type" : "PaymentOnAccount",
                    "id" : "y",
                    "amount" : 1000
                }
            ]
        }
    ]
}
{
    "id" : payment-001",
    "totalAmount": 1000,
    "lines": [
        {
            "amount" : 1000,
            "links" : [
                {
                    "type" : "Refund",
                    "id" : "refund-001",
                    "amount" : -1000
                }
            ]
        }
    ]
}
{
    "id" : "refund-001",
    "totalAmount": -1000,
    "lines": [
        {
            "amount" : -1000,
            "links" : [
                {
                    "type" : "Payment",
                    "id" : "payment-001",
                    "amount" : 1000
                }
            ]
        }
    ]
}
{
    "totalAmount": 250,
    "lines": [
        {
            "amount": 0,
            "links": [
                {
                    "type": "Invoice",
                    "id": "x",
                    "amount": -750
                }, 
                {
                    "type": "CreditNote",
                    "id": "y",
                    "amount": 750
                }
            ]
        },
        {
            "amount": 250,
            "links": [
                {
                    "type": "Invoice",
                    "id": "x",
                    "amount": -250
                }
            ]
        }
    ]
}

Complex examples

{
    "totalAmount": 1000,
    "lines": [
        {
            "amount" : 0,
            "links" : [
                {
                    "type" : "Invoice",
                    "id" : "x",
                    "amount" : -1000
                },
                {
                    "type" : "CreditNote",
                    "id" : "y",
                    "amount" : 1000
                }
            ]
        },
        {
            "amount" : 0,
            "links" : [
                {
                    "type" : "Invoice",
                    "id" : "x",
                    "amount" : -1000
                },
                {
                    "type" : "CreditNote",
                    "id" : "z",
                    "amount" : 1000
                }
            ]
        },
        {
            "amount" : 1000,
            "links" : [
                {
                    "type" : "Invoice",
                    "id" : "x",
                    "amount" : -1000
                }
            ]
        }
    ]
}
{
    "totalAmount": 2000,
    "lines": [
        {
            "amount" : 0,
            "links" : [
                {
                    "type" : "Invoice",
                    "id" : "x",
                    "amount" : -1000
                },
                {
                    "type" : "CreditNote",
                    "id" : "y",
                    "amount" : 1000
                }
            ]
        },
        {
            "amount" : 0,
            "links" : [
                {
                    "type" : "Invoice",
                    "id" : "x",
                    "amount" : -1000
                },
                {
                    "type" : "CreditNote",
                    "id" : "z",
                    "amount" : 1000
                }
            ]
        },
        {
            "amount" : 1000,
            "links" : [
                {
                    "type" : "Invoice",
                    "id" : "x",
                    "amount" : -1000
                }
            ]
        },
        {
            "amount" : 1000,
            "links" : [
                {
                    "type" : "PaymentOnAccount",
                    "id" : "customer-001",
                    "amount" : -1000
                }
            ]
        }
    ]
}
{
    "totalAmount": 0,
    "lines": [
        {
            "amount" : 0,
            "links" : [
                {
                    "type" : "Invoice",
                    "id" : "w",
                    "amount" : -1000
                },
                {
                    "type" : "Invoice",
                    "id" : "x",
                    "amount" : -1000
                },
                {
                    "type" : "CreditNote",
                    "id" : "y",
                    "amount" : 1000
                },
                {
                    "type" : "CreditNote",
                    "id" : "z",
                    "amount" : 1000
                }
            ]
        }
    ]
}
{
    "totalAmount": 2000,
    "lines": [
        {
            "amount" : 1000,
            "links" : [
                {
                    "type" : "Invoice",
                    "id" : "w",
                    "amount" : -1000
                },
                {
                    "type" : "Invoice",
                    "id" : "x",
                    "amount" : -1000
                },
                {
                    "type" : "Invoice",
                    "id" : "u",
                    "amount" : -1000
                },
                {
                    "type" : "CreditNote",
                    "id" : "y",
                    "amount" : 1000
                },
                {
                    "type" : "CreditNote",
                    "id" : "z",
                    "amount" : 1000
                }
            ]
        },
        {
            "amount" : 1000,
            "links" : [
                {
                    "type" : "Refund",
                    "id" : "refund-001",
                    "amount" : -1000
                }
            ]
        }
    ]
}
{
    "id" : "refund-001",
    "totalAmount": -1000,
    "lines": [
        {
            "amount" : -1000,
            "links" : [
                {
                    "type" : "Payment",
                    "id" : "payment-001",
                    "amount" : 1000
                }
            ]
        }
    ]
}

Payment on account is used to pay an invoice in January and February:

{
    "id": "001",
    "totalAmount": 5000,
    "date" : "1901-01-01",
    "lines": [
        {
            "amount" : 1000,
            "links" : [
                {
                    "type" : "Invoice",
                    "id" : "x",
                    "amount" : -1000
                }
            ]
        },
        {
            "amount" : 4000,
            "links" : [
                {
                    "type" : "PaymentOnAccount",
                    "id" : "y",
                    "amount" : -4000
                }
            ]
        }
    ]
}
{
    "id": "001",
    "totalAmount": 5000,
    "date" : "1901-01-01",
    "lines": [
        {
            "amount" : 1000,
            "links" : [
                {
                    "type" : "Invoice",
                    "id" : "x",
                    "amount" : -1000
                }
            ]
        },
        {
            "amount" : 1000,
            "links" : [
                {
                    "type" : "Invoice",
                    "id" : "y",
                    "amount" : -1000
                }
            ]
        },
        {
            "amount" : 3000,
            "links" : [
                {
                    "type" : "PaymentOnAccount",
                    "id" : "y",
                    "amount" : -3000
                }
            ]
        }
    ]
}
{
    "totalAmount": 500,
    "lines": [
        {
            "amount": 500,
            "links": [{
                    "type": "Invoice",
                    "id": "a",
                    "amount": -1000
                }, {
                    "type": "Invoice",
                    "id": "b",
                    "amount": -1000
                }, {
                    "type": "CreditNote",
                    "id": "y",
                    "amount": 750
                },{
                    "type": "CreditNote",
                    "id": "z",
                    "amount": 750
                }
            ]
        }
    ]
}

Did this page help you?