Postable Remittance

The Da Vinci Postable Remittance Reference Implementation Microservice that confirms the Postable Remittance Implementation Guide (IG)

A live demo is hosted by HL7 FHIR Foundry, where you may also download curated configurations to run yourself.

Local Setup

Requirements

Java version: 17
Maven version: 3.9.7 (3.6.3+)
Postgres version: 16
Docker/Docker Desktop (optional but helpful)

Create environment file

Create an .env file to store environmental variables used by the service.

Run touch .env
Copy and paste the data into the file below

DB_HOST=localhost
DB_PORT=5432
DB_NAME=postgres
DB_USERNAME=postgres
DB_PASSWORD=postgres
DB_ADMIN_USERNAME=postgres
DB_ADMIN_PASSWORD=postgres
LOGICAL_ENV_NAME=local
SERVICE_NAME=postable-remittance

Sample data

Run service to generate postable_remittance schema along with tables in the postgres database
Add data to the tables using insert queries from test-data.xlsx
Same queries are included in initial-data.sql to populate sample data upon service startup
If required, add new sql files under src/main/resources/db/seeds/ directory with additional queries

Postman collection

Postman collection with scenario based examples per endpoints based on sample data postman_collection.json

Getting Started

Running with Foundry docker-compose image

Login to Foundry and go to Account
Register a "Runtime Platform Environments" with name postable-remittance
Go to Catalog and select Postable Remittance Server
Click on "Configuration Wizard" and "Add Configuration to Platform"
Close the dialog box and go to My Environments and select both PostgresSQL Server and Postable Remittance Server
Click on "Docker Stack" and Foundry will generate a docker-compose.yml file that will be downloaded to your local machine with name docker-compose.yml
If you want to connect locally running DB client to the database, then add the port mapping to postgresql-server section in downloaded docker-compose.yml file as follows:
- ```
  postgresql-server:
    ports:
      - 5432:5432
```
Go to Downloads directory and run docker-compose.yml with command (--pull always will pull the latest image) docker-compose -f docker-compose.yml up -d --pull always
If port 5432 is exposed, then you can connect using DB client running locally.
OR connect to postgresql shell using docker network interface as follows:
- Since you register a new "Runtime Platform Environment" with name postable-remittance, your network interface name would be postable-remittance_network
- Run docker run -it --network postable-remittance_network --rm postgres psql -h postgresql-server -U postgres
- Input password mentioned in docker-compose.yml file to connect psql shell
- List out schemas using \dn and Select postgres database using \c postgres
- List out all tables using \dt+ postable_remittance.*
- Observe any table using describe \d postable_remittance.claim_query
- Fetch some data from table using SELECT * FROM postable_remittance.claim_query LIMIT 10
Once done working with the service, stop both containers using docker-compose -f docker-compose.yml down

Note: A sample Foundry file can be found here docker-compose/foundry/docker-compose.yml

Running local build

Run the service using docker-compose

Create docker containers for postgresql and microservice using docker-compose

Navigate to the docker-compose directory
Run sh ./up.sh to create both service and database container
- Note you may need to run chmod 777 *.sh to make the scripts executable.
- This only needs to be done the first time to create it
- You may use Docker Desktop to manage it afterward.
- You should see containers named davinci-pr-postgres and davinci-pr-service running.
- If your container for service is running old jar, run sh ./build-up.sh file to update image and run.

Other handy commands

sh ./build-up.sh will rebuild both service and database docker images and run if you update any file
sh ./stop.sh will stop both service and database containers
sh ./down.sh will delete both service and database containers (wipes data!!!)
sh ./db-up.sh will create and run the database
sh ./db-stop.sh will stop the database

To delete and recreate the database (and wipe all data)

sh ./down.sh to delete both service and database containers
sh ./up.sh to create both service and database containers

Run the service from the command line

To boot the service locally, use the helper script which loads the environmental variables from your .env file.

Start the service sh ./run.sh
- Note you may need to run chmod 777 run.sh to make the scripts executable.
Stop the service with ^c

Use IntelliJ IDE to debug and test the microservice

Run microservice in debug mode with breakpoints if required.

Access the service

Access the service at: http://localhost:8080/[endpoint]

Health and Swagger UI Routes

