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 SoFi Tech Solutions - **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. | Use case | Endpoint | | ----------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------- | | Display a list of billers that have been configured for the account holder. | Get Billers | | Find out if a biller is in the RPPS database | Search Biller Directory | | Add an electronic biller for the account holder; optionally, add a one-time payment or a series of payments | Add RPPS Biller | | Modify biller information or change recurring payments | Modify RPPS Biller | | Add a biller that is not in the RPPS database, which will receive a paper check; optionally, add a one-time payment or series of payments | Add Paper Biller | | Modify biller information or change recurring payments | Modify Paper Biller | | Delete a biller from the account holder's account | Remove Biller | | Initiate a one-time payment to an existing biller | Create Bill Payment | | Cancel an existing bill payment, if possible | Cancel Bill Payment | | Retrieve a list of payments that have a process date that is equal to or later than the current date | Get Scheduled Bill Payments | | Retrieve a list of bill payments between specified dates | Get Bill Payment History | - 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`).

{/* billpay-add-biller.png */} 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. (SoFi Tech Solutions recommends passing the `billerState` parameter to help distinguish between billers with the same name.) - If the biller is in the database: 1. SoFi Tech Solutions 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](#scheduling-billpay-transactions) or create a one-time transaction. 4. The endpoint response includes the `biller_id`. - If the biller is not in the database: 1. SoFi Tech Solutions 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](#scheduling-billpay-transactions) 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](#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](#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 SoFi Tech Solutions processes one-time transactions that are initiated by the Program API. This workflow assumes that SoFi Tech Solutions 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.png */} 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](#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](#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](#balance-checks-and-ledger-adjustment) for more information on balance-check timing. 4. SoFi Tech Solutions 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, SoFi Tech Solutions' billpay process runs. The process performs these checks again: 1. The account must be active. If it is not, SoFi Tech Solutions sends the `BSPF: sched_billpay_fail` event message. 2. There must be sufficient funds. If not, SoFi Tech Solutions sends the `BSPF: sched_billpay_fail` event message. See [Balance checks and ledger adjustment](#balance-checks-and-ledger-adjustment) for more information on balance-check timing. 3. Velocity limits must not be exceeded. If they are, SoFi Tech Solutions 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](#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](#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](#processing-an-electronic-transaction) for next steps. - `status: W` — Paper biller. See [Processing a paper billpay transaction](#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.

{/* billpay-create-scheduled-payment.png */} 1. On the process date for the transaction, the scheduler initiates the billpay transaction process. The scheduler begins to run every morning. 2. SoFi Tech Solutions creates the transaction in `status: N` and sends the `BPCQ: billpay_request_made` event message. 3. SoFi Tech Solutions verifies that the account holder's account is active. If it is not, SoFi Tech Solutions sends the `BSPF: sched_billpay_fail` event message. 4. SoFi Tech Solutions verifies that the transaction amount does not exceed the limit in LIMBP. If it does, SoFi Tech Solutions sends the `BLVF: billpay_limit_violation` event message. 5. SoFi Tech Solutions checks for sufficient funds. - If there are insufficient funds, SoFi Tech Solutions sends the `BSPF: sched_billpay_fail` event message. See [Balance checks and ledger adjustment](#balance-checks-and-ledger-adjustment) for more information on balance-check timing. 6. SoFi Tech Solutions adjusts the transaction amount from the account and sends the `BPAY: billpay` event message. See [Balance checks and ledger adjustment](#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](#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](#processing-an-electronic-transaction) for next steps. - `status: W` — Paper biller. See [Processing a paper billpay transaction](#processing-a-paper-billpay-transaction) for next steps. ## Balance checks and ledger adjustment This section details the timing of when SoFi Tech Solutions 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, SoFi Tech Solutions 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, SoFi Tech Solutions 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](#processing-an-electronic-transaction) - [Check](#processing-a-paper-billpay-transaction) ### Processing an electronic transaction On the same day that the electronic transaction is initiated, SoFi Tech Solutions performs these actions:

{/* billpay-create-RPPS-payment.png */} 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, our system time, 365 days per year. 2. SoFi Tech Solutions 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 SoFi Tech Solutions in an [RPPS return file](#rpps-return-file). SoFi Tech Solutions sends the `BRRJ: billpay_rejected` event message. 4. The transaction is posted to the biller’s bank account. SoFi Tech Solutions 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 SoFi Tech Solutions. It can take several days or longer for a transaction to be included in the return file. #### RPPS return file SoFi Tech Solutions checks for RPPS return files four times per day, at 06:10, 14:10, 18:10, and 22:10 our system time. When SoFi Tech Solutions finds a return file, it processes it right away. About 30 minutes after processing the file: 1. SoFi Tech Solutions 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 SoFi Tech Solutions 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. | Status change | Approximate interval | | :-----------: | -------------------------------------------------------------------- | | `N` to `O` | Up to 30 minutes. Process runs at :08 and :38 minutes past the hour. | | `O` to `P` | Process runs at 06:45, 14:45, 18:45 and 22:45 every day. | ### Processing a paper billpay transaction Within 2–3 days after a paper transaction is initiated, SoFi Tech Solutions performs these actions:

{/* billpay-create-paper-payment.png */} 1. Transactions in `status: W` (waiting to be printed) are picked up by SoFi Tech Solutions' paper check process once per business day at 06:00, our system time. Check transactions that are initiated before midnight are included in this batch. Transactions initiated after midnight are processed within 2–3 business days. 2. A vendor prints the check on behalf of SoFi Tech Solutions. 3. On the same day, the vendor sends the check in the mail on behalf of SoFi Tech Solutions. SoFi Tech Solutions 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, SoFi Tech Solutions sends the `BPCR: billpay_request_returned` event message. - SoFi Tech Solutions 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, SoFi Tech Solutions 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. SoFi Tech Solutions sends the `BPEX: billpay_expired` event message and changes the transaction to `status: L`. 2. SoFi Tech Solutions records the check in the cancellation file and changes the transaction to the temporary `status: U`. 3. SoFi Tech Solutions 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

{/* billpay-check-example-2025-annotated-02.png */} 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 name and 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 SoFi Tech Solutions typically prints and mails a paper check within 2–3 business days after the transaction was initiated. During this interval, the funds are moving from your account to the bank that issues the checks. The biller receives the check depending on post office handling. SoFi Tech Solutions 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, SoFi Tech Solutions voids the check and returns the amount to the account. A check can be returned to SoFi Tech Solutions 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. (SoFi Tech Solutions cannot tell you why the bank returned a check; you must ask the bank for that information.) When SoFi Tech Solutions 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 SoFi Tech Solutions prints and mails checks as well as how fast returned and expired checks are processed. | Status change | Approximate interval | | :-----------: | -------------------------------------------------- | | `N` to `W` | Process runs at :08 and :38 minutes past the hour. | | `W` to `Q` | 2–3 business days | | `Q` to `P` | Same business day as above | | `P` to `C` | \~10 days minimum. Up to 180 days. | ### 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.

{/* billpay-fee.png */} 1. After the billpay process posts the adjustment to the account, SoFi Tech Solutions checks for any billpay fees. - If there are no fees, SoFi Tech Solutions does not follow the fee process and skips to step 3. - If a fee is configured, SoFi Tech Solutions 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, SoFi Tech Solutions checks the AAIGB parameter. - **Set** — When the fee is removed from the account, it drives the balance negative. - **Not set** — SoFi Tech Solutions checks the BPPPF parameter. - **Set** — The fee is deferred until there are sufficient funds in the account. - **Not set** — SoFi Tech Solutions rolls back both the fee and the billpay adjustment and sends the `BSPF: sched_billpay_fail` event message. 2. SoFi Tech Solutions 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](#processing-an-electronic-transaction) for next steps. - `status: W` — Paper biller. See [Processing a paper billpay transaction](#processing-a-paper-billpay-transaction) for next steps.