Skip to main content

Record and reconcile bill payments

Record and reconcile bill payments in the SMB's accounting software

Overview​

Once the mapping is complete, your SMB customer will make a payment from your application, which you should then record and reconcile back to the SMB's accounting platform. A bill payment represents an allocation of money within any of your customer's accounts payable (AP) accounts.

You can see how this flow completes on our detailed process diagram below.

Detailed process diagram

We built Sync for Payables to handle various bill pay scenarios, for example:

  • A payment made against a bill, e.g. a credit card payment, cheque payment, or cash payment
  • An allocation of a supplier's credit note to a bill or a refund
  • A bill payment made directly to an AP account, e.g. an overpayment or a prepayment

Ways to pay a bill​

In this diagram, we have summarized approaches to bill payments and reconciliation that are available to you via Sync for Payables. Next, we will go through those options in detail.

A diagram of all bill payment options that Sync for Payables supports

Single bill payment​

If your SMB customer is making a payment to pay off a bill in full, use the Create bill payments endpoint and include the following properties in the request:

  • A totalAmount value (always positive) that indicates the amount of the bill that was paid.
  • A lines array that contains one element with the following properties:
    • An amount equal to the totalAmount above
    • A links array that contains one element with the following properties:
      • A type of link, in this case a Bill
      • An id of the bill that was paid
      • An amount with value of -totalAmount to indicate the full amount is allocated to the bill.

In case of partial payments, use the same endpoint and adjust the amount values according to the amount of the partial payment.

When paying a bill, pay attention to the following:

  • supplierRef.id is the same id as the supplierRef.id on the bill.
  • accountRef.id is the account the payment is made from as indicated during mapping.
  • totalAmount is the same as the amountDue on the bill.
  • date is the date that the payment is made to the supplier.

For example, review the bill mapped from Xero in the dropdown below and see how it can be paid using the Create bill payments in the subsequent code snippets.

Bill mapped from Xero
{
  "id": "59978bef-af2f-4a7e-9728-4997597c0980",
  "reference": "RPT445-1",
  "supplierRef": {
    "id": "dec56ceb-65e9-43b3-ac98-7fe09eb37e31",
    "supplierName": "PowerDirect"
  },
  "purchaseOrderRefs": [],
  "issueDate": "2023-02-09T00:00:00",
  "dueDate": "2023-02-19T00:00:00",
  "currency": "GBP",
  "currencyRate": 1,
  "lineItems": [
    {
      "description": "Monthly electricity",
      "unitAmount": 129.38,
      "quantity": 1,
      "discountAmount": 0,
      "subTotal": 129.38,
      "taxAmount": 6.47,
      "totalAmount": 135.85,
      "discountPercentage": 0,
      "accountRef": {
        "id": "d50842c3-af67-4233-b8c9-df3180f5b7bd"
      },
      "taxRateRef": {
        "id": "RRINPUT",
        "name": "5% (VAT on Expenses)",
        "effectiveTaxRate": 5
      },
      "trackingCategoryRefs": [],
      "isDirectCost": false
    }
  ],
  "withholdingTax": [],
  "status": "Open",
  "subTotal": 129.38,
  "taxAmount": 6.47,
  "totalAmount": 135.85,
  "amountDue": 135.85,
  "modifiedDate": "2023-04-17T14:51:35Z",
  "sourceModifiedDate": "2021-01-03T21:56:20",
  "paymentAllocations": [],
  "metadata": {
    "isDeleted": false
  }
}
const billPaymentResponse = await payablesClient.billPayments.create({
  billPayment: {
    supplierRef: {
      id: "dec56ceb-65e9-43b3-ac98-7fe09eb37e31"
    },
    accountRef: {
      id: "bd9e85e0-0478-433d-ae9f-0b3c4f04bfe4"
    },
    totalAmount: 135.85,
    currency: "GBP",
    currencyRate: 1,
    date: "2023-04-17T00:00:00",
    lines: [
      {
        amount: 135.85,
        links: [
          {
            id: "59978bef-af2f-4a7e-9728-4997597c0980",
            type: BillPaymentLineLinkType.Bill,
            amount: -135.85,
            currencyRate: 1,
          },
        ],
      },
    ]
  },
  companyId: companyId,
  connectionId: connectionId,
});

