SAP S4HANA Billing Inbound

SAP S/4HANA Billing Inbound — Receiving Payment Confirmations

When SAP processes a payment against an HMIS bill, it can notify HMIS by calling a webhook. HMIS stores this confirmation against the bill, allowing finance staff to see which bills have been confirmed as paid in SAP.

---

How It Works

1. SAP processes a payment and identifies the related HMIS bill by its reference number (the HMIS bill reference, stored as deptId on the bill record).
2. SAP calls the HMIS confirmation endpoint with the payment details.
3. HMIS looks up the bill by its reference number and stores the confirmation.
4. If the same confirmation is sent again, HMIS returns the existing record (idempotent — no duplicate entries are created).

---

Configuration Required

The SAP integration must be enabled. The confirmation endpoint does not require any additional configuration beyond the core auth keys. See SAP S/4HANA Cloud Integration — Overview.

SAP side configuration: Your SAP system administrator must configure SAP to call the HMIS webhook URL when payments are posted against HMIS-originated accounting documents.

---

Webhook Endpoint

Your SAP administrator will need this information to configure the outbound call from SAP:

Field	Value
Method	POST
URL	https://{your-hmis-host}/hmis/api/sap/billing/confirm
Header	Finance: {hmis-api-key}
Content-Type	application/json

Request Body

{
  "sapDocumentNumber": "0100000042",
  "hmsBillReference":  "HMIS-2024-001234",
  "amount":            15000.00,
  "currency":          "LKR",
  "postingDate":       "2024-03-15",
  "note":              "Settled via online transfer"
}

Field	Required	Description
sapDocumentNumber	Yes	The SAP accounting document number
hmsBillReference	Yes	The HMIS bill reference number (must match the bill's reference in HMIS)
amount	No	Payment amount
currency	No	ISO currency code
postingDate	No	Date the payment was posted in SAP (yyyy-MM-dd)
note	No	Optional free-text note

Success Response

{
  "status": "success",
  "code": 200,
  "data": {
    "billId": 12345,
    "billReference": "HMIS-2024-001234",
    "sapDocumentNumber": "0100000042",
    "confirmedAt": "2024-03-15 14:32:00",
    "status": "confirmed"
  }
}

If the same confirmation has already been received:

{
  "status": "success",
  "code": 200,
  "data": {
    "status": "already_confirmed",
    ...
  }
}

---

Checking Confirmation Status

Finance staff or administrators can check whether a bill has been confirmed by SAP:

Request

GET /api/sap/billing/confirm/status/{billId}
Finance: <api-key>

Returns the stored confirmation record if it exists, or a 404 if the bill has not yet received a confirmation.

---

Troubleshooting

Problem	What to check
hmsBillReference is required	SAP call is missing the hmsBillReference field
Bill not found for reference: ...	The bill reference in the SAP payload does not match any HMIS bill reference. Verify the reference number format.
HTTP 500 from HMIS	Internal database error — check Payara server log. SAP should retry on 5xx.

---

Related Pages

• SAP S/4HANA Cloud Integration — Overview
• SAP S/4HANA Billing Outbound