Documentation
Start typing to search…

Start building your integration

Introduction

To start building your API integration, you should:

  1. set up your development environment with the necessary tools or libraries.
  2. acquire an API key to gain access to our REST APIs.
  3. start testing requests.

This guide illustrates an example use case of issuing payments using each of the following methods:

  • Issuing a single payment
  • Creating and managing a batch of payments

Prerequisites

Access

Ensure that your Organization is set up and you acquired an API key. Refer to Set up Organization and Acquire an API Key for details.

Environment setup

Make sure you have the necessary development tools installed:

  • API testing tools: Postman or curl for manual API request testing
  • Coding environment: IDEs such as Visual Studio Code, PyCharm or any suitable development tools
  • SDKs or libraries for the language you are using (e.g. requests for Python, axios for JavaScript)

Select the appropriate tooling:

This guide will focus on using the REST APIs, providing links to other documentation throughout.

Authentication

Include your API key in the API-Key header when making requests to our REST APIs or when configuring your Client SDK.

Payments processing

Our API suite offers two methods for initiating and processing payments. You can create and execute a single payment batch or leverage a set of endpoints to build a batch, add multiple payments and initiate the batch.

In certain cases, payments may be subject to a hold/release process, requiring an additional step to release the batch before it can be processed.

Create and execute a single payment batch


1. Create a payment

Creates a paymentId and associates it to a batchId

Endpoint: POST /api/v1/payments