To access the Health: /actuator/health
To access the Actuator: /actuator
To access the Swagger UI: /swagger-ui/index.html
To access the Swagger JSON: /v3/api-docs
To access the Swagger YAML: /v3/api-docs.yaml

Entity Relationship Diagram (ERD)

%% Courtesy of Mermaid.js 
%% Syntax: https://mermaid.js.org/syntax/entityRelationshipDiagram.html

erDiagram
  provider {
    integer id PK
    string provider_npi
    string tin
  }

  patient {
    integer id PK
    timestamp date_of_birth
    string first_name
    string last_name
  }

  payer {
    integer id PK
    string payer_name
    string payer_identity
  }

  subscriber_patient {
    integer id PK
    integer patient_id FK
    integer payer_id FK
    string subscriber_patient_id
  }

  claim_query {
    integer id PK
    integer patient_id FK
    integer payer_id FK
    integer provider_id FK
    timestamp dos_dt
    timestamp received_dt
    string dcn_icn
    string payer_claimid
    string provider_claimid
    string provider_npi
    string provider_tin
    string subscriber_patient_id
    numeric claim_charge_amt
  }

  payment {
    integer id PK
    integer claim_id FK
    numeric amount
    timestamp payment_issue_dt
    string payment_number
    integer remittance_id FK
  }

  remittance {
    integer id PK
    integer claim_id FK
    integer remittance_advice_file_size
    timestamp remittance_advice_dt
    string remittance_advice_type
    string remittance_adviceid
  }

%% Relationships
  claim_query }o--|| payer: "payer_id"
  claim_query }o--|| patient: "patient_id"
  claim_query }o--|| provider: "provider_id"
  payment }o--|| claim_query: "claim_id"
  payment }o--|| remittance: "remittance_id"
  remittance }o--|| claim_query: "claim_id"
  subscriber_patient }o--|| payer: "payer_id"
  subscriber_patient }o--|| patient: "patient_id"

Loading

Service Endpoints

The service endpoints are documented as Artifact Summary in the IG.
The input cardinality of individual endpoint is mentioned in respective input parameters links in the following table.
Service will respond with 200 (Ok) for results found, 404 (Not Found) for no results found, 400 (Bad Request) for any other errors.
RemittanceAdviceFileSize in Remittance Parameters is in Bytes.

Service	Methods	Required Parameters	Description
`/$searchByClaim`	`POST`	TIN and ProviderClaimID (PAN)	This endpoint returns search results based on input claim parameters
`/$searchByPatient`	`POST`	TIN, PatientID, and DateOfBirth	This endpoint returns search results based on input patient parameters
`/$searchByPayment`	`POST`	TIN, PaymentNumber, and PaymentIssueDate	This endpoint returns search results based on input payment parameters
`/$downloadRemittance`	`POST`	RemittanceAdviceIdentifier	This endpoint returns zipped remittance document based on input remittance parameters

Endpoints `/$searchByClaim` and `/$searchByPatient`

Sample request for /$searchByClaim. Click to expand.

curl --location 'http://localhost:8080/$searchByClaim' \
--header 'Content-Type: application/json' \
--data '{
    "resourceType": "Parameters",
    "parameter": [
        {
            "name": "TIN",
            "valueString": "123456789"
        },
        {
            "name": "DateOfService",
            "valuePeriod": {
                "start": "2023-08-01",
                "end": "2023-08-31"
            }
        },
        {
            "name": "PatientID",
            "valueString": "M12345678901"
        },
        {
            "name": "Claim",
            "part": [
                {
                    "name": "ProviderClaimID",
                    "valueString": "12345V12345"
                },
                {
                    "name": "ProviderID",
                    "valueString": "PB654"
                },
                {
                    "name": "ClaimChargeAmount",
                    "valueString": "20.00"
                }
            ]
        },
        {
            "name": "PayerID",
            "valueString": "12345"
        },
        {
            "name": "PayerName",
            "valueString": "ABCDE"
        }
    ]
}'

Sample request for /$searchByPatient. Click to expand.

