Switch between processing models

This guide covers moving a company between Peach-managed processing, Bring Your Own Bank (BYOB) processing and external processing. For each direction, it states what changes, who can make each change, and what happens to your borrowers' payment instruments, autopay plans, payments already in progress and investor settlement. It is for the integration engineer and the operations lead at a lender that is moving. Peach makes every change to your company's configuration, so agree with Peach which move applies to your company before you begin.

This guide does not cover setting up each model. For that, see Set up Peach-managed payment processing, Set up Bring Your Own Bank (BYOB) processing and Set up external payment processing.

• Peach has agreed to the move with you. Peach makes every change to your company's configuration; you can't make these changes yourself.
• An API key with the permissions for the steps you perform in your direction:

• Two different isExternal fields — Required to tell the instrument setting from the processor setting in every direction.
• Set up autopay — How an autopay plan and its agreement document fit together.
• How settlement works — How collected payments become investor settlements.

• config.payment.processedByPeach — The company setting that says Peach processes your payments: true under Peach-managed and BYOB processing, false under external processing. Only Peach can change it. See Set up external payment processing.
• config.payment.disablePaymentProcessing — A separate company setting. When true, Peach cancels your Peach-processed scheduled payments on their scheduled date, cancels Peach-processed ACH payments in initiated when it next builds an ACH file while processedByPeach is still true, refuses new payments that aren't external with 402, creates new payment instruments as external, creates no autopay payments, and sends no micro-deposits. A request that sends isExternal: true still needs payment.instrument:external, and returns 403 without it. A bank account linked through Plaid is the exception to the instrument rule: Peach currently doesn't create it as external, and accepts it, because processedByPeach is still true. Peach currently refuses a Plaid-linked account only when processedByPeach is false; see Set up external payment processing. Peach-processed ACH payments already in pending still move to succeeded, and investor settlement continues. It defaults to false.
• config.payment.scheduleAutopayTransactions — When processedByPeach is false, true means Peach creates scheduled payments from your autopay plans. It defaults to false. See Handle autopay.
• Instrument isExternal — On a payment instrument, true means Peach records its payments but doesn't move the money. Each new payment takes the value from its instrument.
• Default ACH processor — Your active processor with isDefault: true receives your new ACH payments, unless the loan type names its own ACH processor. With neither, Peach's own processor does. See Step 3 of the BYOB guide.

Each direction in the following sections lists the changes the move needs and who can make each one. The changes are grouped by what they affect. They are not an order of steps: Peach sets the date and the order of its own steps for each move.

Two facts apply to every direction. Peach performs every change to company configuration. And Peach sets a payment's processor and its isExternal value when the payment is created, and a later change doesn't alter either. A change can still affect payments already in progress. When Peach sets processedByPeach to false, it stops filing Peach-processed ACH payments in initiated, stops charging card payments, and stops settling collected payments that are not yet settled; they are not settled automatically. Disabling payment processing cancels existing Peach-processed scheduled payments, and deactivating your own processor stops the filing of its payments in initiated. It also stops Peach from reading your bank's confirmation and return files for that processor, unless another active processor uses the same SFTP host, username, inbox folder and file-name pattern.

Peach performs this step. Peach sets processedByPeach to false for your company. From then on, Peach creates a new payment instrument as external when the request leaves isExternal out or sends false, and returns no error. A request that sends isExternal: true still needs payment.instrument:external, and returns 403 without it. A bank account linked through Plaid is currently refused; see Set up external payment processing.

After this step, a new instrument created without isExternal comes back with isExternal: true.

Each instrument is converted one at a time, by your integration or by Peach; agree with Peach who does it. Nothing converts your existing instruments automatically. Each one keeps isExternal: false until it is updated, and every payment created on it is a Peach-processed payment.

To convert one, send isExternal: true in PUT /api/people/{personId}/payment-instruments/{paymentInstrumentId}. The key needs payment.instrument:external. The API reference doesn't list isExternal among the fields this request accepts, but Peach applies it. A Peach user can make the same request.

PUT /api/people/{personId}/payment-instruments/{paymentInstrumentId}
Content-Type: application/json
X-API-KEY: <YOUR-API-KEY>

{
  "isExternal": true
}

Sending the same value again changes nothing more. Payments already created on the instrument keep their isExternal value; only payments created afterward are external. The response shows isExternal: true.

An autopay plan creates its payments from its payment instrument, so a plan on a converted instrument creates external payments. To move a plan to a different instrument, send the new paymentInstrumentId in PUT /api/people/{personId}/loans/{loanId}/autopay. The instrument must be active. For an external instrument, the request doesn't need agreementDocumentId.

After the move, Peach creates scheduled payments from your autopay plans only if Peach sets scheduleAutopayTransactions to true for your company. With the default false, you create them yourself, as in Handle autopay. If Peach disables payment processing, it creates no autopay payments at all.

