Guide
10 min
Create an Invoice
Generate and send a professional invoice via the YardPay Pro API. Includes line items, tax calculation, QR codes, and payment tracking.
Prerequisites
- A sandbox API key — see the Authentication guide
- Familiar with processing payments (optional, for testing invoice payments)
1
Create an Invoice
Create an invoice with line items, customer info, and optional tax/discounts. Each item can be a Product, Service, Subscription, Fee, Discount, or Tax.
curl -X POST /v1/invoice \
-H "Content-Type: application/json" \
-H "x-api-key: sk_test_YOUR_API_KEY" \
-d '{
"description": "Website Design Services - March 2026",
"currencyCode": "JMD",
"paymentDueDate": "2026-04-15T00:00:00Z",
"notes": "Thank you for your business!",
"items": [
{
"name": "Website Design",
"description": "Custom landing page design",
"unitCost": 50000.00,
"quantity": 1,
"taxRate": 15.0,
"invoiceItemTypeId": "Service"
},
{
"name": "Hosting (1 year)",
"unitCost": 12000.00,
"quantity": 1,
"taxRate": 15.0,
"invoiceItemTypeId": "Service"
}
],
"sourceInfo": {
"firstName": "John",
"lastName": "Doe",
"email": "[email protected]"
},
"successUrl": "https://yoursite.com/payment/success",
"cancelUrl": "https://yoursite.com/payment/cancel"
}'The response includes the invoice id, identifier (UUID for public links), and calculated totals.
2
Understand Invoice Statuses
| Status | Description | Can Pay? |
|---|---|---|
Draft | Not yet finalized | No |
Pending | Created and awaiting payment | Yes |
Sent | Sent to the customer | Yes |
PartiallyPaid | Some amount received | Yes |
Paid | Fully paid | No |
Overdue | Past the due date | Yes |
Cancelled | Cancelled by merchant | No |
Expired | Past validity period | No |
3
Share the Invoice
Invoices can be shared via a public payment link or QR code. Both use the invoice identifier (UUID).
Payment Link
/invoice/{identifier}QR Code (returns PNG image)
GET /v1/invoice/qrcode/{identifier}Embed QR Code in HTML
<img
src="/v1/invoice/qrcode/{identifier}"
alt="Scan to pay"
width="200"
height="200"
/>4
Retrieve and Track Invoices
By Reference Code (public, no auth)
GET /v1/invoice/getByReference(code='INV-2024-001')
By ID (authenticated)
GET /v1/invoice/{id}List with OData Filters
GET /v1/invoice?$filter=status eq 'Pending'&$orderby=createdDateTime desc&$top=20
5
Listen for Payment Events
Use SignalR or webhooks to receive real-time notifications when an invoice is paid. This avoids polling the API.
// SignalR — listen for invoice updates
import { HubConnectionBuilder } from '@microsoft/signalr';
const connection = new HubConnectionBuilder()
.withUrl('/hubs/notifications')
.withAutomaticReconnect()
.build();
connection.on('InvoiceUpdated', (notification) => {
console.log(`Invoice ${notification.invoiceId} → ${notification.status}`);
if (notification.status === 'Paid') {
// Fulfill the order
}
});
await connection.start();Complete Example (JavaScript)
import axios from 'axios';
const client = axios.create({
baseURL: window.location.origin,
headers: {
'Content-Type': 'application/json',
'x-api-key': 'sk_test_YOUR_API_KEY',
},
});
// Create the invoice
const { data: invoice } = await client.post('/v1/invoice', {
description: 'Consulting Services',
currencyCode: 'JMD',
paymentDueDate: '2026-04-15T00:00:00Z',
items: [
{ name: 'Consulting', unitCost: 25000, quantity: 2, taxRate: 15, invoiceItemTypeId: 'Service' },
{ name: 'Report', unitCost: 5000, quantity: 1, invoiceItemTypeId: 'Product' },
],
sourceInfo: {
firstName: 'Jane', lastName: 'Smith', email: '[email protected]',
},
successUrl: 'https://yoursite.com/thanks',
});
console.log('Invoice created:', invoice.identifier);
console.log('Payment link: /invoice/' + invoice.identifier);
console.log('QR code: /v1/invoice/qrcode/' + invoice.identifier);
console.log('Total:', invoice.totalCost, invoice.currencyCode);