curl --location 'http://localhost:8080/$searchByPatient' \
--header 'Content-Type: application/json' \
--data '{
    "resourceType": "Parameters",
    "parameter": [
        {
            "name": "TIN",
            "valueString": "123456789"
        },
        {
            "name": "DateOfService",
            "valuePeriod": {
                "start": "2023-08-01",
                "end": "2023-08-31"
            }
        },
        {
            "name": "Patient",
            "part": [
                {
                    "name": "PatientID",
                    "valueString": "M12345678901"
                },
                {
                    "name": "DateOfBirth",
                    "valueDate": "2000-11-05"
                },
                {
                    "name": "PatientFirstName",
                    "valueString": "QWERT"
                },
                {
                    "name": "PatientLastName",
                    "valueString": "ZXCVB"
                }
            ]
        },
        {
            "name": "PayerID",
            "valueString": "12345"
        },
        {
            "name": "PayerName",
            "valueString": "ABCDE"
        }
    ]
}'

Sample response for /$searchByClaim and /$searchByPatient. Click to expand.

{
  "resourceType": "Parameters",
  "id": "SearchResult",
  "meta": {
    "profile": [
      "http://hl7.org/fhir/us/davinci-pr/StructureDefinition/searchResultParameters"
    ]
  },
  "parameter": [
    {
      "name": "TIN",
      "valueString": "123456789"
    },
    {
      "name": "Payer",
      "part": [
        {
          "name": "PayerID",
          "valueString": "12345"
        },
        {
          "name": "PayerName",
          "valueString": "ABCDE"
        }
      ]
    },
    {
      "name": "Claim",
      "part": [
        {
          "name": "ProviderClaimID",
          "valueString": "12345V12345"
        },
        {
          "name": "ClaimReceivedDate",
          "valueDate": "2023-09-02"
        },
        {
          "name": "ProviderID",
          "valueString": "PB654"
        },
        {
          "name": "PayerClaimID",
          "valueString": "4567891236"
        },
        {
          "name": "PaymentInfo",
          "part": [
            {
              "name": "PaymentDate",
              "valueDate": "2023-10-02"
            },
            {
              "name": "PaymentNumber",
              "valueString": "A123456"
            },
            {
              "name": "PaymentAmount",
              "valueMoney": {
                "value": 20.0,
                "currency": "USD"
              }
            },
            {
              "name": "Remittance",
              "part": [
                {
                  "name": "RemittanceAdviceIdentifier",
                  "valueString": "A123456BCD"
                },
                {
                  "name": "RemittanceAdviceType",
                  "valueCode": "835"
                },
                {
                  "name": "RemittanceAdviceDate",
                  "valueDate": "2023-10-02"
                },
                {
                  "name": "RemittanceAdviceFileSize",
                  "valueInteger": 1024
                }
              ]
            }
          ]
        }
      ]
    },
    {
      "name": "Claim",
      "part": [
        {
          "name": "ProviderClaimID",
          "valueString": "12345V12345"
        },
        {
          "name": "ClaimReceivedDate",
          "valueDate": "2023-10-05"
        },
        {
          "name": "ProviderID",
          "valueString": "PB654"
        },
        {
          "name": "PayerClaimID",
          "valueString": "TYU7894562"
        },
        {
          "name": "PaymentInfo",
          "part": [
            {
              "name": "PaymentDate",
              "valueDate": "2023-11-02"
            },
            {
              "name": "PaymentNumber",
              "valueString": "A123456789"
            },
            {
              "name": "PaymentAmount",
              "valueMoney": {
                "value": 50.0,
                "currency": "USD"
              }
            },
            {
              "name": "Remittance",
              "part": [
                {
                  "name": "RemittanceAdviceIdentifier",
                  "valueString": "A123456BCDEF"
                },
                {
                  "name": "RemittanceAdviceType",
                  "valueCode": "835"
                },
                {
                  "name": "RemittanceAdviceDate",
                  "valueDate": "2023-11-02"
                },
                {
                  "name": "RemittanceAdviceFileSize",
                  "valueInteger": 1536
                }
              ]
            }
          ]
        }
      ]
    },
    {
      "name": "Patient",
      "part": [
        {
          "name": "DateOfBirth",
          "valueDate": "2000-11-05"
        },
        {
          "name": "PatientID",
          "valueString": "M12345678901"
        },
        {
          "name": "PatientFirstName",
          "valueString": "QWERT"
        },
        {
          "name": "PatientLastName",
          "valueString": "ZXCVB"
        }
      ]
    }
  ]
}

Endpoint `/$searchByPayment`

Sample request. Click to expand.

