PaymentNotice
This resource provides the status of the payment for goods and services rendered, and the request and response resource references.
https://hl7.org/fhir/R4/paymentnotice.html
In Canvas, FHIR PaymentNotice records payments made toward a patient’s balance.
See this Zendesk article for information about how to collect payments.
PaymentNotice create
Create a PaymentNotice resource.
This endpoint can be used to note a payment that has been collected from a patient and deduct the amount from their balance.
Moreover, this endpoint can be used to denote copayments as well. For that purpose, use the valueReference extension to link the associated Claim for which the copayment is being processed. Adding that extension determines the purpose of action for this endpoint, meaning that it would be treated as a copayment transaction if the Claim reference extension is present.
Don’t overpay! Requests that would bring the account balance negative will be rejected. Example: If a patient owes $5, Canvas would reject a PaymentNotice with a value that is greater than $5. Balance can only go negative if performing copayments as customers could be charged prior to recieveing a medical service.
A created payment notice can be found in Canvas by going to the patient’s chart, and clicking the paper icon in the top right corner. The created payment notice will be displayed under receipts. The “Originator” will be automatically set to Canvas Bot.
As payment notices are created, they will be applied to charges in chronological order of creation date, from oldest to newest.
Attributes
Specific FHIR extensions on resources are supported to be able to map some Canvas specific attributes. The copayment extensions contains references to claims used for copayments.
If you are not denoting a copayment, then use PaymentNotice without the copayment extension for other type of payments.
Identifies the meaning of the extension
Use this extension to denote and reference a Claim targeted for a copayment. For producing copayments, only a single Claim is accepted.
Identifies the meaning of the extension.
The reference string of the Claim used for copayments in the format of "Claim/f0dfefbe-3fe0-4ee7-bd44-636f7be073e9".
The status of the resource instance.
A reference to the patient whose balance this payment is being applied to.
The reference string of the patient in the format of "Patient/a39cafb9d1b445be95a2e2548e12a787".
Type the reference refers to (e.g. “Patient”).
Required by the FHIR spec. Canvas recommends sending the current date on create; however, the value returned by the search interaction will be the creation timestamp of the actual database record in Canvas.
The payment field is required by FHIR, but is not used by Canvas.
Canvas recommends sending an empty JSON object.
The recipient field is required by FHIR, but is not used by Canvas.
Canvas recommends sending an empty JSON object.
The payment amount.
The amount of USD to apply to the patient’s balance.
Responses
Canvas returns the created resource's id as a UUID within the
location header and a null response body.Errors
PaymentNotice read
Read a PaymentNotice resource.
Path Parameters
Response Payload Attributes
The identifier of the payment notice.
Specific FHIR extensions on resources are supported to be able to map some Canvas specific attributes. The copayment extensions contains references to claims used for copayments.
Identifies the meaning of the extension
A nested extension that contains references to Claims related to copayments.
Identifies the meaning of the extension.
The reference string of the Claim used for copayments in the format of "Claim/f0dfefbe-3fe0-4ee7-bd44-636f7be073e9".
The status of the resource instance.
A reference to the patient whose balance this payment is being applied to.
The reference string of the patient in the format of "Patient/a39cafb9d1b445be95a2e2548e12a787".
Type the reference refers to (e.g. “Patient”).
Required by the FHIR spec. Canvas recommends sending the current date on create; however, the value returned by the search interaction will be the creation timestamp of the actual database record in Canvas.
The payment field is required by FHIR, but is not used by Canvas.
Text alternative for the resource.
The recipient field is required by FHIR, but is not used by Canvas.
Text alternative for the resource.
The payment amount.
The amount of USD to apply to the patient’s balance.
ISO 4217 Currency Code. Only USD is supported, and USD will be used regardless of what is provided.
Issued or cleared Status of the payment.
Code defined by a terminology system. There will be a single coding of paid.
In search responses, the code of paid will be noted.
Responses
Errors
PaymentNotice search
Search for PaymentNotice resources.
Query Parameters
The Canvas-issued unique identifier of the PaymentNotice
The patient reference associated with the PaymentNotice in the format Patient/a39cafb9d1b445be95a2e2548e12a787.
Response Payload Attributes
The FHIR Resource name.
This element and value designate that the bundle is a search response. Search result bundles will always have the Bundle.type of searchset .
The number of resources that match the search parameter.
Attributes relevant to pagination, see our Pagination page for more detail.
The relation of the page search
The search url for the specific relation
The results bundle that lists out each object returned in the search
The attributes specific to the resource type, see the Attributes section below
Attributes
The identifier of the payment notice.
Specific FHIR extensions on resources are supported to be able to map some Canvas specific attributes. The copayment extensions contains references to claims used for copayments.
Identifies the meaning of the extension
A nested extension that contains references to Claims related to copayments.
Identifies the meaning of the extension.
The reference string of the Claim used for copayments in the format of "Claim/f0dfefbe-3fe0-4ee7-bd44-636f7be073e9".
The status of the resource instance.
A reference to the patient whose balance this payment is being applied to.
The reference string of the patient in the format of "Patient/a39cafb9d1b445be95a2e2548e12a787".
Type the reference refers to (e.g. “Patient”).
Required by the FHIR spec. Canvas recommends sending the current date on create; however, the value returned by the search interaction will be the creation timestamp of the actual database record in Canvas.
The payment field is required by FHIR, but is not used by Canvas.
Text alternative for the resource.
The recipient field is required by FHIR, but is not used by Canvas.
Text alternative for the resource.
The payment amount.
The amount of USD to apply to the patient’s balance.
ISO 4217 Currency Code. Only USD is supported, and USD will be used regardless of what is provided.
Issued or cleared Status of the payment.
Code defined by a terminology system. There will be a single coding of paid.
In search responses, the code of paid will be noted.
Responses
Errors
curl --request POST \ --url 'https://fumage-example.canvasmedical.com/PaymentNotice' \ --header 'Authorization: Bearer <token>' \ --header 'accept: application/json' \ --header 'content-type: application/json' \ --data ' { "resourceType": "PaymentNotice", "extension": [ { "extension": [ { "url": "claim", "valueReference": { "reference": "Claim/f0dfefbe-3fe0-4ee7-bd44-636f7be073e9" } } ], "url": "http://schemas.canvasmedical.com/fhir/copayment-claims" } ], "status": "active", "request": { "reference": "Patient/bc4ec998a49745b488f552bebddf7261" }, "created": "2023-09-12", "payment": {}, "recipient": {}, "amount": { "value": 10.00, "currency": "USD" } }'import requests url = "https://fumage-example.canvasmedical.com/PaymentNotice" headers = { "accept": "application/json", "Authorization": "Bearer <token>", "content-type": "application/json" } payload = { "resourceType": "PaymentNotice", "extension": [ { "extension": [ { "url": "claim", "valueReference": { "reference": "Claim/f0dfefbe-3fe0-4ee7-bd44-636f7be073e9" } } ], "url": "http://schemas.canvasmedical.com/fhir/copayment-claims" } ], "status": "active", "request": { "reference": "Patient/bc4ec998a49745b488f552bebddf7261" }, "created": "2023-09-12", "payment": {}, "recipient": {}, "amount": { "value": 10.00, "currency": "USD" } } response = requests.post(url, json=payload, headers=headers) print(response.text)
null{ "resourceType": "OperationOutcome", "issue": [ { "severity": "error", "code": "invalid", "details": { "text": "Bad request" } } ] }{ "resourceType": "OperationOutcome", "issue": [ { "severity": "error", "code": "unknown", "details": { "text": "Authentication failed" } } ] }{ "resourceType": "OperationOutcome", "issue": [ { "severity": "error", "code": "forbidden", "details": { "text": "Authorization failed" } } ] }{ "resourceType": "OperationOutcome", "issue": [ { "severity": "error", "code": "not-supported", "details": { "text": "Operation is not supported" } } ] }{ "resourceType": "OperationOutcome", "issue": [ { "severity": "error", "code": "business-rule", "details": { "text": "Unprocessable entity" } } ] }
curl --request GET \ --url 'https://fumage-example.canvasmedical.com/PaymentNotice/<id>' \ --header 'Authorization: Bearer <token>' \ --header 'accept: application/json'import requests url = "https://fumage-example.canvasmedical.com/PaymentNotice/<id>" headers = { "accept": "application/json", "Authorization": "Bearer <token>" } response = requests.get(url, headers=headers) print(response.text)
{ "resourceType": "PaymentNotice", "id": "297e160c-8246-4054-8023-554d8e14c8c8", "extension": [ { "extension": [ { "url": "claim", "valueReference": { "reference": "Claim/f0dfefbe-3fe0-4ee7-bd44-636f7be073e9" } } ], "url": "http://schemas.canvasmedical.com/fhir/copayment-claims" } ], "status": "active", "request": { "reference": "Patient/3f688bb915d04e168dbfa635da4ab259", "type": "Patient" }, "created": "2023-10-17T18:27:59.232743+00:00", "payment": { "display": "Unused" }, "recipient": { "display": "Unused" }, "amount": { "value": 25.0, "currency": "USD" }, "paymentStatus": { "coding": [ { "system": "http://terminology.hl7.org/CodeSystem/paymentstatus", "code": "paid" } ] } }{ "resourceType": "OperationOutcome", "issue": [ { "severity": "error", "code": "unknown", "details": { "text": "Authentication failed" } } ] }{ "resourceType": "OperationOutcome", "issue": [ { "severity": "error", "code": "forbidden", "details": { "text": "Authorization failed" } } ] }{ "resourceType": "OperationOutcome", "issue": [ { "severity": "error", "code": "not-found", "details": { "text": "Unknown PaymentNotice resource 'a47c7b0e-bbb4-42cd-bc4a-df259d148ea1'" } } ] }
curl --request GET \ --url 'https://fumage-example.canvasmedical.com/PaymentNotice?request=Patient/b8dfa97bdcdf4754bcd8197ca78ef0f0' \ --header 'Authorization: Bearer <token>' \ --header 'accept: application/json'import requests url = "https://fumage-example.canvasmedical.com/PaymentNotice?request=Patient/b8dfa97bdcdf4754bcd8197ca78ef0f0" headers = { "accept": "application/json", "Authorization": "Bearer <token>" } response = requests.get(url, headers=headers) print(response.text)
{ "resourceType": "Bundle", "type": "searchset", "total": 1, "link": [ { "relation": "self", "url": "/PaymentNotice?request=Patient%2Fb8dfa97bdcdf4754bcd8197ca78ef0f0&_count=10&_offset=0" }, { "relation": "first", "url": "/PaymentNotice?request=Patient%2Fb8dfa97bdcdf4754bcd8197ca78ef0f0&_count=10&_offset=0" }, { "relation": "last", "url": "/PaymentNotice?request=Patient%2Fb8dfa97bdcdf4754bcd8197ca78ef0f0&_count=10&_offset=0" } ], "entry": [ { "resource": { "resourceType": "PaymentNotice", "id": "777094d2-664c-49b9-8926-b17a1b3fff8d", "status": "active", "request": { "reference": "Patient/b8dfa97bdcdf4754bcd8197ca78ef0f0", "type": "Patient" }, "created": "2023-09-13T01:10:49.515238+00:00", "payment": { "display": "Unused" }, "recipient": { "display": "Unused" }, "amount": { "value": 10.0, "currency": "USD" }, "paymentStatus": { "coding": [ { "system": "http://terminology.hl7.org/CodeSystem/paymentstatus", "code": "paid" } ] } } }, { "resource": { "resourceType": "PaymentNotice", "id": "3a2f4045-0591-460c-9bee-592ae7e8eef7", "extension": [ { "extension": [ { "url": "claim", "valueReference": { "reference": "Claim/f0dfefbe-3fe0-4ee7-bd44-636f7be073e9" } } ], "url": "http://schemas.canvasmedical.com/fhir/copayment-claims" } ], "status": "active", "request": { "reference": "Patient/b8dfa97bdcdf4754bcd8197ca78ef0f0", "type": "Patient" }, "created": "2023-09-13T01:11:22.767640+00:00", "payment": { "display": "Unused" }, "recipient": { "display": "Unused" }, "amount": { "value": 10.0, "currency": "USD" }, "paymentStatus": { "coding": [ { "system": "http://terminology.hl7.org/CodeSystem/paymentstatus", "code": "paid" } ] } } } ] }{ "resourceType": "OperationOutcome", "issue": [ { "severity": "error", "code": "invalid", "details": { "text": "Bad request" } } ] }{ "resourceType": "OperationOutcome", "issue": [ { "severity": "error", "code": "unknown", "details": { "text": "Authentication failed" } } ] }{ "resourceType": "OperationOutcome", "issue": [ { "severity": "error", "code": "forbidden", "details": { "text": "Authorization failed" } } ] }