Overview

Payment batch events identify what stage the batch is in. They have an underscore separating the words (e.g., batch_created).

For more info on what a payment batch is, check the Batch payments management page.

Event envelope

Each event request body follows a standardized envelope format for all events. This format ensures that all events follow a standardized structure, making it easier to process and understand them.

Field	Description	Example
id	The identifier of the object the event is related to (e.g., batch id, payment id etc.)	45b93ecf-c718-4255-8485-10228f ca6713
source	The source of the event	https://example.com
specVersion	The version of the CloudEvent spec	1.0
type	The type of event	batch_created
dataContentType	Content type of the data	application/json
data	The payload of the event	dynamic JSON object
time	The date and time the event was created	2024-12-02T15:24:40. 6048459Z
causationId	The identifier of the event	134433a2-387d-48b8-9d7e-ddc7af8c705f

{
    "id": "45b93ecf-c718-4255-8485-10228f ca6713",
    "source": "https://example.com",
    "specVersion": "1.0",
    "type": "batch_created",
    "dataContentType": "application/json",
    "data": {
        "org": "ABC",
        "account": "ABC",
        "subAccount": "ABC001",
        "totalAmount": 100,
        "numberOfPayments": 1,
        "status": "Created",
        "fundingMethod": "PreFundedSameDay",
        "type": "batch_created"
    },
    "time": "2024-12-02T15:24:40. 6048459Z",
    "causationId": "134433a2-387d-48b8-9d7e-ddc7af8c705f"
}

📘
Note
Please note that the Data field contains a dynamic JSON object, which can vary depending on the specific event being published

Events list

The following table lists the payment batch funding events sent by Payment Issuing and a short description of each:

