Managing Billpay Transactions

👍

Notice

This guide is in a preliminary state. Some of the details may be incorrect, and we will be updating them as needed. Contact Galileo to report any errors or omissions.

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:

Displaying billpay transactions

Canceling billpay transactions

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

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 CST when it is in status: N (not processed), status: W (waiting to be printed) or status: P (printed). (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.

  1. The account holder launches a "cancel transaction" control on your interface for a paper biller.
  2. Do one of the following:
    • Call Get Bill Payment History and check the status on the transaction:
      • N, W or P — The transaction can be canceled. Call Cancel Bill Payment.
      • Other — The transaction cannot be canceled.
    • Call Cancel Bill Payment.
      • If the transaction can be canceled, the endpoint returns success.
      • If the transaction cannot be canceled, the endpoint returns status_code: 435-02.
  3. If the amount has already been adjusted out of the account, Galileo returns the amount to the account, sends the BADJ: adj event message, and writes the adjustment to the Posted Transactions RDF. It takes approximately two days to return the funds to the account.

Cancel one scheduled billpay transaction

To cancel the next transaction in a recurring series without canceling the series, follow these steps:

  1. Call Get Scheduled Bill Payments. The endpoint returns a billpay_transaction_id under future_scheduled_payments for all scheduled transactions.
  2. Call Cancel Bill Payment and populate the billpayTransactionId with the ID that you retrieved in the previous step.

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 Get Billers to retrieve the biller_id and type:
  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 transactions by removing the biller.

Deleting a biller

📘

Note

When you delete a biller, any scheduled 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.

To remove a biller, follow these steps:

  1. Call Get Billers to retrieve the biller_id of the biller to delete.
  2. Call Remove Biller and populate billerId with the ID you retrieved in the previous step.

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 Processing fees for the workflow.

External Trans API

If you are the system of record for your accounts, you can implement the Billpay Webhook 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

  1. The transaction is created by the scheduler, and Galileo runs through the same series of checks as in the Scheduled transaction workflow.

  2. Galileo creates the transaction in status: N and sends the BPCQ: billpay_request_made 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 BPAR: billpay_retry 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 BRRJ: billpay_rejected event message for electronic transactions only.
    • 00 — The adjustment is posted to the account. Galileo sends the BPAY: billpay 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:

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 curated list of transaction codes that you received from Galileo.

Transaction typeact_typeotype
Electronic postedADR
Electronic reversalADr
Paper check posted or reversedADZ
Electronic feeFE0301
Paper check feeFE0302
Check cancellation feeFE0303

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.

CodeNameDescription
BPCQbillpay_request_madeA billpay request was initiated. The billpay transaction has been created and is in status: N.
BPAYbillpayA billpay transaction was adjusted out of the account. This event is sent instead of BADJ: adj.
BPCMbillpay_check_mailedA billpay check order was created.
BPCCbillpay_check_clearedA billpay check was cashed and the payment has cleared.
BPARbillpay_retryThe 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.
BRRJbillpay_rejectedAn electronic transaction has been returned by Mastercard.
BSPFsched_billpay_failA scheduled bill payment has failed because of insufficient funds or some other problem in the process.
BPCRbillpay_request_returnedA recipient of a bill payment returned the check
BPEXbillpay_expiredA billpay check did not clear six months after the check's date, and the check is no longer valid.
BLVFbillpay_limit_violationA billpay transaction violated the velocity limit in LIMPB

Galileo setup

Galileo will configure these parameters according to your use case.

ParameterDescription
AAIGBControls whether to allow a billpay transaction to drive the account negative when using the External Trans API.
BPLBLContains a string to add to the adjustment description as a prefix for the biller name. When this parameter is not set, the default text “Billpay” is the prefix.
BPOTBControls 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.
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.
LIMBPSpecifies the maximum amount of an individual billpay transaction. When this parameter is not set, the maximum is $25,000.
RPPSCContains the RPPS payment ID and check digit.