# Payer to Payer (P2P) API
* version 1.1

## Introduction
This guide details how to configure and use Smile CDR's P2P API. The use of this API provides a convenient solution to data transfer of member data between Payers. Now, Payers whose Member portals lack P2P functionality, can utilize this API to gain Payer to Payer exchange feautures.

## Getting Started
- This module currently only supports FHIR R4.

## Configuration Categories

- P2P Module Configuration
- P2P Module has its own API operations for performing this operations it needs to be on a new port.
- Most of the configuration is like a FHIR endpoint except on this module no FHIR operations can be performed.

#### Email Notification
- This configuration only works when you have Subscription configured and enable [Rest Hook](https://smilecdr.com/docs/configuration_categories/fhir_subscription_persistence.html#subscription.rest_hook.enabled) on the persistence module.
- P2P Module seeds a default Subscription resource on startup to capture events on Task resource.
- This configuration is used to send out emails from a single email address to multiple recipients based on Task resource.
- Need to provide sample Tsak resource
#### Provenance
- [Regulation](https://build.fhir.org/ig/HL7/davinci-epdx/PDexProvenance.html) Please confirm with Casey Trauer before publishing this regulation link
- Smile CDR acting as Target Payer
- During data ingestion, a Provenance resource is generated for each page in order to keep track of resources.
- If [Versioned References](https://smilecdr.com/docs/configuration_categories/fhir_storage_versioned_reference.html#property-allow-versioned-references-at-all-paths) on the persistence module is turned off then the generated Provenance will not include versioned references for the resources.
- Smile CDR acting as Source Payer
- Please refer documentation [here](https://smilecdr.com/docs/validation_and_conformance/automatic_provenance_injection.html)

#### MDM Configuration
- As a target, if [MDM](https://smilecdr.com/docs/mdm/mdm.html) is enabled and matches on [Patient Identifier](https://build.fhir.org/ig/HL7/carin-bb/ValueSet-C4BBPatientIdentifierType.html), then this configuration allows to add the Patient Identifier during ingestion process so, the Patient resource received from source can be matched to the Patient resource in target based on Patient Identifier.
- Leave it as blank if MDM is not enabled.

- OIDC Server Configuration
- As the P2P Module is making API request to the source system it needs authorization/authentication information. This information is kept in OIDC server definition for P2P Module.
- To create a new OIDC server definition used by P2P module, navigate to Config > OpenID Connect Servers and create a new server definition for P2P module.
- This OIDC server definition will be used by the front-end application for initiating OAuth2 OIDC flow and it'll be used by P2P module to associate P2P exchange batch processes.
- The configurations items for OIDC servers are listed below :
- OAuth2 Properties
- Server Name -> A name to give this server (this property is just for convenience, it does not need to match any value elsewhere).
- Issuer -> The URL associated with this issuer. This URL will be provided within the iss claim in Access Tokens generated by this server. Note that the issuer URL serves as the identifier for a given server definition. It must be unique. Note that any trailing slash will be ignored, and this definition will still be matched if a trailing slash is present in tokens being validated.
- Token Introspection
- Client ID -> If Smile CDR needs to perform token introspection in order to learn more about an access token, this client ID will be used.
- Client Secret -> If Smile CDR needs to perform token introspection in order to learn more about an access token, this client secret will be used.
- JSON Web Keys
- Key (Text) -> For flows that require Smile CDR to verify a JWK that was signed by the remote server (i.e. the Cross-Organization Data Access Profile), this field may be populated with a JWK. Typically this JWK will contain only the public key.
- Key (File) -> For flows that require Smile CDR to verify a JWK that was signed by the remote server (i.e. the Cross-Organization Data Access Profile), this field may be populated with a JWK. Typically this JWK will contain only the public key.
- P2P Related Fields
- Auth Well-Known Configuration URL -> The URL defined within the OpenID Connect specification, which provides configuration information about the Identity Provider (IDP).
- Request Scopes -> When requesting authorization against the provider, this setting controls which OAuth2 scopes will be requested. Note that the scopes requested by the security module from the provider are independent from the scopes requested by the SMART application that is authorizing against Smile CDR. In a typical flow, a SMART on FHIR application will request SMART scopes from Smile CDR, and Smile CDR will in turn request a different set of appropriate scopes from the provider.
- FHIR Endpoint URL -> The URL describing the technical details of a location that can be connected to for the delivery/retrieval of information. This URL can be a locally hosted service, regional service, or national service.
- Token URL -> The service URL used by the SMART Outbound Security module for code exchange when requesting a token from the provider.
- Custom Token Parameters -> Customized token parameters set for this OIDC Server.
- Response Type -> Possible values include: code, token, id_token, id_token token, code id_token, code token, code id_token token, none.
- Organization ID -> The identification code used to specify an organization or business. (i.e. Payer ID/A five digit standardized industry identify used by payers)
- Notes -> Include details such as Registration URL, etc.

## API Solution Usage
- Overview (Licensing, PMP, etc)
- For clients not using Smile CDR's member portal, we have a complete API solution exposed by P2P module.
- All the api's available to perform REST operations can be found on P2P module's swagger endpoint which can be reached by hitting the base endpoint url for P2P Module.
- Add payer request
- To track when a member requests for a new payer for P2P exchance we use Task resource.
- Create Task resource, which looks like below to track requests initiated by members for adding a new payer.
- POST /baseFHIREndpointURL/Task
- Request body :
`
{
"resourceType": "Task",
"identifier": [
{
"system": "http://payer-to-payer-exchange/CodeSystem/p2p-internal-codes",
"value": "<Patient_ID>-<Organization_ID>-<Task_Creation_Date_Time>"
}
],
"status": "requested",
"intent": "original-order",
"priority": "routine",
"code": {
"coding": [
{
"system": "http://payer-to-payer-exchange/CodeSystem/p2p-internal-codes",
"code": "p2p-request-add-provider-id",
"display": "p2p-request-add-provider-id"
}
],
"text": "Add Payer"
},
"authoredOn": "<Task_Creation_Date_Time>",
"lastModified": "<Task_Last_Updated_Date_Time>",
"requester": {
"reference": "Patient/<Patient_ID>",
"type": "Patient"
},
"owner": {
"reference": "Organization/<Organization_ID>"
},
"input": [
{
"type": {
"coding": [
{
"system": "http://payer-to-payer-exchange/CodeSystem/p2p-internal-codes",
"code": "requester-first-name",
"display": "display"
}
],
"text": "<member_first_name>"
},
"valueString": "<member_first_name>"
},
{
"type": {
"coding": [
{
"system": "http://payer-to-payer-exchange/CodeSystem/p2p-internal-codes",
"code": "requester-last-name",
"display": "display"
}
],
"text": "<requester_last_name>"
},
"valueString": "<requester_last_name>"
},
{
"type": {
"coding": [
{
"system": "http://payer-to-payer-exchange/CodeSystem/p2p-internal-codes",
"code": "new-payer-name",
"display": "display"
}
],
"text": "<new_payer_name>"
},
"valueString": "<new_payer_name>"
},
{
"type": {
"coding": [
{
"system": "http://payer-to-payer-exchange/CodeSystem/p2p-internal-codes",
"code": "requester-email",
"display": "display"
}
],
"text": "<member_email_address>"
},
"valueString": "<member_email_address>"
},
{
"type": {
"coding": [
{
"system": "http://payer-to-payer-exchange/CodeSystem/p2p-internal-codes",
"code": "requester-phone",
"display": "1111111111"
}
],
"text": "1111111111"
},
"valueString": "1111111111"
}
]
}
`
- This Task resource is tied up with a Subscription resource generated by P2P module which can be used to send emails to admins and the members.

- P2P Exchange API's
- Get a list of OIDC servers associated with P2P Module. This can be used in your application to show a list of available source payers to members.
- GET /api/oidc_servers
- Sample response :
`
{
"servers": [
{
"pid": 1,
"name": "P2P Source Payer A"
},
{
"pid": 2,
"name": "P2P Source Payer B"
}
]
} `
- Get a single OIDC server definition. The returned configuration can be used in your application to initiate auth flow against source payer system.
- GET /api/oidc_servers/{server_id}
- Sample response :
`
{
"pid": 1,
"name": "P2P Source Payer A",
"issuer": "https://sourcepayerA.com/issuer",
"clientId": "p2pexchangeclientId",
"scopes": "openid profile offline_access",
"customTokenParams": "memberId",
"authWellKnown": "https://sourcepayerA.com/.well-known/openid-configuration",
"tokenEndpoint": "https://sourcepayerA.com/token-endpoint",
"fhirEndpoint": "https://sourcepayerA.com/fhir-endpoint",
"responseType": "code",
"organizationId": "ABCD"
}
`
- Initiate a batch job for P2P Exchange. This POST request will initiate P2P Exchange from source system and returns a batch_job_id.
- POST /api/oidc_servers/{server_id}/batch_job
- Request Body :
`
{
"sourcePayer": {
"oidcToken": "string",
"oidcRefreshToken": "string",
"fhirBundleRequest": "string",
"patientId": "string"
},
"targetPayer": {
"patientId": "string",
"organizationId": "string"
}
}
`
- Sample response :
`
{
"batchJobId": 0,
"batchStatus": "COMPLETED",
"startTime": "2022-05-09T20:36:18.111Z",
"createTime": "2022-05-09T20:36:18.111Z",
"endTime": "2022-05-09T20:36:18.111Z",
"lastUpdated": "2022-05-09T20:36:18.111Z",
"jobConfigurationName": "string",
"taskId": "string"
}
`
- Get batch job status. This can be used to get status of Batch process for P2P exchange.
- GET /api/oidc_servers/{server_id}/batch_job/{batch_job_id}
- Sample response :
`
{
"batchJobId": 0,
"batchStatus": "COMPLETED",
"startTime": "2022-05-09T20:36:18.106Z",
"createTime": "2022-05-09T20:36:18.106Z",
"endTime": "2022-05-09T20:36:18.106Z",
"lastUpdated": "2022-05-09T20:36:18.106Z",
"jobConfigurationName": "string",
"taskId": "string"
}
`