curl --location 'http://localhost:8080/$searchByPayment' \
--header 'Content-Type: application/json' \
--data '{
    "resourceType": "Parameters",
    "parameter": [
        {
            "name": "TIN",
            "valueString": "123456789"
        },
        {
            "name": "DateOfService",
            "valuePeriod": {
                "start": "2023-08-01",
                "end": "2023-08-31"
            }
        },
        {
            "name": "PaymentInfo",
            "part": [
                {
                    "name": "PaymentIssueDate",
                    "valuePeriod": {
                        "start": "2023-09-01",
                        "end": "2023-10-30"
                    }
                },
                {
                    "name": "PaymentAmount",
                    "part": [
                        {
                            "name": "PaymentAmountLow",
                            "valueMoney": {
                                "value": 10.00,
                                "currency": "USD"
                            }
                        },
                        {
                            "name": "PaymentAmountHigh",
                            "valueMoney": {
                                "value": 150.00,
                                "currency": "USD"
                            }
                        }
                    ]
                },
                {
                    "name": "PaymentNumber",
                    "valueString": "A123456"
                }
            ]
        },
        {
            "name": "PayerID",
            "valueString": "12345"
        },
        {
            "name": "PayerName",
            "valueString": "ABCDE"
        }
    ]
}'

Sample response. Click to expand.

{
  "resourceType": "Parameters",
  "id": "SearchResult",
  "meta": {
    "profile": [
      "http://hl7.org/fhir/us/davinci-pr/StructureDefinition/searchByPaymentResultParameters"
    ]
  },
  "parameter": [
    {
      "name": "TIN",
      "valueString": "123456789"
    },
    {
      "name": "Payer",
      "part": [
        {
          "name": "PayerID",
          "valueString": "12345"
        },
        {
          "name": "PayerName",
          "valueString": "ABCDE"
        }
      ]
    },
    {
      "name": "PaymentInfo",
      "part": [
        {
          "name": "PaymentIssueDate",
          "valueDate": "2023-10-02"
        },
        {
          "name": "PaymentNumber",
          "valueString": "A123456"
        },
        {
          "name": "PaymentAmount",
          "valueMoney": {
            "value": 20.0,
            "currency": "USD"
          }
        }
      ]
    },
    {
      "name": "Remittance",
      "part": [
        {
          "name": "RemittanceAdviceIdentifier",
          "valueString": "A123456BCD"
        },
        {
          "name": "RemittanceAdviceType",
          "valueCode": "835"
        },
        {
          "name": "RemittanceAdviceDate",
          "valueDate": "2023-10-02"
        },
        {
          "name": "RemittanceAdviceFileSize",
          "valueInteger": 1024
        }
      ]
    }
  ]
}

Endpoint `/$downloadRemittance`

Sample request. If RemittanceAdviceType is not provided, it will default to PDF. Click to expand.

curl --location 'http://localhost:8080/$downloadRemittance' \
--data '{
    "resourceType": "Parameters",
    "parameter": [
        {
            "name": "RemittanceAdviceIdentifier",
            "valueString": "A123456BCD"
        },
        {
            "name": "RemittanceAdviceType",
            "valueCode": "PDF"
        }
    ]
}'

Sample response with default advice type as PDF. Click to expand. Note that we are adding optional `text` element with the type of the document inside compressed attachment, in this case its value is `RemittanceAdviceType:PDF`.

{
  "resourceType": "DocumentReference",
  "id": "remittance-document-486e03ec-4749-461d-b37a-5087f78256a9",
  "meta": {
    "profile": [
      "http://hl7.org/fhir/us/davinci-pr/StructureDefinition/remittanceAdviceDocument"
    ]
  },
  "text": {
    "status": "generated",
    "div": "<div xmlns=\"http://www.w3.org/1999/xhtml\">RemittanceAdviceType:PDF</div>"
  },
  "status": "current",
  "content": [
    {
      "attachment": {
        "contentType": "application/zip",
        "data": "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"
      }
    }
  ]
}

Decode and open the remittance document

Decode the base64 content of "data" in attachment object using online decoder tool like base64 Guru
Download the file and unzip to get the remittance document
PDF type document can be viewed using any PDF viewer
835 type document can be decoded using online X12 EDI viewer like Healthcare Data Insight X12 EDI Viewer

Sample response for no results found or any errors