Request body: Information about the payment to create
{
"clientRequestId": "D8S6FSD686S68DS6",
"accountShortCode": "ACCT1",
"subAccountShortCode": "SUBACCT1",
"payment": {
  "paymentDetails": {
    "issuerPaymentId": "48dc20ff1d97977e65209b927d28dc6b",
    "issuerReferenceId": "EVRYHEALTH001",
    "paymentDate": "2025-01-15",
    "adjudicationCutoffDate": "2025-01-15",
    "adjudicationVersion": "2",
    "amount": 1754.98,
    "remitMethod": "DATA",
    "jurisdictionalBody": "MN",
    "numberOfAttachedPDFs": 2
  },
  "payeeDetails": {
    "name": "John Doe",
    "address": {
      "address1": "123 West St.",
      "address2": "Apt 987",
      "city": "Dallas",
      "state": "TX",
      "postalCode": "75227",
      "country": "USA"
    },
    "taxId": "786532990",
    "npiId": "1234567890",
    "receiverId": "string"
  },
  "shippingDetails": {
    "name": "John Doe",
    "address": {
      "address1": "123 West St.",
      "address2": "Apt 987",
      "city": "Dallas",
      "state": "TX",
      "postalCode": "75227",
      "country": "USA"
    }
  },
  "totalNumberClaims": 1,
  "claimLevelInformation": [
    {
      "providerSummaryInformation": {
        "referenceIdentification": "123456",
        "facilityCode": "11",
        "date": "2025-01-15",
        "quantity": 110,
        "monetaryAmount": 130957.66
      },
      "supplementalProviderSummaryInformation": {
        "totalDrgAmount": 123456.78,
        "totalFederalSpecificAmount": 23456.78,
        "totalHospitalSpecificAmount": 34567.89,
        "totalDisproportionateShareAmount": 45678.9,
        "totalCapitalAmount": 56789.01,
        "totalImeAmount": 67890.12,
        "totalOutlierDayCount": 5,
        "totalDayOutlierAmount": 78901.23,
        "totalCostOutlierAmount": 78901.23,
        "averageDrgLengthOfStay": 3,
        "totalDischargeCount": 4,
        "totalCostReportDayCount": 4,
        "totalCoveredDayCount": 4,
        "totalNonCoveredDayCount": 4,
        "totalMspPassThroughAmount": 78901.23,
        "averageDrgWeight": 44.6,
        "totalPpsCapitalFspDrgAmount": 44.6,
        "totalPpsCapitalHspDrgAmount": 44.6,
        "totalPpsDshDrgAmount": 44.6
      },
      "claimLoop": [
        {
          "claimPaymentInformation": {
            "patientControlNumber": "7722337",
            "statusCode": 1,
            "totalChargeAmount": 211366.97,
            "paymentAmount": 138018.4,
            "patientResponsibilityAmount": 9000.28,
            "filingIndicatorCode": "12",
            "payerClaimControlNumber": "119932404007801",
            "facilityTypeCode": "02",
            "claimFrequencyCode": "3",
            "diagnosisRelatedGroupDrgCode": "123",
            "diagnosisRelatedGroupDrgWeight": 1.234,
            "dischargeFraction": 0.25
          },
          "involvedEntitiesInfo": [
            {
              "entityIdentifierCode": "QC",
              "entityTypeQualifier": "1",
              "lastName": "Shephard",
              "firstName": "Sam",
              "middleNameOrInitial": "O",
              "nameSuffix": "SENIOR",
              "identificationCodeQualifier": "34",
              "entityIdentifier": "string"
            }
          ],
          "inPatientAdjudicationInformation": {
            "coveredDaysOrVisitsCount": 5,
            "ppsOperatingOutlierAmount": 143745.97,
            "lifetimePsychiatricDaysCount": 2,
            "claimDrgAmount": 84765.37,
            "claimPaymentRemarkCode": "M1234",
            "claimDisproportionateShareAmount": 2345.67,
            "claimMspPassThroughAmount": 345.67,
            "claimPpsCapitalAmount": 4567.89,
            "ppsCapitalFspDrgAmount": 567.89,
            "ppsCapitalHspDrgAmount": 678.9,
            "ppsCapitalDshDrgAmount": 789.01,
            "oldCapitalAmount": 890.12,
            "ppsCapitalImeAmount": 901.23,
            "ppsOperatingHospitalSpecificDrgAmount": 1234.56,
            "costReportDaysCount": 10,
            "ppsOperatingFederalSpecificDrgAmount": 1234.56
          },
          "outPatientAdjudicationInformation": {
            "reimbursementRate": 0.25,
            "hcpcsPayableAmount": 1234.56,
            "claimPaymentRemarkCode1": "M1234",
            "claimPaymentRemarkCode2": "M5678",
            "claimPaymentRemarkCode3": "M91011",
            "claimPaymentRemarkCode4": "M1213",
            "claimPaymentRemarkCode5": "M1415",
            "esrdPaymentAmount": 678.9
          },
          "relatedIdentification": [
            {
              "referenceIdentificationQualifier": "1L",
              "referenceIdentification": "string"
            }
          ],
          "relevantDates": [
            {
              "qualifier": "036",
              "date": "2025-01-15"
            }
          ],
          "claimContactInformation": {
            "name": "John",
            "primaryPhone": {
              "type": "Phone",
              "number": "8005551212",
              "extension": "579"
            },
            "secondaryPhone": {
              "type": "Phone",
              "number": "8005551212",
              "extension": "579"
            },
            "email": "[email protected]"
          },
          "claimSupplementalInformation": {
            "amountQualifierCode": "T",
            "claimSupplementalInformationAmount": 49.36
          },
          "loop2110": [
            {
              "servicePaymentInformation": {
                "compositeMedicalProcedureId1": {
                  "productServiceIdQualifier": "AD",
                  "procedureCode": "99214",
                  "procedureModifier1": "st",
                  "procedureModifier2": "st",
                  "procedureModifier3": "st",
                  "procedureModifier4": "st",
                  "procedureCodeDesc": "string"
                },
                "lineItemChargeAmount": 100,
                "lineItemProviderPaymentAmount": 80,
                "nationalUniformBillingCommitteeRevenueCode": "99214",
                "quantity1": 2,
                "compositeMedicalProcedureId2": {
                  "productServiceIdQualifier": "AD",
                  "procedureCode": "99214",
                  "procedureModifier1": "st",
                  "procedureModifier2": "st",
                  "procedureModifier3": "st",
                  "procedureModifier4": "st",
                  "procedureCodeDesc": "string"
                },
                "quantity2": 2
              },
              "serviceDate": {
                "dateTimeQualifier": "150",
                "date": "2025-01-15"
              },
              "serviceAdjustment": [
                {
                  "claimAdjustmentGroupCode": "CO",
                  "adjustments": [
                    {
                      "adjustmentReasonCode": "45",
                      "monetaryAmount": 41.08,
                      "adjustmentQuantity": 0
                    }
                  ]
                }
              ],
              "relatedIdentificationRefSvc": [
                {
                  "referenceIdentificationQualifier": "RB",
                  "referenceIdentifier": "100"
                }
              ],
              "serviceSupplementalAmountInformationAmt": {
                "amountQualifierCode": "B6",
                "claimSupplementalInformationAmount": 425
              },
              "healthCareRemarkCode": {
                "codeListQualifierCode": "HE",
                "remarkCode": "12345"
              }
            }
          ]
        }
      ]
    }
  ],
  "providerLevelAdjustment": [
    {
      "providerIdentifier": "1134673957",
      "fiscalPeriodDate": "2025-01-15",
      "adjustments": [
        {
          "reasonCode": "FB",
          "identifier": "2004990161",
          "amount": 224.83
        }
      ]
    }
  ]
}
}