If Peach sets scheduleAutopayTransactions to true, an autopay plan still on an instrument that hasn't been converted creates Peach-processed payments, which get stuck as described in What happens to payments already in progress. With the default false, Peach creates no payments from that plan.

What happens depends on which setting Peach changes.

If Peach only turns off Peach-managed processing, nothing is canceled or converted:

• A Peach-processed payment in scheduled still moves to initiated on its date. A payment in initiated counts as applied to the loan.
• Peach never files a Peach-processed ACH payment in initiated, because ACH files are built only for companies that Peach processes for. Card processing skips these companies too, so a card payment in initiated is never charged. These payments stay in initiated.
• A Peach-processed ACH payment already in pending still moves to succeeded.
• A new Peach-processed payment created after the switch gets no processor.

If Peach disables payment processing instead (disablePaymentProcessing), Peach cancels your Peach-processed payments in scheduled on their scheduled date. It also cancels any Peach-processed ACH payment in initiated when it next builds an ACH file. External scheduled payments are not canceled. Peach creates no autopay payments while processing is disabled.

Peach does no investor settlement for external payments, and its daily settlement run skips companies that Peach doesn't process payments for. After the switch:

• Collected payments not yet rolled into a settlement are not settled to investors automatically.
• A payment that was pending at the switch and succeeds later is not settled automatically either.
• Settlements already waiting to be funded still fund and are filed.

From the switch, you process your borrowers' payments and report each status to Peach. Peach sends payment.due.today for each external payment in scheduled on its date, and keeps sending borrower notices for the statuses you report. Follow Steps 2 to 8 of Set up external payment processing.

You can also update the status of any payment, including payments Peach created. While Peach processed your payments, only Peach could update a Peach-processed payment.

Every change in Peach-managed to external applies. Peach sets processedByPeach to false, your instruments and autopay plans need converting, and investor settlement stops in the same way.

Your own processor's payments are affected too. Peach builds ACH files only for companies it processes for, so once the setting is off, Peach files nothing for your processor. Its payments in initiated stay there, and its payments in pending still move to succeeded.

Keep your processor active until its payments in pending have succeeded, its settlements waiting to be funded have funded, and your bank's return window for its payments and settlement payouts has passed. Peach funds settlements only through active settlement-required processors. While a processor is inactive, Peach doesn't read its confirmation or return files, unless another active processor uses the same SFTP host, username, inbox folder and file-name pattern. Until the files are read, returns on its payments and settlement payouts aren't recorded, and if the processor receives confirmation files, its payments in pending don't move to succeeded.

Peach performs this step. Peach sets processedByPeach to true for your company. From then on, a new instrument is Peach-processed unless the request sends isExternal: true. Peach validates the routing number of each new Peach-processed bank account, and sends micro-deposits to verify it when your company has micro-deposit verification turned on.

An instrument created before this step is external, because Peach can't create a Peach-processed instrument for a company it doesn't process for.

After this step, a new instrument created without isExternal comes back with isExternal: false.

Your existing external instruments stay external, and their payments stay record-only. Peach can't process a payment from an external bank account that holds only the last digits of the account number. When an external bank account is created, the last two to four digits are enough, and no request can change an account number afterward.

Add each borrower's bank account again as a new, Peach-processed instrument with the full account number, as in Step 1 of the Peach-managed guide. Either your integration or the borrower can add it; your integration can do so only if it holds the full account number. A new Peach-processed bank account is unverified until micro-deposits verify it, or until a key with payment.instrument:skip.verification sets verified: true.

Once an instrument is Peach-processed, your key can change its status only from active to inactive. Only Peach can make the other status changes.

Move each autopay plan to the borrower's new instrument with PUT /api/people/{personId}/loans/{loanId}/autopay. For a Peach-processed instrument, the request needs agreementDocumentId for an accepted autopay agreement on the loan, or it returns 400. See Step 2 of the autopay guide.

Once Peach processes your payments, it creates the scheduled payments from your autopay plans.

Payments already created on external instruments stay external.

From the switch, Peach's daily settlement run includes your company again. See How settlement works.

Every change in External to Peach-managed applies: Peach sets processedByPeach to true, your integration or your borrowers add the borrowers' bank accounts again, and you point autopay at the new instruments.

You also set up your own bank's processor and make it your only active default, as in Steps 2 and 3 of Set up Bring Your Own Bank (BYOB) processing, and complete Steps 4 to 6 (investors, settlement instruments, and ownership dated on or before your payments), and have Peach complete Step 7 (the funding instrument), before you expect settlements. Until it is active and the default, your new ACH payments go to Peach's own processor.

Before you rely on your processor, have Peach check your loan types, as in Peach-managed to BYOB.

Your company stays processed by Peach, so your instruments and autopay plans don't change.

You set up your own bank's processor and make it your only active default, as in Steps 2 and 3 of Set up Bring Your Own Bank (BYOB) processing, and complete Steps 4 to 6 (investors, settlement instruments, and ownership dated on or before your payments), and have Peach complete Step 7 (the funding instrument), before you expect settlements. New ACH payments go to it from the time they are created. Payments created earlier keep Peach's processor.