Sample response for /$searchByClaim not found results. Click to expand.

{
  "resourceType": "OperationOutcome",
  "issue": [
    {
      "severity": "error",
      "code": "invalid",
      "diagnostics": "POST Endpoint /$searchByClaim is unable to find any records."
    }
  ]
}

Testing from the Swagger-UI

After the service is up and running, access the Swagger UI: http://localhost:8080/swagger-ui/index.html
Expand the operations section and click on "Try it out" button to test the service.
Modify request body with one of the requests mentioned in the Scenarios For Testing.
Observe the responses as expected per the scenario.
Demo of Swagger UI. Click to expand.

Scenarios For Testing

Following scenarios can be used for testing the service. These are based on the test data mentioned above. Same examples will be found in the postman collection along with their respective responses as well.

Scenario 1: Return a single result

Search by Claim: Ideally single result when requested with TIN and ProviderClaimID (PAN). Click to expand.

curl --location 'http://localhost:8080/$searchByClaim' \
--data '{
    "resourceType": "Parameters",
    "parameter": [
        {
            "name": "TIN",
            "valueString": "123456789"
        },
        {
            "name": "DateOfService",
            "valuePeriod": {
                "start": "2023-08-01",
                "end": "2023-08-31"
            }
        },
        {
            "name": "PatientID",
            "valueString": "M12345678901"
        },
        {
            "name": "Claim",
            "part": [
                {
                    "name": "ProviderClaimID",
                    "valueString": "12345V12345"
                },
                {
                    "name": "ProviderID",
                    "valueString": "PB654"
                },
                {
                    "name": "PayerClaimID",
                    "valueString": "4567891236"
                },
                {
                    "name": "ClaimChargeAmount",
                    "valueString": "20.00"
                }
            ]
        },
        {
            "name": "PayerID",
            "valueString": "12345"
        },
        {
            "name": "PayerName",
            "valueString": "ABCDE"
        }
    ]
}'

Search by Patient: Ideally single result when requested with TIN, PatientID, and DateOfBirth. Click to expand.

curl --location 'http://localhost:8080/$searchByPatient' \
--data '{
    "resourceType": "Parameters",
    "parameter": [
        {
            "name": "TIN",
            "valueString": "123456789"
        },
        {
            "name": "DateOfService",
            "valuePeriod": {
                "start": "2023-08-01",
                "end": "2023-08-31"
            }
        },
        {
            "name": "Patient",
            "part": [
                {
                    "name": "PatientID",
                    "valueString": "M12345678901"
                },
                {
                    "name": "DateOfBirth",
                    "valueDate": "2000-11-05"
                },
                {
                    "name": "PatientFirstName",
                    "valueString": "QWERT"
                },
                {
                    "name": "PatientLastName",
                    "valueString": "ZXCVB"
                }
            ]
        },
        {
            "name": "PayerID",
            "valueString": "12345"
        },
        {
            "name": "PayerName",
            "valueString": "ABCDE"
        }
    ]
}'

Search by Payment: Ideally single result when requested with TIN, PaymentNumber, and PaymentIssueDate. Click to expand.

curl --location 'http://localhost:8080/$searchByPayment' \
--data '{
    "resourceType": "Parameters",
    "parameter": [
        {
            "name": "TIN",
            "valueString": "123456789"
        },
        {
            "name": "DateOfService",
            "valuePeriod": {
                "start": "2023-08-01",
                "end": "2023-08-31"
            }
        },
        {
            "name": "PaymentInfo",
            "part": [
                {
                    "name": "PaymentIssueDate",
                    "valuePeriod": {
                        "start": "2023-09-01",
                        "end": "2023-11-30"
                    }
                },
                {
                    "name": "PaymentAmount",
                    "part": [
                        {
                            "name": "PaymentAmountLow",
                            "valueMoney": {
                                "value": 10.00,
                                "currency": "USD"
                            }
                        },
                        {
                            "name": "PaymentAmountHigh",
                            "valueMoney": {
                                "value": 150.00,
                                "currency": "USD"
                            }
                        }
                    ]
                },
                {
                    "name": "PaymentNumber",
                    "valueString": "A123456"
                }
            ]
        },
        {
            "name": "PayerID",
            "valueString": "12345"
        },
        {
            "name": "PayerName",
            "valueString": "ABCDE"
        }
    ]
}'