Response: Returns a paymentId and a batchId.

{
  "batchId": "48dc20ff1d97977e65209b927d28dc6b",
  "paymentId": "48dc5287796f5fbd2e6218ba334c7e88"
}
📘

If a batch with the given request ID already exists, or a payment with the same reference ID already exists, a 409 is returned.

📘

Retain the paymentId to be used as a parameter for subsequent requests.

Click and TRY IT!

2. Release a payment

Releases the held payment created using POST /payments request.

Endpoint:POST api/v1/payments/{paymentId}/release

  • Where {paymentId} represents the ID of the payment created in step 1.
Request body: The data related to the release of the payment
{
"batchId": "D8S6FSD686S68DS6",
"releasedBy": "[email protected]"
}

Response: 204 (if the payment batch is released)

📘

If the payment batch cannot be found, a 404 is returned.

Click and TRY IT!

Create and execute a payments batch

The following set of endpoints are used when many payments will be associated with a payment batch.


1. Create a batch

Creates a batchId. This endpoint should be used when many payments will be associated with the payment batch.

EndpointPOST api/v1/payments/batch

Request body: Contains the payment batch data
{
"clientRequestId": "D8S6FSD686S68DS6",
"accountShortCode": "ACCT1",
"subAccountShortCode": "SUBACCT1",
"totalAmount": 12342,
"numberOfPayments": 2500
}

Response: When the batch is successfully created, a batchId is returned.

{
  "batchId": "48dc20ff1d97977e65209b927d28dc6b"
}
📘

Retain the batchId to be used as a parameter for subsequent requests.

Click and TRY IT!

2. Add payments

Associates payments with a created batchId.

EndpointPOST api/v1/payments/batch/{batchId}/add

  • Where {batchId} represents the ID of the payment batch to associate the payments to.
