Creating a Billpay Transaction

This guide explains how to use the Program API to add billers to an account and how to initiate a billpay transaction, either for one time or on a schedule.

Along with this guide you may want to read these other guides:

• About Bill Pay — General information about bill pay at Galileo
• Managing Billpay Transactions — Instructions for displaying and canceling billpay transactions and removing billers.

Billpay endpoints

Integrate these endpoints with your billpay interface according to the use case.

• For details on using these endpoints, see the Billpay Endpoints guide.
• For details on managing billers and billpay transactions, see the Managing Billpay Transactions guide.

Adding a biller

Before you can initiate a billpay transaction, you must add the biller to the account holder's account. Billers are associated with an account holder's primary PRN, so adding a biller to one PRN does not add it to another account holder's PRN, even if the account holders share the same balance. If 10 account holders need to add the same biller, you must add that biller 10 times, to each individual account.

📘

Note

You cannot add or modify a biller unless the account is active (status: N).

1. The account holder launches an "add biller" control in your interface.
2. Your interface prompts the account holder to provide the name of the biller.
3. Call the Search Biller Directory endpoint to look for the biller name in the RPPS database. (Galileo recommends passing the billerState parameter to help distinguish between billers with the same name.)
   • If the biller is in the database:
     1. Galileo returns one or more billers that match the string in billerName. Each biller has an rpps_biller_id.
     2. If there is more than one result, the account holder selects the correct biller.
     3. You call the Add RPPS Biller endpoint to create the electronic biller. Optionally, the account holder can schedule a billpay transaction or create a one-time transaction.
     4. The endpoint response includes the biller_id.
   • If the biller is not in the database:
     1. Galileo returns status code 421-01.
     2. You call the Add Paper Biller endpoint to create the paper biller. Optionally, the account holder can schedule a billpay transaction or create a one-time transaction.
     3. The endpoint response includes the biller_id.

📘

Note

If the account holder creates a one-time transaction using these Add X Biller endpoints, it is not necessary to call Create Bill Payment to initiate the transaction.

Creating a billpay transaction

A billpay transaction is initiated in one of these ways:

• At the time the biller is added, as shown in Adding a biller:
  • The account holder creates a one-time transaction.
  • The account holder creates scheduled transactions.
• After the biller has been added:
  • The account holder creates a billpay transaction, as shown in Creating a one-time billpay transaction, below.
  • The scheduler creates a billpay transaction, as shown in Scheduling billpay transactions.

📘

Note

You cannot initiate a billpay transaction unless the account is active (status: N).

Creating a one-time billpay transaction

After a biller has been created, you can create a transaction. This process applies to both electronic and paper check transactions.

One-time transaction workflow

This diagram shows how Galileo processes one-time transactions that are initiated by the Program API. This workflow assumes that Galileo is the system of record. If you are the system of record for your program, perform your own balance check before calling Create Bill Payment.

1. The account holder goes to the billpay section of your interface.
2. You call the Get Billers endpoint and present the list of billers.
   • If the desired biller is not present, the account holder activates an "add biller" control on your interface. You follow the Adding a biller procedure, and the account holder optionally creates a one-time transaction with the process date of today. When creating the transaction in this way, the rest of the process follows the Scheduled transaction workflow.
   • If the desired biller is present, the account holder selects the biller. You call the Create Bill Payment endpoint using the biller_id as returned by the Get Billers endpoint.
3. The endpoint performs these verification checks:
   1. The biller_id must be associated with the account holder's PRN. If it is not, the endpoint returns status_code: 433-01.
   2. The processDate must be the current date or later. If it is in the past, the endpoint returns status_code: 433-02. If there is no processDate in the request, it defaults to the current date.
   3. The account status must be active. If it is not, the endpoint returns status_code: 433-06.
   4. The amount must be a positive number. If it is not, the endpoint returns status_code: 433-03.
   5. The transaction amount must not exceed the limit in LIMBP If the limit is exceeded, the endpoint returns status_code: 433-04.
   6. The available balance in the account must be equal to or greater than the transaction amount. If there are insufficient funds, the endpoint returns status_code: 433-05. See Balance checks and ledger adjustment for more information on balance-check timing.