Event Name	Description
batch_created	Payment batch has been created
batch_held	Batch has been moved to held status. Requires account to have hold/release configured to “Yes”. Otherwise, the batch is automatically released and moves to batch_initiated.
batch_released	Batch has been released and will move to batch_initiated
batch_initiated	Batch has been initiated
batch_funding_requested	Sent when the Funding Request API returns success for a given batch’s funding request
batch_canceled	Batch has been cancelled. This is a terminal status for the batch and any payments in the batch.
batch_funding_completed	Batch has successfully completed funding, and the money is in a Optum-controlled bank account
batch_funding_failed	Batch has failed funding
batch_loading_requested	Payments in this batch have started loading into payment networks
batch_loaded	All payments in the batch have loaded into at least 1 payment network (e.g., all payments in the batch have at least 1 loading.completed event
batch_distributed	All payments in the batch have been distributed into at least 1 distribution network (e.g., all payments in the batch have at least 1 distribution.completed event)
batch_completed	Batch has completed loading and distributing. Published when both the batch_loaded and batch_distribution events have been published for a batch.
payment_removed	A payment was removed from the batch

Payment Batch Events Payload

In this section we'll explore together each event and it's payload that will be provided in the body.

Batch Created

Payment batch has been created

batch\_created Body

{
  "id": "45b93ecf-c718-4255-8485-10228f ca6713",
  "source": "https://example.com",
  "specVersion": "1.0",
  "type": "batch_created",
  "dataContentType": "application/json",
  "data": {
      "org": "ABC",
      "account": "ABC",
      "subAccount": "ABC001",
      "totalAmount": 100,
      "numberOfPayments": 1,
      "status": "Created",
      "fundingMethod": "PreFundedSameDay",
      "type": "batch_created"
  },
  "time": "2024-12-02T15:24:40. 6048459Z",
  "causationId": "134433a2-387d-48b8-9d7e-ddc7af8c705f"
}

batch\_created Fields

Field	Example	Description
org	ABC	The short code for the organization
account	ABC	The short code for the account
subAccount	ABC001	The short code for the sub-account
totalAmount	100	The sum total amount of all payments in the batch
numberOfPayments	4	The amount of payments in the batch
status	Created	The status of the batch
fundingMethod	PreFundedSameDay	The funding method associated with the account/subaccount for this batch
type	batch_created	The event type

Batch Held

Batch has been moved to held status. Requires Account to have hold/release configured to “Yes”. Otherwise, the batch is automatically released and moves to batch_initiated.

batch\_held Body

{
  "id": "45b93ecf-c718-4255-8485-10228f ca6713",
  "source": "https://example.com",
  "specVersion": "1.0",
  "type": "batch_held",
  "dataContentType": "application/json",
  "data": {
      "status": "Held",
      "fundingMethod": "PreFundedSameDay",
      "amount": 1754.98,
      "numberOfPayments": 1,
      "org": "MCK",
      "account": "MCK",
      "subAccount": "MCK002",
      "type": "batch_held"
  },
  "time": "2024-12-02T15:24:40. 6048459Z",
  "causationId": "134433a2-387d-48b8-9d7e-ddc7af8c705f"
}

batch\_held Fielxs

Field	Description	Example
org	The short code for the organization	ABC
account	The short code for the account	ABC
subAccount	The short code for the sub-account	ABC001
status	The status of the batch	Held
fundingMethod	The funding method associated with the account/subaccount for this batch	PreFundedSameDay
type	The event type	batch_held

Batch Released

Batch has been released and will move to batch_initiated

batch\_released Body

{
   "id": "45b93ecf-c718-4255-8485-10228f ca6713",
   "source": "https://example.com",
   "specVersion": "1.0",
   "type": "batch_released",
   "dataContentType": "application/json",
   "data": {
       "requestedBy": "[email protected]",
       "status": "Released",
       "amount": 1754.98,
       "numberOfPayments": 1,
       "org": "MCK",
       "account": "MCK",
       "subAccount": "MCK002",
       "type": "batch_released"
   },
   "time": "2024-12-02T15:24:40. 6048459Z",
   "causationId": "134433a2-387d-48b8-9d7e-ddc7af8c705f"
}

batch\_released Fields

Field	Description	Example
org	The short code for the organization	ABC
account	The short code for the account	ABC
subAccount	The short code for the sub-account	ABC001
status	The status of the batch	Released
requestedBy	The user account/email that requested the release	[email protected]
type	The event type	batch_released

Batch Initiated

Batch has been initiated

batch\_initiated Body

{
  "id": "45b93ecf-c718-4255-8485-10228f ca6713",
  "source": "https://example.com",
  "specVersion": "1.0",
  "type": "batch_initiated",
  "dataContentType": "application/json",
  "data": {
      "amount": 1754.98,
      "numberOfPayments": 1,
      "fundingMethod": "PreFundedSameDay",
      "status": "Initiated",
      "org": "MCK",
      "account": "MCK",
      "subAccount": "MCK001",
      "type": "batch_initiated"
  },
  "time": "2024-12-02T15:24:40. 6048459Z",
  "causationId": "134433a2-387d-48b8-9d7e-ddc7af8c705f"
}

batch\_initiated Fields

Field	Description	Example
org	The short code for the organization	ABC
account	The short code for the account	ABC
subAccount	The short code for the sub-account	ABC001
status	The status of the batch	Initiated
type	The event type	batch_initiated

Batch Funding Requested

Sent when the Funding Request API returns success for a given batch’s funding request

batch\_funding\_requested Body

{
  "id": "45b93ecf-c718-4255-8485-10228f ca6713",
  "source": "https://example.com",
  "specVersion": "1.0",
  "type": "batch_funding_requested",
  "dataContentType": "application/json",
  "data": {
      "status": "Funding",
      "fundingStatus": "Requested",
      "amount": 1754.98,
      "fundingMethod": "PreFundedSameDay",
      "fundingRequestId": "D24BD704KI",
      "org": "MCK",
      "account": "MCK",
      "subAccount": "MCK001",
      "type": "batch_funding_requested"
  },
  "time": "2024-12-02T15:24:40. 6048459Z",
  "causationId": "134433a2-387d-48b8-9d7e-ddc7af8c705f"
}

batch\_funding\_requested Fields

Field	Description	Example
org	The short code for the organization	ABC
account	The short code for the account	ABC
subAccount	The short code for the sub-account	ABC001
status	The status of the batch	Funding
fundingStatus	The status of the funding request	Requested
type	The event type	batch_funding_requested

Batch Cancelled

Batch has been cancelled. This is a terminal status for the batch and any payments in the batch.

batch\_cancelled Body

{
  "id": "45b93ecf-c718-4255-8485-10228f ca6713",
  "source": "https://example.com",
  "specVersion": "1.0",
  "type": "batch_canceled",
  "dataContentType": "application/json",
  "data": {
      "canceledBy": "[email protected]",
      "status": "Canceled",
      "amount": 1754.98,
      "numberOfPayments": 1,
      "org": "MCK",
      "account": "MCK",
      "subAccount": "MCK002",
      "type": "batch_canceled"
  },
  "time": "2024-12-02T15:24:40. 6048459Z",
  "causationId": "134433a2-387d-48b8-9d7e-ddc7af8c705f"
}

batch\_cancelled Fields

Field	Description	Example
org	The short code for the organization	ABC
account	The short code for the account	ABC
subAccount	The short code for the sub-account	ABC001
canceledBy	The user performing the modification	[email protected]
status	The status of the batch	Canceled
type	The event type	batch_canceled

Batch Funding Completed

Batch has successfully completed funding, and the money is in a Optum-controlled bank account

batch\_funding\_completed Body

{
   "id": "45b93ecf-c718-4255-8485-10228f ca6713",
   "source": "https://example.com",
   "specVersion": "1.0",
   "type": "batch_funding_completed",
   "dataContentType": "application/json",
   "data": {
       "fundingStatus": "Completed",
       "amount": 1754.98,
       "fundingMethod": "PreFundedNextDay",
       "fundingRequestId": "D24BD704KI",
       "initialRequestTime": "2024-11-13T17:55:01.610727",
       "org": "MCK",
       "account": "MCK",
       "subAccount": "MCK005",
       "type": "batch_funding_completed"
   },
   "time": "2024-12-02T15:24:40. 6048459Z",
   "causationId": "134433a2-387d-48b8-9d7e-ddc7af8c705f"
}

batch\_funding\_completed Fields

Field	Description	Example
org	The short code for the organization	ABC
account	The short code for the account	ABC
subAccount	The short code for the sub-account	ABC001
fundingStatus	The status of the funding request	Completed
type	The event type	batch_funding_completed

Batch Funding Failed

Batch has failed funding

batch\_funding\_failed Body

{
  "id": "45b93ecf-c718-4255-8485-10228f ca6713",
  "source": "https://example.com",
  "specVersion": "1.0",
  "type": "batch_funding_failed",
  "dataContentType": "application/json",
  "data": {
      "amount": 1754.98,
      "fundingMethod": "PreFundedSameDay",
      "fundingRequestId": "D24BD704KK",
      "initialRequestTime": "2024-11-13T17:50:12.9370276",
      "fundingStatus": "Failed",
      "org": "MCK",
      "account": "MCK",
      "subAccount": "MCK004",
      "type": "batch_funding_failed"
  },
  "time": "2024-12-02T15:24:40. 6048459Z",
  "causationId": "134433a2-387d-48b8-9d7e-ddc7af8c705f"
}

batch\_funding\_failed Fields

Field	Description	Example
org	The short code for the organization	ABC
account	The short code for the account	ABC
subAccount	The short code for the sub-account	ABC001
fundingStatus	The status of the funding request	Failed
type	The event type	batch_funding_failed

Batch Loading Requested

Payments in this batch have started loading into payment networks

batch\_loading\_requested Body

{
  "id": "45b93ecf-c718-4255-8485-10228f ca6713",
  "source": "https://example.com",
  "specVersion": "1.0",
  "type": "batch_funding_requested",
  "dataContentType": "application/json",
  "data": {
      "status": "Funding",
      "fundingStatus": "Requested",
      "amount": 1754.98,
      "fundingMethod": "PreFundedSameDay",
      "fundingRequestId": "D24BD704KI",
      "org": "MCK",
      "account": "MCK",
      "subAccount": "MCK001",
      "type": "batch_funding_requested"
  },
  "time": "2024-12-02T15:24:40. 6048459Z",
  "causationId": "134433a2-387d-48b8-9d7e-ddc7af8c705f"
}

batch\_loading\_requested Fields

Field	Description	Example
org	The short code for the organization	ABC
account	The short code for the account	ABC
subAccount	The short code for the sub-account	ABC001
status	The status of the batch	Loading
type	The event type	batch_loading_requested

Batch Loaded

Payments in this batch have started loading into payment networks

batch\_loaded Body

{
  "id": "45b93ecf-c718-4255-8485-10228f ca6713",
  "source": "https://example.com",
  "specVersion": "1.0",
  "type": "batch_loaded",
  "dataContentType": "application/json",
  "data": {
      "loadedPaymentCount": 1,
      "totalNumberOfPayments": 1,
      "amount": 1754.98,
      "org": "ABC",
      "account": "ABC",
      "subAccount": "ABC001",
      "type": "batch_loaded"
  },
  "time": "2024-12-02T15:24:40. 6048459Z",
  "causationId": "134433a2-387d-48b8-9d7e-ddc7af8c705f"
}

batch\_loaded Fields

Field	Description	Example
org	The short code for the organization	ABC
account	The short code for the account	ABC
subAccount	The short code for the sub-account	ABC001
loadedPaymentCount	The number of payments that have been loaded at least once	5
totalNumberOfPayments	The total number of payments in the batch	5
type	The event type	batch_loaded

Batch Distributed

All payments in the batch have loaded into at least one (1) payment network (e.g., all payments in the batch have at least one (1) loading.completed event

batch\_distributed Body

{
  "id": "45b93ecf-c718-4255-8485-10228f ca6713",
  "source": "https://example.com",
  "specVersion": "1.0",
  "type": "batch_distributed",
  "dataContentType": "application/json",
  "data": {
      "distributedPaymentCount": 1,
      "totalNumberOfPayments": 1,
      "amount": 1754.98,
      "org": "ABC",
      "account": "ABC",
      "subAccount": "ABC001",
      "type": "batch_distributed"
  },
  "time": "2024-12-02T15:24:40. 6048459Z",
  "causationId": "134433a2-387d-48b8-9d7e-ddc7af8c705f"
}

batch\_distributed Fields

Field	Description	Example
org	The short code for the organization	ABC
account	The short code for the account	ABC
subAccount	The short code for the sub-account	ABC001
distributedPaymentCount	The number of payments that have been distributed at least once	5
totalNumberOfPayments	The total number of payments in the batch	5
type	The event type	batch_distributed

Batch Completed

Batch has completed loading and distributing. Published when both the batch_loaded and batch_distribution events have been published for a batch.

batch\_completed Body

{
  "id": "45b93ecf-c718-4255-8485-10228f ca6713",
  "source": "https://example.com",
  "specVersion": "1.0",
  "type": "batch_distributed",
  "dataContentType": "application/json",
  "data": {
      "amount": 1754.98,
      "numberOfPayments": 1,
      "org": "ABC",
      "account": "ABC",
      "subAccount": "ABC001",
      "type": "batch_completed"
  },
  "time": "2024-12-02T15:24:40. 6048459Z",
  "causationId": "134433a2-387d-48b8-9d7e-ddc7af8c705f"
}

batch\_completed Fields

Field	Description	Example
org	The short code for the organization	ABC
account	The short code for the account	ABC
subAccount	The short code for the sub-account	ABC001
type	The event type	batch_completed

Payment Removed From Batch

A payment was removed from the batch

payment\_removed Body

{
  "id": "45b93ecf-c718-4255-8485-10228f ca6713",
  "source": "https://example.com",
  "specVersion": "1.0",
  "type": "batch_distributed",
  "dataContentType": "application/json",
  "data": {
      "payment": {
          "batchId": {
              "tenantId": "a976ced5-28ea-4e08-a267-024d2751e591",
              "uniqueId": "48dcb7da68a460bc48c045822fc75bb8"
          },
          "amount": 100.00,
          "issuerPaymentId": "48dc20ff1d97977e65209b927d28dc6b",
          "issuerReferenceId": "EVRYHEALTH004",
          "paymentDate": "2024-08-08",
          "shippingDetails": {
              "name": "John Doe",
              "address": {
                  "address1": null,
                  "address2": null,
                  "city": null,
                  "state": null,
                  "postalCode": null,
                  "country": null
              }
          },
          "remittanceMethod": "DATA",
          "adjudicationCutoffDate": "2024-08-08",
          "adjudicationVersion": "2",
          "jurisdictionalBody": "MN",
          "numberOfAttachedPdfFiles": 2,
          "availableBalance": 0.00,
          "previousAvailableBalance": null,
          "issuer": null,
          "acquirer": {
              "name": "John Doe",
              "taxId": "786532990",
              "address": {
                  "address1": "123 West St.",
                  "address2": "Apt 987",
                  "city": "Dallas",
                  "state": "TX",
                  "postalCode": "75227",
                  "country": "USA"
              },
              "nationalProviderId": null,
              "receiverId": null
          },
          "metaData": null,
          "status": "Created",
          "documentConsolidationStatus": "Requested",
          "paymentNetworks": [],
          "currentPaymentNetwork": null,
          "id": {
              "tenantId": "a976ced5-28ea-4e08-a267-024d2751e591",
              "individualPaymentId": "48dcb7da7936a24048c045833f6566ff"
          },
          "version": 1
      },
      "type": "payment_removed"
  },
  "time": "2024-12-02T15:24:40. 6048459Z",
  "causationId": "134433a2-387d-48b8-9d7e-ddc7af8c705f"
}

payment\_removed Fields

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Ut enim ad minim veniam, quis nostrud exercitation ullamco. Excepteur sint occaecat cupidatat non proident!

payment_removed Fields

Field	Description	Example
payment	The array of payments associated with the batch	ABC
payment.batchId	The batch identifier composed of two identifiers (tenantId, uniqueId)	00000000-0000-0000-0000-000000000000
payment.batchId.tenantId	The tenant identifier
payment.batchId.uniqueId	The unique batch identifier	48dcb7c9b530394c49e5cfab4f081cfb
payment.amount	The individual payment amount	100
payment.issuerPaymentId	The issuer payment identifier	48dc20ff1d97977e65209b927d28dc6b
payment.issuerReferenceId	ID that can be printed on payment documents to assist with customer service	EVRYHEALTH001
payment.paymentDate	DateOnly date of the payment	2024-08-08
payment.shippingDetails	Json object of the shipping information
payment.shippingDetails.name	The name for the shipping address	John Doe
payment.shippingDetails.address	Json object of the address information
payment.shippingDetails.address.address1	Address line 1 of the shipping information	123 West St.
payment.shippingDetails.address.address2	Address line 2 of the shipping information	Apt 987
payment.shippingDetails.address.city	The city of the shipping information	Dallas
payment.shippingDetails.address.state	The state of the shipping information	TX
payment.shippingDetails.address.postalCode	The postal/zip code of the shipping information	75227
payment.shippingDetails.address.country	The country	USA
payment.remittanceMethod	The remittance method to be use for this payment	DATA
payment.adjudicationCutoffDate	The adjudication cutoff date	2024-08-08
payment.adjudicationVersion	The adjudication version	2
payment.jurisdictionalBody	The jurisdictional body	MN
payment.numberOfAttachedPdfFiles	The number of attached pdf files	2
payment.availableBalance	They payments available balance (this should be 0 at the time of payment creation)	0
payment.previousAvailableBalance	The previous available balance (this should be 0 at the time of payment creation)	0
payment.issuer	Issuer information	null
payment.acquirer	The information about the acquirer
payment.acquirer.name	The acquirer name	John Doe
payment.acquirer.taxId	The acquirer tax identifier	786532990
payment.acquirer.address	Json object of the address information for acquirer
payment.acquirer.address.address1	Address line 1 of the shipping information	123 West St.
payment.acquirer.address.address2	Address line 2 of the shipping information	Apt 987
payment.acquirer.address.city	The city of the shipping information	Dallas
payment.acquirer.address.state	The state of the shipping information	TX
payment.acquirer.address.postalCode	The postal/zip code of the shipping information	75227
payment.acquirer.address.country	The country	USA
payment.acquirer.nationalProviderId	The acquirer's National Provider ID	1234567890
payment.acquirer.receiverId	The acquirer's receiver Id. Required if the payee is different than the person receiving the transaction (e.g., clearinghouse / billing service)	string
payment.metaData	The metadata dictionary	dynamic json object
payment.status	The payment status	Created
payment.documentConsolidationStatus	The document consolidation status	Requested
payment.paymentNetworks	The associated payment networks	json array
payment.currentPaymentNetwork	The current payment network for this payment	null
payment.id	The payments composite identifier (tenantId, individualPaymentId)	{"tenantId": "a976ced5-28ea-4e08-a267-024d2751e591","individualPaymentId": "48dcb7ccfcac025849e5cfac5e3a23f9"}
payment.id.tenantId	The tenant ID	a976ced5-28ea-4e08-a267-024d2751e591
payment.id.individualPaymentId	The individual payment ID	48dcb7ccfcac025849e5cfac5e3a23f9
payment.version	The version of the payment	1
type	payment_removed	payment_removed