While payments created before and after the move are still clearing, a day's settlement build can create two settlements for an investor: one for payments on Peach's processor and one for payments on yours. Each is funded separately, through its own processor.

A loan type can name its own ACH processor, which takes precedence over your default processor for that loan type's ACH payments. No API request can set or clear it. Ask Peach to check your loan types before you switch. A loan type that names a processor keeps routing its ACH payments there.

Your processor handles ACH only. Card payments are unaffected by the switch.

Your processor settles to your investors only if you created it settlement-required. See Set up Bring Your Own Bank (BYOB) processing and How settlement works.

Settlements on your processor fund only once Peach has created your funding instrument; see Step 7 of the BYOB guide.

As in Peach-managed to BYOB, your instruments and autopay plans don't change. You perform these steps on your own processor. The code allows this safe order:

1. Make your processor non-default with PUT /api/payment-processors/{paymentProcessorId}. New ACH payments then go to Peach's own processor, unless a loan type names your processor. isDefault plays no part in filing, settlement or funding.
2. Keep the processor active until its payments in initiated have been filed, its payments in pending have succeeded, its settlements waiting to be funded have funded, and your bank's return window for its payments and settlement payouts has passed. Peach files ACH only for an active processor, and funds settlements only through active settlement-required processors. While a processor is inactive, Peach doesn't read its confirmation or return files, unless another active processor uses the same SFTP host, username, inbox folder and file-name pattern. Until the files are read, returns on its payments and settlement payouts aren't recorded, and if the processor receives confirmation files, its payments in pending don't move to succeeded.
3. Then deactivate it with DELETE /api/payment-processors/{paymentProcessorId}. Deleting a processor marks it deprecated; it doesn't remove it.

PUT /api/payment-processors/{paymentProcessorId}
Content-Type: application/json
X-API-KEY: <YOUR-API-KEY>

{
  "isDefault": false
}

Ask Peach to check that none of your loan types names your processor. A loan type that does keeps routing its ACH payments to it.

The move takes effect when Peach changes your company's processing setting, for a move to or from external processing. Between Peach-managed and BYOB, it takes effect when your default processor changes. Each payment keeps the processor and isExternal value it was created with. Turning off Peach-managed processing still affects payments already in progress: Peach no longer files Peach-processed ACH payments in initiated or charges card payments, and collected payments not yet settled are not settled automatically. See What happens to payments already in progress and What happens to investor settlement.

• Create a payment instrument without isExternal. After a move to external processing, the response shows isExternal: true. After a move to Peach-managed or BYOB processing, it shows isExternal: false.
• Check your loans for payments still in initiated.
• After a move to BYOB processing, confirm that your bank received a file from Peach for your processor after the first ACH build that includes payments on it. A build with nothing to file sends no file. If you subscribe to the ACH file events, ach.file.created fires for your processor at every build, including one that sends no file, and ach.file.upload.succeeded fires when a file is uploaded to your bank's SFTP server.

• Known limitation: after Peach sets processedByPeach to false, Peach-processed payments in scheduled move to initiated on their date, and a payment in initiated is applied to the loan but never collected. See What happens to payments already in progress.
• Known limitation: collected payments not yet in an investor settlement when Peach stops processing your payments are not settled automatically. See What happens to investor settlement.
• Known limitation: no request can change a bank account's account number. An external account created with only the last digits can't become Peach-processed.
• Known limitation: the API reference doesn't list isExternal as a field of the instrument update request, although Peach applies it.
• Known limitation: you can't see or change a loan type's own ACH processor; no API request or portal screen shows or sets it. Ask Peach to check it.
• Known limitation: a processor's isExternal and isSettlementRequired are set when it's created and can't be changed later. See Set up Bring Your Own Bank (BYOB) processing.
• Known limitation: no request can move an existing payment, including a scheduled one, to a different processor.

Only Peach can reverse a change to your company's processing settings.

An instrument converted to external keeps the account number it was created with. To reverse a conversion, send isExternal: false in the same update request. This needs no extra permission.

After a move to external processing, you can update payments stuck in initiated yourself, as in Take over payment processing. Agree with Peach how to resolve them before you change them.

Peach hasn't turned on Peach-managed processing yet, or has disabled payment processing. Ask Peach to check your company's settings.

Peach still processes your payments, and the payment isn't external. Only Peach can update it until Peach sets processedByPeach to false.

The new instrument is Peach-processed. Send the ID of the borrower's accepted autopay agreement.

Your processor isn't active and the default, or a loan type names another processor. Make it your only active default, and ask Peach to check your loan types.

• Set up external payment processing — The steps you take once your own processor handles payments.
• Set up Bring Your Own Bank (BYOB) processing — Setting up your own bank's processor and investor settlement.
• How settlement works — How collected payments become investor settlements.