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
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.

Click to view child attributes
system
string
code
string

In search responses, the code of paid will be noted.

Responses

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

Canvas returns the created resource's id as a UUID within the location header and a null response body.

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

Response Payload Attributes

id
string

The identifier of the payment notice

status
string

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

request
json

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

created
datetime

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

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

recipient
json

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

amount
json

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.

Click to view child attributes
system
string
code
string

In search responses, the code of paid will be noted.

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.

Response Payload Attributes

resourceType
string

The FHIR Resource name.

type
string

This element and value designate that the bundle is a search response. Search result bundles will always have the Bundle.type of searchset .

total
integer

The number of resources that match the search parameter.

link
array[json]

Attributes relevant to pagination, see our Pagination page for more detail.

Click to view child attributes
relation
enum [self|first|next|last]

The relation of the page search

url

The search url for the specific relation

entry
array[json]

The results bundle that lists out each object returned in the search

Click to view child attributes
resource
json

The attributes specific to the resource type, see the Attributes section below

Attributes

id
string

The identifier of the payment notice

status
string

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

request
json

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

created
datetime

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

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

recipient
json

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

amount
json

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.

Click to view child attributes
system
string
code
string

In search responses, the code of paid will be noted.

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