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:

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

• <a href="doc:managing-billpay-transactions" target="_blank">**Managing Billpay Transactions**</a> — 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 <a href="doc:billpay-endpoints" target="_blank">Billpay Endpoints</a> guide.

• For details on managing billers and billpay transactions, see the <a href="doc:managing-billpay-transactions" target="_blank">Managing Billpay Transactions</a> 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 <<glossary: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.

<!--billpay-add-biller.pngggggg-->

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 <a href="doc:billpay-endpoints#search-biller-directory" target="_blank">Search Biller Directory</a> 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 <a href="doc:billpay-endpoints#add-rpps-biller" target="_blank">Add RPPS Biller</a> 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 <a href="doc:billpay-endpoints#add-paper-biller" target="_blank">Add Paper Biller</a> 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](🔗).

### 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.

<!--billpay-create-onetime-payment.pngg-->

1. The account holder goes to the billpay section of your interface.

2. You call the <a href="ref:post_getbillers" target="_blank">Get Billers</a> 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 <a href="doc:billpay-endpoints#create-bill-payment" target="_blank">Create Bill Payment</a> 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 <a href="doc:about-bill-pay#galileo-setup" target="_blank">the limit in LIMPB</a> If the limit is exceeded, the endpoint returns `status_code: 433-04`.

4. Galileo creates the transaction in `status: N`, sends the <a href="api-reference-events-api-billpay-request-made" target="_blank">`BPCQ: billpay_request_made`</a> 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 <a href="ref:api-reference-events-api-sched-billpay-fail" target="_blank">`BSPF: sched_billpay_fail`</a> event message.

   2. There must be sufficient funds. If not, Galileo sends the <a href="ref:api-reference-events-api-sched-billpay-fail" target="_blank">`BSPF: sched_billpay_fail`</a> event message.

   3. Velocity limits must not be exceeded. If they are, Galileo sends the <a href="ref:api-reference-events-api-billpay-limit-violation" target="_blank"> `BLVF: billpay_limit_violation`</a> event message.

6. The billpay process adjusts the transaction amount out of the account and sends the <a href="api-reference-events-api-billpay" target="_blank">`BPAY: billpay`</a> event message.

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:

#### 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 <a href="doc:billpay-endpoints#create-bill-payment" target="_blank">Create Bill Payment</a>, 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 <a href="doc:managing-billpay-transactions#external-trans-api" target="_blank">External Trans API</a> is not in use.

<!--billpay-create-scheduled-payment.pngg-->

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 <a href="api-reference-events-api-billpay-request-made" target="_blank">`BPCQ: billpay_request_made`</a> event message.

3. Galileo verifies that the account holder's account is active. If it is not, Galileo sends the <a href="api-reference-events-api-sched-billpay-fail" target="_blank">`BSPF: sched_billpay_fail`</a> event message.

4. Galileo verifies that the transaction amount does not exceed <a href="doc:about-bill-pay#galileo-setup" target="_blank">the limit in LIMPB</a>. If it does, Galileo sends the <a href="api-reference-events-api-billpay-limit-violation" target="_blank">`BLVF: billpay_limit_violation`</a> event message.

5. Galileo checks for sufficient funds.

   • If there are insufficient funds, Galileo sends the <a href="api-reference-events-api-sched-billpay-fail" target="_blank">`BSPF: sched_billpay_fail`</a> event message.

6. Galileo adjusts the transaction amount from the account and sends the <a href="api-reference-events-api-billpay" target="_blank">`BPAY: billpay`</a> event message.

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.

### Processing an electronic transaction

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

<!--billpay-create-RPPS-payment.pngg-->

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, <a href="ref:galileo-system-time" target="_blank">Galileo system time</a>, 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 is accepted by the bank and the biller, the transaction is posted to the biller’s bank account. Galileo does not receive notification of this event.

If the transaction does not pass the validation checks, or if the biller or the biller's bank returns the transaction, 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.

Galileo checks for the RPPS return file four times per day. When Galileo finds a rejected transaction in the return file, it performs these steps:

1. Sends the <a href="ref:api-reference-events-api-billpay-rejected" target="_blank">`BRRJ: billpay_rejected`</a> event message.

2. Returns the amount back to the account, sends the <a href="api-reference-events-api-adj" target="_blank">`BADJ: adj`</a> event message.

3. Includes the adjustment 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

Galileo checks for RPPS return files four times per day, at 06:10, 14:10, 18:10, and 22:10 <a href="ref:galileo-system-time" target="_blank">Galileo system time</a>. When Galileo finds a return file, it processes it right away. About 30 minutes after processing the file, Galileo returns the transaction amount to the account, sends the <a href="api-reference-events-api-adj" target="_blank">`BADJ: adj`</a> event message, and includes the adjustment in the Posted Transactions RDF.

### Processing a paper billpay transaction

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

<!--billpay-create-paper-payment.pngg-->

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, <a href="ref:galileo-system-time" target="_blank">Galileo system time</a>. Check transactions that are initiated before midnight are included in this batch. Transactions initiated after midnight are processed the next business day.

2. Galileo prints the check and changes the transaction to `status: Q`.

3. On the same day, Galileo sends the check in the mail. Galileo then changes the transaction to `status: P`, sends the <a href="api-reference-events-api-billpay-check-mailed" target="_blank">`BCPM: billpay_check_mailed`</a> event message and includes the transaction in the Posted Transactions RDF

4. If the check is returned, Galileo sends the <a href="api-reference-events-api-adj" target="_blank">`BPCR: billpay_request_returned`</a> event message.

   • Galileo later returns the amount to the account, sends the <a href="api-reference-events-api-adj" target="_blank">`BADJ: adj`</a> event message, and includes the adjustment in the Posted Transactions RDF.

5. If the check is cashed within 180 days, Galileo sends the <a href="api-reference-events-api-billpay-check-cleared" target="_blank">`BPCC: billpay_check_cleared`</a> event message.

6. If the check is not cashed within 180 days:

   1. Galileo sends the <a href="api-reference-events-api-billpay-expired" target="_blank">`BPEX: billpay_expired`</a> event message and changes the transaction to `status: L`.

   2. Galileo records the check in the cancellation file and changes the transaction to `status: U`.

   3. Galileo returns the amount to the account, sends the <a href="api-reference-events-api-adj" target="_blank">`BADJ: adj`</a> event message, changes the transaction to `status: Y`, and includes the adjustment in the Posted Transactions RDF.

#### Example paper check

<!--billpay-check-example.pngg-->

The fields for the check are derived as follows:

• **`billerAccountNo`** — <a href="doc:billpay-endpoints#add-paper-biller" target="_blank">Add Paper Biller</a> endpoint.

• **Account Holder Name** — `firstName` and `lastName` of an enrollment endpoint such as <a href="ref:post_createaccount" target="_blank">Create Account</a>. For business accounts this is the business name.

• **Biller address fields** — <a href="doc:billpay-endpoints#add-paper-biller" target="_blank">Add Paper Biller</a> endpoint.

• **`memo`** — <a href="doc:billpay-endpoints#create-bill-payment" target="_blank">Create Bill Payment</a> 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 <a href="doc:api-reference-bill-payment-statuses" target="_blank">transaction status</a> 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 <a href="doc:managing-billpay-transactions#fees" target="_blank">set up billpay fees</a>, 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.

<!--billpay-fee.pngggggg-->

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.