Multiple bill payment​

Your SMB customer may want pay multiple bills from a single supplier using one payment. Use the Create bill payments endpoint to do so and include a lines array with multiple elements for each bill and its respective amount.

Integration-specific examples
{
  "supplierRef": {
    "id": "dec56ceb-65e9-43b3-ac98-7fe09eb37e31"
  },
  "accountRef": {
    "id": "bd9e85e0-0478-433d-ae9f-0b3c4f04bfe4"
  },
  "totalAmount": 244.45,
  "currency": "GBP",
  "currencyRate": 1,
  "date": "2023-04-17T00:00:00",
  "lines": [
    {
      "amount": 135.85,
      "links": [
        {
          "type": "Bill",
          "id": "59978bef-af2f-4a7e-9728-4997597c0980",
          "amount": -135.85,
          "currencyRate": 1
        }
      ]
    },
    {
      "amount": 108.6,
      "links": [
        {
          "type": "Bill",
          "id": "2175c381-d323-4e20-8c94-7680ea7f85d3",
          "amount": -108.6,
          "currencyRate": 1
        }
      ]
    }
  ]
}

Batch bill payment​

In some accounting platforms (for example, Xero) your SMB customer can make a batch payment. It allows them to pay multiple bills from multiple suppliers in a single payment.

To do this with Sync for Payables, use the Create bill payments endpoint and leave the supplierRef parameter blank.

const billPaymentResponse = await payablesClient.billPayments.create({
  billPayment: {
    accountRef: {
      id: "d96ffd74-2394-4666-81c4-eebb76e51e21"
    },
    totalAmount: 6,
    date: "2022-09-06T00:00:00",
    lines: [
      {
        amount: 1,
        links: [
          {
            id: "0394819c-b784-454d-991c-c4711b9aca12",
            type: BillPaymentLineLinkType.Bill,
            amount: -1,
          },
        ],
      },
      {
        amount: 2,
        links: [
          {
            id: "428e3e38-e8fb-4c56-91b5-dd09dc2e6505",
            type: BillPaymentLineLinkType.Bill,
            amount: -2,
          },
        ],
      },
      {
        amount: 3,
        links: [
          {
            id: "76129542-2b2f-482f-b2b3-e612d9c1ba08",
            type: BillPaymentLineLinkType.Bill,
            amount: -3,
          },
        ],
      },
    ]
  },
  companyId: companyId,
  connectionId: connectionId,
});

Bill credit note​

If a company receives a credit note from their supplier, the company could use it to partially or fully offset the balance of any outstanding bills from the same supplier.

With Sync for Payables, you can do that using the following steps:

  1. Create a bill credit note.
  2. Allocate the credit note to a bill.

Create a credit note​

Start by creating a credit note using our Create bill credit note endpoint. 

const billCreditNoteCreateResponse = await payablesClient.billCreditNotes.create({
    billCreditNote: {
      billCreditNoteNumber: "JMY-1987",
      supplierRef: {
        id: "3a0d40a2-2698-4cf5-b7b2-30133c632ab6",
        supplierName: "Swanston Security"
      },
      withholdingTax: [],
      totalAmount: 25.44,
      totalDiscount: 0,
      subTotal: 25.44,
      totalTaxAmount: 4.24,
      discountPercentage: 0,
      remainingCredit: 0,
      status: BillCreditNoteStatus.Submitted,
      issueDate: "2023-02-09T00:00:00",
      currency: "GBP",
      currencyRate: 1,
      lineItems: [
        {
          description: "Refund as agreed due to window break when guard absent",
          unitAmount: 21.2,
          quantity: 1,
          discountAmount: 0,
          subTotal: 21.2,
          taxAmount: 4.24,
          totalAmount: 25.44,
          accountRef: {
            id: "f96c9458-d724-47bf-8f74-a9d5726465ce"
          },
          discountPercentage: 0,
          taxRateRef: {
            id: "INPUT2",
            name: "20% (VAT on Expenses)",
            effectiveTaxRate: 20
          },
          trackingCategoryRefs: []
        }
      ]
    },
    companyId: companyId,
    connectionId: connectionId,
  });