4. Galileo creates the transaction in status: N, sends the BPCQ: billpay_request_made event message, and the endpoint returns status_code: 00.
5. Every 30 minutes, at :08 and :38 past the hour, Galileo's billpay process runs. The process performs these checks again:
   1. The account must be active. If it is not, Galileo sends the BSPF: sched_billpay_fail event message.
   2. There must be sufficient funds. If not, Galileo sends the BSPF: sched_billpay_fail event message. See Balance checks and ledger adjustment for more information on balance-check timing.
   3. Velocity limits must not be exceeded. If they are, Galileo sends the BLVF: billpay_limit_violation event message.
6. The billpay process adjusts the transaction amount out of the account and sends the BPAY: billpay event message. See Balance checks and ledger adjustment for more information on ledger-adjustment timing.
7. 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.
8. The billpay process then changes the transaction status according to the biller type:
   • status: O (letter O) — Electronic biller. See Processing an electronic transaction for next steps.
   • status: W — Paper biller. See Processing a paper billpay transaction for next steps.

Scheduling billpay transactions

Use one of these methods to schedule billpay transactions in the future.

📘

Note

You cannot create scheduled billpay transactions unless the account is active (status: N).

One-time transaction

• When adding or modifying a biller (Add X Biller or Modify X Biller), pass these parameters:
  • frequencyType: O (letter O)
  • nextDate: future date
  • endDate: same as nextDate
  • amount: amount of the transaction
• When creating a one-time transaction with Create Bill Payment, input a future date for processDate.

Recurring transactions

• When adding or modifying a biller (Add X Biller or Modify X Biller), select one of these options. With recurring transactions, nextDate, endDate, and amount are required:
  • W — Weekly
  • M — Monthly
  • Q — Quarterly
  • Y — Yearly
• nextDate — Date of first scheduled transaction
• endDate — Date of last scheduled transaction, up to five years in the future
• amount — Amount of the scheduled transaction

📘

Note

The maximum value of endDate is five years after the current date. For example, if today is 20 Jan 2020, the end date can be no later than 20 Jan 2025. However, if today's date is leap day, such as 29 Feb 2020, the latest date can be 1 Mar 2025 instead of 28 Feb.

Scheduled transaction workflow

This is the workflow for a billpay transaction when the scheduler initiates the transaction. The flowchart assumes that the External Trans API is not in use.

1. On the process date for the transaction, the scheduler initiates the billpay transaction process. The scheduler begins to run every morning.
2. Galileo creates the transaction in status: N and sends the BPCQ: billpay_request_made event message.
3. Galileo verifies that the account holder's account is active. If it is not, Galileo sends the BSPF: sched_billpay_fail event message.
4. Galileo verifies that the transaction amount does not exceed the limit in LIMBP. If it does, Galileo sends the BLVF: billpay_limit_violation event message.
5. Galileo checks for sufficient funds.
   • If there are insufficient funds, Galileo sends the BSPF: sched_billpay_fail event message. See Balance checks and ledger adjustment for more information on balance-check timing.
6. Galileo adjusts the transaction amount from the account and sends the BPAY: billpay event message. See Balance checks and ledger adjustment for more information on ledger-adjustment timing.
7. 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.
8. The billpay process also changes the transaction status according to the biller type:
   • status: O (letter O) — Electronic biller. See Processing an electronic transaction for next steps.
   • status: W — Paper biller. See Processing a paper billpay transaction for next steps.

Balance checks and ledger adjustment

This section details the timing of when Galileo checks balances and when it adjusts the ledger. The timing depends on how the billpay transaction was initiated. Click the initiation method to see the steps.

One-time transaction

For a one-time bill payment, this is the sequence of events for a 20.00 payment. The beginning balance is 100.00:

