Skip to main content
An invoice is one of your workspace’s invoices: the same record your team sees under Invoices in the Payra dashboard, whether it came from your ERP through Payra Connect or was created in the dashboard. The API reads them; it does not create or change them. Each open invoice carries its payment link, the hosted page where the customer pays it by card or bank account. Put that link behind a Pay button in your own customer portal, or on the invoice document you send, and Payra collects the payment, records it on the invoice and, for ERP-synced invoices, posts it back to the ERP as it does for every other payment.
1

Find the invoice

By the number your customer sees, or by your ERP’s id for it:
Response
external_id finds at most one invoice. number usually does too, but a number can repeat across customers, so read the list. With Payra’s id, GET /invoices/{id} reads the invoice directly.
2

Show what a customer owes

customer is the id from Customers, the same one a payment carries. The list runs newest first and pages with limit and starting_after.
3

Link to the payment page

Send the customer to payment_url. The page shows the invoice and takes the payment; when it succeeds, the invoice’s amount_paid and status change on your next read.

​
Amounts and status

Amounts are integers in the currency’s smallest unit (cents), as everywhere in the API.
  • total is the invoice total.
  • amount_paid is what was collected, refunds netted out.
  • amount_pending is what charges still processing will collect, such as a bank debit that has not settled. It is owed until a charge fails, and cannot be paid a second time meanwhile.
  • amount_due is what a payer can still pay today: the total less what was paid, pending or written off in the dashboard, and 0 once the invoice is paid or canceled (even when your ERP marked it paid without a payment through Payra). An early-payment discount the invoice offers is applied on the payment page, not here.
status is open while the invoice owes money, whether it has been sent or is still scheduled to be sent, and paid or canceled once settled. past_due is true from the day after due_date while an open invoice is unpaid; an invoice still scheduled to be sent is never past due. Drafts, and ERP invoices still awaiting approval in the dashboard, are not listed. payment_url is the link Payra prints on its own invoice emails and reminders: the same URL every time you read the invoice while it works, so you can store it or print it. It is null when there is nothing a payer could use: the invoice is settled, nothing is left to pay while a charge is pending, the invoice or its link expired, the link was revoked, or no link was ever made (an invoice created in the dashboard and never sent). Invoices that arrive from an ERP get their link as they arrive. Sending the invoice again from the dashboard makes a new link; the earlier one keeps working. A payment made through the link is recorded on the invoice and shown in the dashboard like any other. It is not a payment you created through the API, so it does not appear under Payments or in webhook events: read the invoice to learn that it was paid, or let your ERP learn it through Payra Connect.

​
Scopes and errors

Reading and listing need invoices:read. Keys created before this scope existed with every scope were given it; a key you narrowed on purpose was not, and a new key gets it from the Invoices group.