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.

Endpoints

post
/PaymentNotice
 get
/PaymentNotice/{id}
 get
/PaymentNotice

Attributes

id
string required

The identifier of the payment notice

status
string required

Required by the FHIR spec. Canvas only supports payments with a status of active.

request
json required

A reference to the patient whose balance this payment is being applied to.

created
datetime required

Required by the FHIR spec. Canvas recommends sending the current datetime on create; however, the value returned by the search interaction will be the creation timestamp of the actual database record.

payment
json required

The payment field is required by FHIR, but is not used by Canvas. Canvas recommends sending an empty JSON object.

recipient
json required

The recipient field is required by FHIR, but is not used by Canvas. Canvas recommends sending an empty JSON object.

amount
json required

The payment amount.

Click to view child attributes
value
decimal

The amount of USD to apply to the patient’s balance.

currency
code

Only USD is supported, and USD will be used regardless of what is provided.

paymentStatus
json

Status of the payment

Click to view child attributes
coding
array

In search responses, there will be a single coding of paid.

post
/PaymentNotice

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.

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.

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

id
string required

The identifier of the payment notice

status
string required

Required by the FHIR spec. Canvas only supports payments with a status of active.

request
json required

A reference to the patient whose balance this payment is being applied to.

created
datetime required

Required by the FHIR spec. Canvas recommends sending the current datetime on create; however, the value returned by the search interaction will be the creation timestamp of the actual database record.

payment
json required

The payment field is required by FHIR, but is not used by Canvas. Canvas recommends sending an empty JSON object.

recipient
json required

The recipient field is required by FHIR, but is not used by Canvas. Canvas recommends sending an empty JSON object.

amount
json required

The payment amount.

Click to view child attributes
value
decimal

The amount of USD to apply to the patient’s balance.

currency
code

Only USD is supported, and USD will be used regardless of what is provided.

paymentStatus
json

Status of the payment

Click to view child attributes
coding
array

In search responses, there will be a single coding of paid.

Responses

201 Created
The server has successfully processed the request, the new resource has been created and is now ready for interaction.

Errors

400 Bad Request
The request was invalid or cannot be otherwise served. An accompanying error message will explain further.
401 Unauthorized
The request requires user authentication.
403 Forbidden
The request requires user authorization.
405 Method Not Allowed
The request performs an operation that is either not supported or allowed.
422 Unprocessable Entity
The request cannot be processed due to semantic issues or conflicts with the database state.
get
/PaymentNotice/{id}

PaymentNotice read

Read a PaymentNotice resource.

Path Parameters

id required
string
The unique identifier for the PaymentNotice

Responses

200 OK
Request was successful.

Errors

401 Unauthorized
The request requires user authentication.
403 Forbidden
The request requires user authorization.
404 Not Found
The requested resource was not found.
get
/PaymentNotice

PaymentNotice search

Search for PaymentNotice resources.

Query Parameters

_id
string

The Canvas-issued unique identifier of the PaymentNotice

request
string

A reference to the patient whose balance the payment was applied to.

Responses

200 OK
Request was successful.

Errors

400 Bad Request
The request was invalid or cannot be otherwise served. An accompanying error message will explain further.
401 Unauthorized
The request requires user authentication.
403 Forbidden
The request requires user authorization.
  • 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",
    "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",
    "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",
    "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%2Fb8dfa97bdcdf4754bcd8197ca78ef0f0' \
     --header 'Authorization: Bearer <token>' \
     --header 'accept: application/json'

  • import requests

url = "https://fumage-example.canvasmedical.com/PaymentNotice?request=Patient%2Fb8dfa97bdcdf4754bcd8197ca78ef0f0"

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",
                "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"
      }
    }
  ]
}