Request body: The payments to associate with the payment batch
{
"payments": [
  {
    "paymentDetails": {
      "issuerPaymentId": "48dc20ff1d97977e65209b927d28dc6b",
      "issuerReferenceId": "EVRYHEALTH001",
      "paymentDate": "2025-01-16",
      "adjudicationCutoffDate": "2025-01-16",
      "adjudicationVersion": "2",
      "amount": 1754.98,
      "remitMethod": "DATA",
      "jurisdictionalBody": "MN",
      "numberOfAttachedPDFs": 2
    },
    "payeeDetails": {
      "name": "John Doe",
      "address": {
        "address1": "123 West St.",
        "address2": "Apt 987",
        "city": "Dallas",
        "state": "TX",
        "postalCode": "75227",
        "country": "USA"
      },
      "taxId": "786532990",
      "npiId": "1234567890",
      "receiverId": "string"
    },
    "shippingDetails": {
      "name": "John Doe",
      "address": {
        "address1": "123 West St.",
        "address2": "Apt 987",
        "city": "Dallas",
        "state": "TX",
        "postalCode": "75227",
        "country": "USA"
      }
    },
    "totalNumberClaims": 1,
    "claimLevelInformation": [
      {
        "providerSummaryInformation": {
          "referenceIdentification": "123456",
          "facilityCode": "11",
          "date": "2025-01-16",
          "quantity": 110,
          "monetaryAmount": 130957.66
        },
        "supplementalProviderSummaryInformation": {
          "totalDrgAmount": 123456.78,
          "totalFederalSpecificAmount": 23456.78,
          "totalHospitalSpecificAmount": 34567.89,
          "totalDisproportionateShareAmount": 45678.9,
          "totalCapitalAmount": 56789.01,
          "totalImeAmount": 67890.12,
          "totalOutlierDayCount": 5,
          "totalDayOutlierAmount": 78901.23,
          "totalCostOutlierAmount": 78901.23,
          "averageDrgLengthOfStay": 3,
          "totalDischargeCount": 4,
          "totalCostReportDayCount": 4,
          "totalCoveredDayCount": 4,
          "totalNonCoveredDayCount": 4,
          "totalMspPassThroughAmount": 78901.23,
          "averageDrgWeight": 44.6,
          "totalPpsCapitalFspDrgAmount": 44.6,
          "totalPpsCapitalHspDrgAmount": 44.6,
          "totalPpsDshDrgAmount": 44.6
        },
        "claimLoop": [
          {
            "claimPaymentInformation": {
              "patientControlNumber": "7722337",
              "statusCode": 1,
              "totalChargeAmount": 211366.97,
              "paymentAmount": 138018.4,
              "patientResponsibilityAmount": 9000.28,
              "filingIndicatorCode": "12",
              "payerClaimControlNumber": "119932404007801",
              "facilityTypeCode": "02",
              "claimFrequencyCode": "3",
              "diagnosisRelatedGroupDrgCode": "123",
              "diagnosisRelatedGroupDrgWeight": 1.234,
              "dischargeFraction": 0.25
            },
            "involvedEntitiesInfo": [
              {
                "entityIdentifierCode": "QC",
                "entityTypeQualifier": "1",
                "lastName": "Shephard",
                "firstName": "Sam",
                "middleNameOrInitial": "O",
                "nameSuffix": "SENIOR",
                "identificationCodeQualifier": "34",
                "entityIdentifier": "string"
              }
            ],
            "inPatientAdjudicationInformation": {
              "coveredDaysOrVisitsCount": 5,
              "ppsOperatingOutlierAmount": 143745.97,
              "lifetimePsychiatricDaysCount": 2,
              "claimDrgAmount": 84765.37,
              "claimPaymentRemarkCode": "M1234",
              "claimDisproportionateShareAmount": 2345.67,
              "claimMspPassThroughAmount": 345.67,
              "claimPpsCapitalAmount": 4567.89,
              "ppsCapitalFspDrgAmount": 567.89,
              "ppsCapitalHspDrgAmount": 678.9,
              "ppsCapitalDshDrgAmount": 789.01,
              "oldCapitalAmount": 890.12,
              "ppsCapitalImeAmount": 901.23,
              "ppsOperatingHospitalSpecificDrgAmount": 1234.56,
              "costReportDaysCount": 10,
              "ppsOperatingFederalSpecificDrgAmount": 1234.56
            },
            "outPatientAdjudicationInformation": {
              "reimbursementRate": 0.25,
              "hcpcsPayableAmount": 1234.56,
              "claimPaymentRemarkCode1": "M1234",
              "claimPaymentRemarkCode2": "M5678",
              "claimPaymentRemarkCode3": "M91011",
              "claimPaymentRemarkCode4": "M1213",
              "claimPaymentRemarkCode5": "M1415",
              "esrdPaymentAmount": 678.9
            },
            "relatedIdentification": [
              {
                "referenceIdentificationQualifier": "1L",
                "referenceIdentification": "string"
              }
            ],
            "relevantDates": [
              {
                "qualifier": "036",
                "date": "2025-01-16"
              }
            ],
            "claimContactInformation": {
              "name": "John",
              "primaryPhone": {
                "type": "Phone",
                "number": "8005551212",
                "extension": "579"
              },
              "secondaryPhone": {
                "type": "Phone",
                "number": "8005551212",
                "extension": "579"
              },
              "email": "[email protected]"
            },
            "claimSupplementalInformation": {
              "amountQualifierCode": "T",
              "claimSupplementalInformationAmount": 49.36
            },
            "loop2110": [
              {
                "servicePaymentInformation": {
                  "compositeMedicalProcedureId1": {
                    "productServiceIdQualifier": "AD",
                    "procedureCode": "99214",
                    "procedureModifier1": "st",
                    "procedureModifier2": "st",
                    "procedureModifier3": "st",
                    "procedureModifier4": "st",
                    "procedureCodeDesc": "string"
                  },
                  "lineItemChargeAmount": 100,
                  "lineItemProviderPaymentAmount": 80,
                  "nationalUniformBillingCommitteeRevenueCode": "99214",
                  "quantity1": 2,
                  "compositeMedicalProcedureId2": {
                    "productServiceIdQualifier": "AD",
                    "procedureCode": "99214",
                    "procedureModifier1": "st",
                    "procedureModifier2": "st",
                    "procedureModifier3": "st",
                    "procedureModifier4": "st",
                    "procedureCodeDesc": "string"
                  },
                  "quantity2": 2
                },
                "serviceDate": {
                  "dateTimeQualifier": "150",
                  "date": "2025-01-16"
                },
                "serviceAdjustment": [
                  {
                    "claimAdjustmentGroupCode": "CO",
                    "adjustments": [
                      {
                        "adjustmentReasonCode": "45",
                        "monetaryAmount": 41.08,
                        "adjustmentQuantity": 0
                      }
                    ]
                  }
                ],
                "relatedIdentificationRefSvc": [
                  {
                    "referenceIdentificationQualifier": "RB",
                    "referenceIdentifier": "100"
                  }
                ],
                "serviceSupplementalAmountInformationAmt": {
                  "amountQualifierCode": "B6",
                  "claimSupplementalInformationAmount": 425
                },
                "healthCareRemarkCode": {
                  "codeListQualifierCode": "HE",
                  "remarkCode": "12345"
                }
              }
            ]
          }
        ]
      }
    ],
    "providerLevelAdjustment": [
      {
        "providerIdentifier": "1134673957",
        "fiscalPeriodDate": "2025-01-16",
        "adjustments": [
          {
            "reasonCode": "FB",
            "identifier": "2004990161",
            "amount": 224.83
          }
        ]
      }
    ]
  }
]
}

Response: When the payments are successfully associated with the payment batch apaymentId is returned

{
    "paymentId": "48dc20ff1d97977e65209b927d28dc6b"
  }
Click and TRY IT!

3. Initiate a payments batch

Once a payment batch is created and payments are associated to the payment batch, this endpoint will be called to initiate the payments batch.

Endpoint:POST api/v1/payments//batch/{batchId}/release

  • Where {batchId} represents the ID of the payments batch to be initiated.

Response: 204 (if the payment batch is successfully initiated)

Click and TRY IT!

4. Release a payments batch

Releases the held payments batch for processing.

Endpoint:POST api/v1/payments//batch/{batchId}/release

  • Where {batchId} represents the ID of the payments batch to be released.
Request body: The data related to the release of the payment batch
{
"batchId": "D8S6FSD686S68DS6",
"releasedBy": "[email protected]"
}

Response: 204 (if the payment batch is successfully released)

📘

If the payment batch cannot be found, a 404 is returned.

Click and TRY IT!

Updated 9 months ago