Skip to main content
Finora Business
Finora Business
Sign InStart Free Trial

Reference

Payments & Collections

Enterprise only

Generate hosted payment links for invoices and create NFC tap-to-pay sessions. Auto-reconciles to the invoice on completion.

The payments module wires Finora Business to a bank partner's payment infrastructure. Generate a hosted link to send to a customer, or create an NFC session for in-person tap-to-pay. When the payment completes, Finora Business auto-creates a receipt, applies it to the invoice, and posts the GL entries.

Generate a payment link

POST/v1/businesses/{businessId}/payments/generate-link

Generates a hosted payment link for an invoice. Share with the customer; Finora Business auto-reconciles on payment.

Body

FieldTypeRequiredNotes
invoiceIdstringyesThe invoice to collect against.
expiresInHoursintegernoDefault 24.
allowPartialPaymentbooleannoDefault false.
callbackUrlstringnoURL to receive a payment-completion callback in addition to webhooks.
metadataobjectnoFree-form key/values attached to the payment record.

Response — 201

{
  "success": true,
  "data": {
    "paymentLinkId": "pl_abc123",
    "invoiceId": "inv_abc123",
    "invoiceNumber": "INV-2026-042",
    "amountKobo": 53750000,
    "paymentUrl": "https://pay.finorabusiness.com/p/pl_abc123",
    "shortUrl": "https://pay.finorabusiness.com/p/abc123",
    "qrCodeUrl": "https://api.finorabusiness.com/v1/payment-links/pl_abc123/qr.png",
    "expiresAt": "2026-04-18T10:30:00.000Z",
    "status": "active"
  }
}

Create a tap-to-pay session

POST/v1/businesses/{businessId}/payments/tap-to-pay

Creates an NFC payment session for in-person capture via the partner mobile app.

Body

FieldTypeRequiredNotes
amountKobointegeryesAmount in kobo.
descriptionstringyesShown on the device prompt.
invoiceIdstringnoLink to an invoice for auto-reconciliation.
customerIdstringnoLink to a customer record.
deviceIdstringyesBank partner app device identifier.

Response — 201

{
  "success": true,
  "data": {
    "sessionId": "nfc_sess_001",
    "amountKobo": 5375000,
    "status": "awaiting_tap",
    "expiresAt": "2026-04-17T10:35:00.000Z",
    "deviceId": "dev_001"
  }
}

Sessions expire after 5 minutes if no tap is detected. On a successful tap, the partner processes the payment and calls the payment webhook below.

Payment webhook (inbound)

POST/v1/webhooks/alat-payment

Webhook endpoint for the bank partner to notify Finora Business of payment completions. HMAC-SHA256 authenticated, not API-key.

Inbound payload

The partner POSTs a signed body matching:

{
  "event": "payment.completed",
  "paymentId": "pay_xyz789",
  "paymentLinkId": "pl_abc123",
  "sessionId": null,
  "amountKobo": 53750000,
  "currency": "NGN",
  "reference": "PAY-20260417-001",
  "timestamp": "2026-04-17T10:30:00.000Z",
  "metadata": {
    "businessId": "biz_001",
    "invoiceId": "inv_abc123"
  },
  "signature": "sha256=a1b2c3d4..."
}

Finora Business validates the signature, creates the receipt, updates the invoice, posts GL, and fires the payment.received + invoice.paid webhooks to your registered endpoints. Idempotent on paymentId — duplicate deliveries are safely ignored.

Response — 200

{
  "success": true,
  "data": {
    "received": true,
    "receiptId": "rec_auto_001",
    "receiptNumber": "REC-2026-045",
    "invoiceStatus": "paid",
    "glJournalEntryId": "je_pay_001"
  }
}

403 response for retail keys

{
  "success": false,
  "error": {
    "code": "ENTERPRISE_ONLY",
    "message": "This endpoint requires an enterprise subscription. Contact sales at https://finorabusiness.com/contact",
    "requestId": "req_..."
  }
}

Want payments wired into your banking stack?

Custom payment links, tap-to-pay, and HMAC-verified inbound webhooks are enterprise-only — they require a partner agreement. Contact sales to get started.

Related endpoints

  • Invoices — the invoices payment links reconcile against
  • Receipts — the receipts auto-created on payment
  • Webhooks — outbound payment.received and invoice.paid events

Reference index

Back to all modules