1. Call Create Bill Payment for an existing biller.
2. The endpoint checks the balance.
3. If there are sufficient funds, Galileo creates the 20.00 transaction in status: N.
4. At this point, the 20.00 is pending. When you call a Program API endpoint to check the balance, these are the results:
   • Get Balance:
     • pending_billpay: 20
     • balance: 80
     • balance_without_pending: 100
   • Get Account by ID:
     • balance: 80
   • Verify Account:
     • balance: 80
5. The billpay binary runs at :08 and :38 past the hour and conducts another balance check.
6. If there are still sufficient funds, the 20.00 is adjusted out of the account. When you call a Program API endpoint to check the balance, these are the results:
   • Get Balance:
     • pending_billpay: 0
     • balance: 80
     • balance_without_pending: 80
   • Get Account by ID:
     • balance: 80
   • Verify Account:
     • balance: 80

Scheduled transaction

For scheduled bill payments, this is the sequence of events for a 35.00 payment. The beginning balance is 100.00:

1. The endpoint to create the transaction is called on the 10th of the month, and the payment is scheduled for the 28th of the month. There is no balance check on the 10th.
2. From the 10th to the 27th, the transaction request exists but there is still no balance check and no pending payment on the ledger.
3. On the morning of the 28th, the scheduler initiates the process and performs a balance check.
4. If there are sufficient funds, Galileo creates the 35.00 transaction in status: N.
5. At this point, the 35.00 is a pending payment. When you call a Program API endpoint to check the balance, these are the results:
   • Get Balance:
     • pending_billpay: 35
     • balance: 65
     • balance_without_pending: 100
   • Get Account by ID:
     • balance: 65
   • Verify Account:
     • balance: 65
6. Almost immediately afterwards, the 35.00 is adjusted out of the account. When you call a Program API endpoint to check the balance, these are the results:
   • Get Balance:
     • pending_billpay: 0
     • balance: 65
     • balance_without_pending: 65
   • Get Account by ID:
     • balance: 65
   • Verify Account:
     • balance: 65

Processing billpay transactions

After the billpay transaction has been initiated, the transaction is processed differently depending on whether it is an electronic (RPPS) or paper-check transaction:

• Electronic
• Check

Processing an electronic transaction

On the same day that the electronic transaction is initiated, Galileo performs these actions:

1. The electronic transaction is in status: O (in process). An internal process adds electronic transactions to the RPPS originator file and changes the transaction to status: P. This process runs at 08:45, 13:45, 16:45 and 22:45, Galileo system time, 365 days per year.
2. Galileo sends the RPPS file to Mastercard, and the transaction is included in the Posted Transactions RDF.
3. Mastercard receives the RPPS file and validates the transactions.
   • If the transaction passes the validation checks, Mastercard sends the billpay transaction to the biller's bank.
   • If the transaction does not pass the validation checks, Mastercard sends the transaction back to Galileo in an RPPS return file. Galileo sends the BRRJ: billpay_rejected event message.
4. The transaction is posted to the biller’s bank account. Galileo does not receive notification of this event.
   • If the transaction is rejected by the biller or the biller's bank, Mastercard includes it in an RPPS return file that it sends to Galileo. It can take several days or longer for a transaction to be included in the return file.

RPPS return file

Galileo checks for RPPS return files four times per day, at 06:10, 14:10, 18:10, and 22:10 Galileo system time. When Galileo finds a return file, it processes it right away. About 30 minutes after processing the file:

1. Galileo returns the transaction amount to the account and sends the BADJ: adj event message.
2. The adjustment is included in the Posted Transactions RDF.

Electronic timing

When billers register with Mastercard RPPS, they select a method for Mastercard to send the transaction to the biller's bank. The method can be ACH or it can be a quicker, electronic method. It is therefore possible for an electronic transaction to be posted to the biller's account on the same day that Galileo processes it; likewise, the transaction might be posted a few days later, depending on the delivery method chosen by the biller.

This table shows the approximate amount of time it takes to transition between electronic transaction statuses.

Processing a paper billpay transaction