Integration-specific examples
{
    "billCreditNoteNumber": "JMY-1987",
    "supplierRef": {
        "id": "3a0d40a2-2698-4cf5-b7b2-30133c632ab6",
        "supplierName": "Swanston Security"
    },
    "withholdingTax": [],
    "totalAmount": 25.44,
    "totalDiscount": 0,
    "subTotal": 25.44,
    "totalTaxAmount": 4.24,
    "discountPercentage": 0,
    "remainingCredit": 0,
    "status": "Submitted",
    "issueDate": "2023-02-09T00:00:00",
    "currency": "GBP",
    "currencyRate": 1,
    "lineItems": [
        {
            "description": "Refund as agreed due to window break when guard absent",
            "unitAmount": 21.2,
            "quantity": 1,
            "discountAmount": 0,
            "subTotal": 21.2,
            "taxAmount": 4.24,
            "totalAmount": 25.44,
            "accountRef": {
                "id": "f96c9458-d724-47bf-8f74-a9d5726465ce"
            },
            "discountPercentage": 0,
            "taxRateRef": {
                "id": "INPUT2",
                "name": "20% (VAT on Expenses)",
                "effectiveTaxRate": 20
            },
            "trackingCategoryRefs": []
        }
    ]
}

Allocate credit note to a bill​

Now that you have the credit note, offset its balance against outstanding bills. Create a bill payment and include the credit note in the links array.

In some accounting platforms, you can combine a credit note and a partial payment to pay off the full balance of a bill.

const billPaymentResponse = await payablesClient.billPayments.create({
  billPayment: {
    supplierRef: {
      id: "3a0d40a2-2698-4cf5-b7b2-30133c632ab6"
    },
    accountRef: {
      id: "94b02f61-f95f-4873-b5b7-651ff9707325"
    },
    totalAmount: 0.00,
    currency: "GBP",
    currencyRate: 1,
    date: "2023-05-09T00:00:00",
    lines: [
      {
        amount: 45.00,
        links: [
          {
            id: "59978bef-af2f-4a7e-9728-4997597c0980",
            type: BillPaymentLineLinkType.Bill,
            amount: -25.44,
          },
          {
            id: "ee8bec08-2be8-40ba-acd0-d53d5df11235",
            type: BillPaymentLineLinkType.CreditNote,
            amount: 25.44,
          },
        ],
      },
    ]
  },
  companyId: companyId,
  connectionId: connectionId,
});
Integration-specific examples
Considerations

With Xero, you can only fully allocate a billCreditNote to a bill using a billPayment. If you want to also use a partial payment, two separate transactions should be created.

{
  "supplierRef": {
    "id": "3a0d40a2-2698-4cf5-b7b2-30133c632ab6"
  },
  "accountRef": {
    "id": "94b02f61-f95f-4873-b5b7-651ff9707325"
  },
  "totalAmount": 0,
  "currency": "GBP",
  "date": "2023-05-09T00:00:00",
  "lines": [
    {
      "amount": 45,
      "links": [
        {
          "type": "Bill",
          "id": "8e65df54-4bbd-41f3-b241-8da2588be341",
          "amount": -25.44
        },
        {
          "type": "CreditNote",
          "id": "ee8bec08-2be8-40ba-acd0-d53d5df11235",
          "amount": 25.44
        }
      ]
    }
  ]
}

Delete bills and payments​

In certain scenarios, your SMB customer may want to delete an existing bill or a bill payment - for example, if they made a mistake or no longer want to process the bill.

Use the Delete bill and Delete bill payment endpoints to support these requirements, and check them in our OAS for the most up-to-date integration coverage.

Delete bills​

const billDeleteResponse = await payablesClient.bills.delete({
  companyId: companyId,
  connectionId: connectionId,
  billId: billId,
});

Delete bill payments​

const billPaymentDeleteResponse = await payablesClient.billPayments.delete({
  companyId: companyId,
  connectionId: connectionId,
  billPaymentId: billPaymentId,
});
Recap

This concludes the bill pay process supported by Sync for Payables. You have provided your customer with their suppliers, bills, and bank accounts and enabled them to choose relevant payment methods. You have reflected the bill payments in their accounting system.

As a result, the customer will see these bills marked as paid in their software and their accounts payable liability and supplier balances reduced.

Was this page useful?
❤️
👍
🤔
👎
😭

Contents

Suggest edits