This guide contains instructions for managing billpay transactions that have been initiated as well as how to manage billers. This guide also contains information about the External Trans API. Along with this guide you may want to read these other guides:

  • <a href="doc:about-bill-pay" target="_blank">**About Bill Pay**</a> — General information about bill pay at Galileo

  • <a href="doc:creating-a-billpay-transaction" target="_blank">**Creating a Billpay Transaction**</a> — Instructions for creating billpay transactions, including adding billers and creating scheduled transactions

## Displaying billpay transactions

  • Call <a href="ref:post_getscheduledbillpayments" target="_blank">Get Scheduled Bill Payments</a> to retrieve transactions with process dates that are equal to or later than the current date.

  • Call <a href="ref:post_getbillpayhistory" target="_blank">Get Bill Payment History</a> to retrieve all billpay transactions between the start and end dates, both past and future.

  • Call any transaction-retrieval endpoint that returns posted transactions to display billpay transactions in a full transaction list:

    • <a href="ref:post_getaccountoverview" target="_blank">Get Account Overview</a>

    • <a href="ref:post_gettranshistory" target="_blank">Get Transaction History</a>

    • <a href="ref:post_getalltranshistory" target="_blank">Get All Transaction History</a>

## Canceling billpay transactions

To cancel a billpay transaction, follow one of these procedures:

  • [Cancel an electronic transaction](🔗)

  • [Cancel a paper check transaction](🔗)

  • [Cancel one scheduled billpay transaction](🔗)

  • [Cancel a scheduled billpay series](🔗)

### Cancel an electronic transaction

Because of the small interval between electronic transaction creation and processing, you cannot cancel electronic transactions after the transaction has been created. Do not attempt to use the Cancel Transaction endpoint to cancel an electronic transaction, or you could set up a race condition with undesirable results. However, you can cancel an electronic transaction with the Program API [that is scheduled for the future](🔗).

### Cancel a paper check transaction

You can cancel a paper check transaction using the Program API or <<glossary:CST>> when it is in `status: N` (not processed), `status: W` (waiting to be processed) or `status: P` (processed). In `status: Q` (printed) you might be able to cancel it through the CST. (Sometimes, it's too late to cancel a check after it's been printed.) You can also cancel paper transactions [that are scheduled for the future](🔗).

871


<!--billpay-cancel-paper-payment.png...........-->

  1. The account holder launches a "cancel transaction" control on your interface for a paper biller.

  2. Do one of the following:

    • _Recommended._ Check the status of the payment first. Call <a href="ref:post_getbillpaythistory" target="_blank">Get Bill Payment History</a> and get the `status` on the transaction:

      • `N`, `W` or `P` — The transaction can be canceled with the CST or the Program API. Call <a href="ref:post_cancelbillpayment" target="_blank">Cancel Bill Payment</a>.

      • `Q` — The transaction must be cancelled in the CST.

      • **Other** — The transaction cannot be canceled.

    • Call <a href="ref:post_cancelbillpayment" target="_blank">Cancel Bill Payment</a>.

      • If the transaction can be canceled, the endpoint returns success.

      • If the transaction cannot be canceled, the endpoint returns `status_code: 435-02`. The endpoint does not return the status, so if the transaction is in `status: Q`, when it can be cancelled in the CST, you will not know.

  3. The transaction is changed to `status: K` (check cancellation requested) and the current datetime is set as the return date.

  4. Galileo confirms with the bank that the check has been cancelled. This process takes approximately two days.

  5. If the amount had already been adjusted out of the account, Galileo returns the amount to the account, sends the <a href="ref:api-reference-events-api-adj" target="_blank">`BADJ: adj`</a> event message, and includes the adjustment in the Posted Transactions RDF.

  6. If the CHC (check cancellation) fee has been set up, Galileo assesses the fee, sends the <a href="ref:api-reference-events-api-fee" target="_blank">`BFEE: fee`</a> event message, and includes the fee in the Posted Transactions RDF.

  7. The transaction is changed to `status: X`.

### Cancel a future billpay transaction

To cancel a non-recurring payment that is scheduled for the future, follow these steps:

  1. Call <a href="ref:post_getscheduledbillpayments" target="_blank">Get Scheduled Bill Payments</a>. The endpoint returns a `billpay_transaction_id` under `future_scheduled_payments`.

  2. Call <a href="ref:post_cancelbillpayment" target="_blank">Cancel Bill Payment</a> and populate the `billpayTransactionId` with the ID that you retrieved in the previous step.

Note

You cannot cancel one particular payment of a recurring payment series, because its `billpay_transaction_id` is not created until the day the payment is scheduled to take place.

### Cancel a scheduled billpay series