Download Remittance: Single result when requested with RemittanceAdviceIdentifier and RemittanceAdviceType as 835. Click to expand.

curl --location 'http://localhost:8080/$downloadRemittance' \
--data '{
    "resourceType": "Parameters",
    "parameter": [
        {
            "name": "RemittanceAdviceIdentifier",
            "valueString": "A123456BCDEF"
        },
        {
            "name": "RemittanceAdviceType",
            "valueCode": "835"
        }
    ]
}'

Download Remittance: Single result when requested with RemittanceAdviceIdentifier and RemittanceAdviceType as PDF. Click to expand.

curl --location 'http://localhost:8080/$downloadRemittance' \
--data '{
    "resourceType": "Parameters",
    "parameter": [
        {
            "name": "RemittanceAdviceIdentifier",
            "valueString": "A123456BCD"
        },
        {
            "name": "RemittanceAdviceType",
            "valueCode": "PDF"
        }
    ]
}'

Scenario 2: Return results with multiple claims/payments/remittances

Search by Claim: Result with multiple claims/payments/remittances when requested with TIN and ProviderClaimID (PAN). Note that the PayerClaimID will not be provided in this case, else it will hard match on that value. Click to expand.

curl --location 'http://localhost:8080/$searchByClaim' \
--data '{
    "resourceType": "Parameters",
    "parameter": [
        {
            "name": "TIN",
            "valueString": "123485858"
        },
        {
            "name": "DateOfService",
            "valuePeriod": {
                "start": "2023-08-01",
                "end": "2023-08-31"
            }
        },
        {
            "name": "PatientID",
            "valueString": "M12345513215"
        },
        {
            "name": "Claim",
            "part": [
                {
                    "name": "ProviderClaimID",
                    "valueString": "12345V54321"
                },
                {
                    "name": "ProviderID",
                    "valueString": "PB655"
                },
                {
                    "name": "ClaimChargeAmount",
                    "valueString": "30.00"
                }
            ]
        },
        {
            "name": "PayerID",
            "valueString": "52415"
        },
        {
            "name": "PayerName",
            "valueString": "PayerAB"
        }
    ]
}'

Search by Patient: Result with multiple claims/payments/remittances when requested with TIN, PatientID, and DateOfBirth. Click to expand.

curl --location 'http://localhost:8080/$searchByPatient' \
--data '{
    "resourceType": "Parameters",
    "parameter": [
        {
            "name": "TIN",
            "valueString": "123485858"
        },
        {
            "name": "DateOfService",
            "valuePeriod": {
                "start": "2023-08-01",
                "end": "2023-08-31"
            }
        },
        {
            "name": "Patient",
            "part": [
                {
                    "name": "PatientID",
                    "valueString": "M12345513215"
                },
                {
                    "name": "DateOfBirth",
                    "valueDate": "2000-11-05"
                },
                {
                    "name": "PatientFirstName",
                    "valueString": "Jane"
                },
                {
                    "name": "PatientLastName",
                    "valueString": "Doe"
                }
            ]
        },
        {
            "name": "PayerID",
            "valueString": "52415"
        },
        {
            "name": "PayerName",
            "valueString": "PayerAB"
        }
    ]
}'

Search by Payment: Result with multiple claims/payments/remittances when requested with TIN, PaymentNumber, and PaymentIssueDate. This also covers partial payment number in request parameter. Click to expand.

curl --location 'http://localhost:8080/$searchByPayment' \
--data '{
    "resourceType": "Parameters",
    "parameter": [
        {
            "name": "TIN",
            "valueString": "123485858"
        },
        {
            "name": "DateOfService",
            "valuePeriod": {
                "start": "2023-08-01",
                "end": "2023-08-31"
            }
        },
        {
            "name": "PaymentInfo",
            "part": [
                {
                    "name": "PaymentIssueDate",
                    "valuePeriod": {
                        "start": "2023-09-01",
                        "end": "2023-11-30"
                    }
                },
                {
                    "name": "PaymentAmount",
                    "part": [
                        {
                            "name": "PaymentAmountLow",
                            "valueMoney": {
                                "value": 10.00,
                                "currency": "USD"
                            }
                        },
                        {
                            "name": "PaymentAmountHigh",
                            "valueMoney": {
                                "value": 150.00,
                                "currency": "USD"
                            }
                        }
                    ]
                },
                {
                    "name": "PaymentNumber",
                    "valueString": "A123"
                }
            ]
        },
        {
            "name": "PayerID",
            "valueString": "52415"
        },
        {
            "name": "PayerName",
            "valueString": "PayerAB"
        }
    ]
}'