On the next business day after a paper transaction is initiated, Galileo performs these actions:

1. Transactions in status: W (waiting to be printed) are picked up by Galileo’s paper check process once per business day at 06:00, Galileo system time. Check transactions that are initiated before midnight are included in this batch. Transactions initiated after midnight are processed the next business day.
2. A vendor prints the check on behalf of Galileo.
3. On the same day, the vendor sends the check in the mail on behalf of Galileo. Galileo then changes the transaction to status: P, sends the BPCM: billpay_check_mailed event message and includes the transaction in the Posted Transactions RDF
4. If the check is returned, Galileo sends the BPCR: billpay_request_returned event message.
   • Galileo later returns the amount to the account, sends the BADJ: adj event message, and includes the adjustment in the Posted Transactions RDF.
5. If the check is cashed within 180 days, Galileo sends the BPCC: billpay_check_cleared event message and changes the transaction to status: C.
6. If the check is not cashed within 180 days:
   1. Galileo sends the BPEX: billpay_expired event message and changes the transaction to status: L.
   2. Galileo records the check in the cancellation file and changes the transaction to the temporary status: U.
   3. Galileo returns the amount to the account, sends the BADJ: adj event message, changes the transaction to status: Y, and includes the adjustment in the Posted Transactions RDF.

Example paper check

The fields for the check are derived as follows:

• Account Holder Name — firstName and lastName of an enrollment endpoint such as Create Account. For business accounts this is typically businessName, but for some legacy clients the business name is in the firstName field. You can use the CST to specify this name.
  • The field on the check is limited to 47 characters including spaces. The system will truncate any name that exceeds this limit. If a truncated name or business name in this context is unacceptable, you can use Update Account or the CST to shorten the name to fit.
• Biller address fields — Add Paper Biller endpoint.
• memo — Create Bill Payment endpoint. This string is not available in the RDFs. Checks generated by the scheduler do not have a memo entry.

Paper check timing

Galileo typically prints and mails a paper check on the next business day after the transaction was initiated. The biller receives the check depending on post office handling. Galileo estimates ~10 days after the transaction is initiated. After that, the biller decides when to cash the check. If the biller does not cash the check within 180 days (six months) of the check date, Galileo voids the check and returns the amount to the account.

A check can be returned to Galileo either by the post office (bad address), by the biller, or by the biller's bank, and the timing of the return depends on post office handling, the decision of the biller, or the bank's processing schedule. (Galileo cannot tell you why the bank returned a check; you must ask the bank for that information.) When Galileo receives a returned check—or when a check expires—it takes approximately 1–3 days to return the amount to the account.

This table shows the approximate interval between transaction status changes. Factors such as the number of checks to process in a day can affect how quickly Galileo prints and mails checks as well as how fast returned and expired checks are processed.

Processing fees

When you set up billpay fees, the billpay process performs extra steps to process the fee. The fee process begins right after the adjustment is posted, as shown in this flowchart.

1. After the billpay process posts the adjustment to the account, Galileo checks for any billpay fees.
   • If there are no fees, Galileo does not follow the fee process and skips to step 3.
   • If a fee is configured, Galileo verifies that there are sufficient funds for the fee.
     • If there are sufficient funds, the process continues to step 2.
     • If there are insufficient funds, Galileo checks the AAIGB parameter.
       • Set — When the fee is removed from the account, it drives the balance negative.
       • Not set — Galileo checks the BPPPF parameter.
         • Set — The fee is deferred until there are sufficient funds in the account.
         • Not set — Galileo rolls back both the fee and the billpay adjustment and sends the BSPF: sched_billpay_fail event message.
2. Galileo determines whether the fee is for an electronic or a paper billpay transaction:
   • Electronic — The BPY fee is applied.
   • Paper — The CHK fee is applied.
3. The billpay process then changes the transaction status according to the biller type:
   • status: O (letter O) — Electronic biller. See Processing an electronic transaction for next steps.
   • status: W — Paper biller. See Processing a paper billpay transaction for next steps.