If an account holder has set up recurring billpay transactions and wants to cancel the whole series, follow these steps:

  1. Call <a href="ref:post_getbillers" target="_blank">Get Billers</a> to retrieve the `biller_id` and `type`:

    • `type: E` — Call <a href="doc:billpay-endpoints#modify-rpps-biller" target="_blank">Modify RPPS Biller</a>.

    • `type: P` — Call <a href="doc:billpay-endpoints#modify-paper-biller" target="_blank">Modify Paper Biller</a>.

  2. Do one of these things:

    • Set the `endDate` to today's date.

    • Pass `Null` for these parameters: `frequencyType`, `nextDate`, `endDate`.

Note

You cannot cancel future or scheduled transactions by removing the biller.

## Deleting a biller

Note

When you delete a biller, any scheduled or future transactions for that biller are not deleted. If you also want to deactivate the scheduled transactions, first follow the procedure in [Cancel a scheduled billpay series](🔗) and then afterwards remove the biller using the steps below. You might also need to manually delete [any future non-recurring transactions](🔗).

To remove a biller, follow these steps:

  1. Call <a href="ref:post_getbillers" target="_blank">Get Billers</a> to retrieve the `biller_id` of the biller to delete.

  2. Call <a href="ref:post_removebillers" target="_blank">Remove Biller</a> and populate `billerId` with the ID you retrieved in the previous step.

## Closing an account with billpay

When you close an account in the CST that uses billpay, and there are pending billpay transactions at the time of account closing, Galileo sends the <a href="ref:api-reference-events-api-billpay-cancelled" target="_blank">`BPCL: billpay_cancelled`</a> event message. This message is not generated if you close the account using the Program API.

Follow the steps in [Cancel a scheduled billpay series](🔗) to cancel the remaining transactions. As necessary, follow the steps in [Cancel a future billpay transaction](🔗) to cancel non-recurring transactions.

If you do not cancel the remaining transactions, on the day the next transaction is scheduled, Galileo checks for an active account, and because the account is closed, the process stops, and Galileo sends <a href="ref:api-reference-events-api-sched-billpay-fail" target="_blank">`BSPF: sched_billpay_fail`</a>.

## Fees

You can configure these fees for your product, as desired:

Fee codeDescriptionTransaction code
BPYBillpay fee (electronic)FE0301
CHKBillpay fee (paper check)FE0302
CHCBillpay fee (check cancelation)FE0303

The fee is assessed at the time that the billpay amount is adjusted out of the account. If there are insufficient funds for the billpay amount plus the fee, Galileo denies the transaction.

However, you can choose to defer the fee if there are insufficient funds for it by setting the BPPPF parameter. With that parameter set, the transaction is approved if there are sufficient funds for the billpay amount but not the fee. The fee remains in a pending state until sufficient funds are deposited in the account, at which time the fee is assessed.

In the Posted Transactions RDF, the fee is a separate transaction from the billpay adjustment, with the transaction code as shown in the table above.

See <a href="doc:about-fees" target="_blank">About Fees</a> for additional information about fees for Billpay. See <a href="doc:creating-a-billpay-transaction#processing-fees" target="_blank">Processing fees</a> for the workflow.

## External Trans API

<!--Review copy: External Trans APIIIIIIIIIIIIIIII-->

If you are the system of record for your accounts, you can implement the <a href="ref:webhook_billpay_post" target="_blank">Billpay Webhook</a> of the External Trans API. Galileo sends you a webhook for each scheduled billpay transaction before it is adjusted out of the account, which you approve or deny for insufficient funds. Set the BPOTB parameter so that Galileo does not check for limit violations or for sufficient funds before sending you the webhook.

When using the Billpay Webhook, you can also determine whether transactions that you approve can drive the account negative, by setting the AAIGB parameter.

If you are the system of record for your program, perform your own balance check before calling the Create Bill Payment endpoint.

### External Trans API workflow

<!--billpay-external-trans.pngggggggggggggggg-->

  1. The transaction is created by the scheduler, and Galileo runs through the same series of checks as in the <a href="doc:creating-a-billpay-transaction#scheduled-transaction-workflow" target="_blank">Scheduled transaction workflow</a>.

  2. Galileo creates the transaction in `status: N` and sends the <a href="doc:ref:api-reference-events-api-billpay-request-made" target="_blank">`BPCQ: billpay_request_made`</a> event message.

  3. Galileo sends you a billpay webhook for the transaction.

  4. You check the account balance and send back a response code:

    • `99` (error; retry) or no response — If retry is set up for your program, Galileo sends the <a href="ref:api-reference-events-api-billpay-retry" target="_blank">`BPAR: billpay_retry`</a> event message, waits for a configured interval, and then resends the webhook.

    • `01` (insufficient funds) or `98` (error; no retry) — Transaction is changed to `status: E` and Galileo sends the <a href="ref:api-reference-events-api-billpay-rejected" target="_blank">`BRRJ: billpay_rejected`</a> event message for electronic transactions only.

    • `00` — The adjustment is posted to the account. Galileo sends the <a href="ref:api-reference-events-api-billpay" target="_blank">`BPAY: billpay`</a> event message.

  5. The billpay process checks for a fee.

    • If there is a fee, the [Processing fees](🔗) process is followed.

    • If there is no fee, the process continues.

  6. Galileo changes the transaction to one of these statuses:

    • `status: O` — Electronic transaction. See <a href="doc:creating-a-billpay-transaction#processing-an-electronic-transaction" target="_blank">Processing an electronic transaction</a> for next steps.

    • `status: W` — Paper check transaction. See <a href="doc:creating-a-billpay-transaction#processing-a-paper-billpay-transaction" target="_blank">Processing a paper billpay transaction</a> for next steps.