Scenario 3: No match found

Search by Claim: No match found when requested with random TIN. Click to expand.

curl --location 'http://localhost:8080/$searchByClaim' \
--data '{
    "resourceType": "Parameters",
    "parameter": [
        {
            "name": "TIN",
            "valueString": "000909090"
        },
        {
            "name": "Claim",
            "part": [
                {
                    "name": "ProviderClaimID",
                    "valueString": "12345V12345"
                }
            ]
        }
    ]
}'

Search by Patient: No match found when requested with random TIN. Click to expand.

curl --location 'http://localhost:8080/$searchByPatient' \
--data '{
    "resourceType": "Parameters",
    "parameter": [
        {
            "name": "TIN",
            "valueString": "000909090"
        },
        {
            "name": "Patient",
            "part": [
                {
                    "name": "PatientID",
                    "valueString": "M12345678901"
                },
                {
                    "name": "DateOfBirth",
                    "valueDate": "2000-11-05"
                }
            ]
        }
    ]
}'

Search by Payment: No match found when requested with random TIN. Click to expand.

curl --location 'http://localhost:8080/$searchByPayment' \
--data '{
    "resourceType": "Parameters",
    "parameter": [
        {
            "name": "TIN",
            "valueString": "000909090"
        },
        {
            "name": "PaymentInfo",
            "part": [
                {
                    "name": "PaymentIssueDate",
                    "valuePeriod": {
                        "start": "2023-09-01",
                        "end": "2023-10-30"
                    }
                },
                {
                    "name": "PaymentNumber",
                    "valueString": "A123"
                }
            ]
        }
    ]
}'

Download Remittance: No match found when requested with random remittance advice ID. Click to expand.

curl --location 'http://localhost:8080/$downloadRemittance' \
--data '{
    "resourceType": "Parameters",
    "parameter": [
        {
            "name": "RemittanceAdviceIdentifier",
            "valueString": "ABCD123546"
        },
        {
            "name": "RemittanceAdviceType",
            "valueCode": "PDF"
        }
    ]
}'

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

README.md

README.md

Postable Remittance

Table of Contents

Local Setup

Requirements

Create environment file

Sample data

Postman collection

Getting Started

Running with Foundry docker-compose image

Running local build

Run the service using docker-compose

Other handy commands

To delete and recreate the database (and wipe all data)

Run the service from the command line

Use IntelliJ IDE to debug and test the microservice

Access the service

Health and Swagger UI Routes

Entity Relationship Diagram (ERD)

Service Endpoints

Endpoints `/$searchByClaim` and `/$searchByPatient`

Endpoint `/$searchByPayment`

Endpoint `/$downloadRemittance`

Decode and open the remittance document

Sample response for no results found or any errors

Testing from the Swagger-UI

Scenarios For Testing

Scenario 1: Return a single result

Scenario 2: Return results with multiple claims/payments/remittances

Scenario 3: No match found

Files

README.md

Latest commit

History

README.md

File metadata and controls

Postable Remittance

Table of Contents

Local Setup

Requirements

Create environment file

Sample data

Postman collection

Getting Started

Running with Foundry docker-compose image

Running local build

Run the service using docker-compose

Other handy commands

To delete and recreate the database (and wipe all data)

Run the service from the command line

Use IntelliJ IDE to debug and test the microservice

Access the service

Health and Swagger UI Routes

Entity Relationship Diagram (ERD)

Service Endpoints

Endpoints /$searchByClaim and /$searchByPatient

Endpoint /$searchByPayment

Endpoint /$downloadRemittance

Decode and open the remittance document

Sample response for no results found or any errors

Testing from the Swagger-UI

Scenarios For Testing

Scenario 1: Return a single result

Scenario 2: Return results with multiple claims/payments/remittances

Scenario 3: No match found

Endpoints `/$searchByClaim` and `/$searchByPatient`

Endpoint `/$searchByPayment`

Endpoint `/$downloadRemittance`