## Billpay transaction codes

These are some of the transaction codes that are associated with bill pay. To see exactly which transaction codes your program uses, consult the Funds Flow document that you received from Galileo.

Transaction type`act_type``otype`
Electronic posted`AD``R`
Electronic reversal`AD``r`
Paper check posted or reversed`AD``Z`
Electronic fee`FE``0301`
Paper check fee`FE``0302`
Check cancellation fee`FE``0303`

## Events API

Arrange with Galileo to have some or all of these events sent to you to alert you of billpay-related events in real time.

MessageDescription
<a href="ref:api-reference-events-api-billpay-request-made" target="_blank">`BPCQ: billpay_request_made`</a>A billpay request was initiated. The billpay transaction has been created and is in `status: N`.
<a href="ref:api-reference-events-api-billpay" target="_blank">`BPAY: billpay`</a>A billpay transaction was adjusted out of the account. This event is sent instead of `BADJ: adj`.
<a href="ref:api-reference-events-api-billpay-cancelled" target="_blank">`BPCL: billpay_cancelled`</a>An account that uses billpay was cancelled in the CST, and it had one or more pending billpay transactions when closed
<a href="ref:api-reference-events-api-billpay-check-mailed" target="_blank">`BPCM: billpay_check_mailed`</a>A billpay check order was created.
<a href="ref:api-reference-events-api-billpay-check-cleared" target="_blank">`BPCC: billpay_check_cleared`</a>A billpay check was cashed and the payment has cleared.
<a href="ref:api-reference-events-api-billpay-retry" target="_blank">`BPAR: billpay_retry`</a>The billpay process must retry a transaction that was sent to the [External Trans API](🔗). Either a timeout occurred, or you indicated that Galileo should try again later.
<a href="ref:api-reference-events-api-billpay-rejected" target="_blank">`BRRJ: billpay_rejected`</a>An electronic transaction has been returned by Mastercard.
<a href="ref:api-reference-events-api-sched-billpay-fail" target="_blank">`BSPF: sched_billpay_fail`</a>A scheduled bill payment has failed because of insufficient funds or some other problem in the process.
<a href="ref:api-reference-events-api-billpay-request-returned" target="_blank">`BPCR: billpay_request_returned`</a>A recipient of a bill payment returned the check
<a href="ref:api-reference-events-api-billpay-expired" target="_blank">`BPEX: billpay_expired`</a>A billpay check did not clear six months after the check's date, and the check is no longer valid.
<a href="ref:api-reference-events-api-billpay-limit-violation" target="_blank">`BLVF: billpay_limit_violation`</a>A billpay transaction violated the velocity limit in LIMPB.

## Galileo setup

Galileo will configure these product parameters according to your use case.

ParameterDescriptionValues
AAIGBControls whether to allow a billpay transaction to drive the account negative when using the [External Trans API](🔗).<li>**Y** — Allow transactions to drive the balance negative.<li>**N** — Decline transactions that would drive the balance negative.
BPLBLContains a string to add to the adjustment description as a prefix for the biller name.<li>**[string]** — Text to prepend bill pay descriptions.<li>**Hyphen (`-`)** — Do not prepend anything to bill pay descriptions.<li>**Not set** — Prepend bill pay descriptions with the default text: `Billpay`.
BPOTB_Provider parameter_. Controls whether to check the maximum limit and balance before creating a billpay transaction. Set this parameter only if you maintain the ledger for your accounts instead of Galileo and you are using the [External Trans API](🔗).<li>**1** — Do not check the balance.<li>**Other or not set** — Check the balance.
BPPPFControls whether a billpay transaction fails if the available balance is insufficient to cover fees. When this parameter is set, the fee is deferred until later when the current balance is sufficient for the billpay transaction but not the fee.<li>**Y** — Allow bill pay to proceed when there are sufficient funds to cover only the payment.<li>**Other or not set** — Allow bill pay to proceed only when there are sufficient funds for both the payment and the processing fee.
LIMBPSpecifies the maximum amount of an individual billpay transaction. When this parameter is not set, the maximum is $25,000.<li>**Decimal number** — Maximum amount for a bill pay transaction<li>**Not set** — Bill pay transactions have a $25,000 limit
RPPSCContains the RPPS payment ID and check digit.9-digit number