# Bring Your Own Bank (BYOB) Implementation ## Overview This guide walks you through implementing Peach's "Bring Your Own Bank" (BYOB) payment processing option. You'll learn how to configure and manage payment processing using your existing banking relationships while leveraging Peach's loan servicing capabilities. This process requires minimal engineering resources from your team, as Peach handles the technical integration with your bank. ## Key Benefits The BYOB payment processing option offers several advantages: 1. **Control Over Banking Relationships**: Maintain your existing banking partnerships and preferred terms. 2. **Direct Fund Flow**: Your bank processes ACH transactions and deposits funds directly into your account without Peach handling the money. 3. **Simplified Implementation**: Requires minimal engineering resources from your team, with Peach handling the technical aspects of NACHA file generation and processing. 4. **Borrower Experience**: Preserves the same borrower-facing experience in the Peach borrower portal. 5. **Automated Updates**: Peach automatically processes return files from your bank and updates relevant loan statuses accordingly. 6. **Borrower Experience**: The borrower experience remains unchanged with this option. Borrowers continue to use the same Peach borrower portal to set up payment methods and make payments. ## Implementation Checklist To successfully implement BYOB payment processing: * [ ] Partner with a bank that supports ACH processing * [ ] Gather all required bank processing details including routing numbers, account numbers, and file header information * [ ] Provide SFTP access details to Peach * [ ] Work with Peach to test NACHA file transfers * [ ] Verify your bank has whitelisted Peach's IP addresses * [ ] Test the full payment flow in Peach's sandbox environment * [ ] Move to production after successful testing ## Payment Processing Flow When using the BYOB option, the payment processing flow follows these steps: 1. **Borrower Initiates Payment**: A borrower sets up a one-time payment or autopay in the Peach borrower portal. 2. **NACHA File Generation**: Peach generates a NACHA file containing the payment information. 3. **File Transfer**: Peach uploads the NACHA file to your bank's SFTP server. 4. **Bank Processing**: Your bank processes the ACH transactions and funds your account directly. 5. **Return Processing**: Your bank sends return files back to Peach via SFTP if any payments fail. 6. **Ledger Updates**: Peach processes the return files and updates the loan ledger accordingly. 7. **Loan Updates**: Peach processes the return files and updates relevant loan data accordingly. The entire process is automated, requiring no manual intervention during normal operations. If issues arise, both you and Peach receive notifications for resolution. ## Prerequisites Before implementing BYOB payment processing, you'll need: * A Peach account with API access * Your API credentials * An existing banking relationship for ACH processing * SFTP access to your bank's system * Basic familiarity with NACHA file formats **Important Note**: The BYOB option is currently available for ACH payments only and does not support card processing. ## API Implementation While your Peach solutions architect will help configure many aspects of the BYOB setup, you'll need to interact with several key API endpoints to complete the implementation. Follow the steps below to configure the APIs. ### 1. Create Payment Processor Configure your payment processor details using the Create Payment Processor endpoint. The following example creates a draft payment processor that can handle ACH payments. ``` POST /api/payment-processors Content-Type: application/json X-API-KEY: { "processorName": "ACH Direct Processor", "processorType": "achDirectUS", "status": "draft", "paymentTypes": [ "ach" ], "timezone": "America/Los_Angeles", "isDefault": false, "achCutoff": "16:00:00", "achSameDayCutoff": "10:30:00", "achFileHeaderImmediateDestination": "123456789", "achFileHeaderImmediateOrigin": "987654321", "achFileHeaderImmediateDestinationName": "RECEIVING BANK", "achFileHeaderImmediateOriginName": "ORIGINATING COMPANY", "achBatchHeaderCompanyName": "ACME LENDING", "achBatchHeaderCompanyId": "1234567890", "achBatchHeaderOriginatingDFIId": "12345678", "achFeeType": "net", "achFeeAmount": 0.25, "achSameDayFeeAmount": 1.50, "achSECCode": "PPD", "sftpAccessMethod": "usernamePassword", "sftpHostname": "test.rebex.net", "sftpUsername": "demo", "sftpPassword": "password", "sftpAchConfirmationFileNameRegex": "ACH_CONF_\\d{8}\\.txt", "sftpAchReturnFileNameRegex": "ACH_RETURN_\\d{8}\\.txt", "isFileNameDefaultConvention": true, "signOutgoing": false, "externalId": "PROC-ACH-001" } ``` This endpoint establishes the connection between Peach and your bank's ACH processing system. The processorType value of "achDirectUS" indicates you're using your own bank for ACH processing. ``` { "status": 200, "data": { "createdAt": "2025-03-05T20:49:27.619038+00:00", "updatedAt": "2025-03-05T20:49:27.619047+00:00", "deletedAt": null, "id": "PP-G2K6-VB45", "object": "paymentProcessor", "externalId": "PROC-ACH-001", "companyId": "CP-L9BN-5J52", "paymentTypes": [ "ach" ], "processorType": "achDirectUS", "processorName": "ACH Direct Processor", "status": "draft", "isDefault": false, "isSettlementRequired": false, "isFileNameDefaultConvention": true, "signOutgoing": false, "sftpAccessMethod": "usernamePassword", "timezone": "America/Los_Angeles", "achFileHeaderImmediateDestination": "123456789", "achFileHeaderImmediateDestinationName": "RECEIVING BANK", "achFileHeaderImmediateOrigin": "987654321", "achFileHeaderImmediateOriginName": "ORIGINATING COMPANY", "achBatchHeaderCompanyName": "ACME LENDING", "achBatchHeaderCompanyId": "1234567890", "achBatchHeaderSettlementCompanyId": null, "achBatchHeaderOriginatingDFIId": "12345678", "achCutoff": "16:00:00", "achSameDayCutoff": "10:30:00", "achFeeType": "net", "achFeeAmount": 0.25, "achSameDayFeeAmount": 1.5, "sftpHostname": "test.rebex.net", "sftpUsername": "demo", "sftpPassword": "cv4bhluj8mqs73bpp30g", "sftpCdDirInbox": null, "sftpCdDirOutbox": null, "sftpAchConfirmationFileNameRegex": "ACH_CONF_\\d{8}\\.txt", "sftpAchReturnFileNameRegex": "ACH_RETURN_\\d{8}\\.txt", "encryptionMethodOutgoing": null, "encryptionMethodIncoming": null, "peachPublicKey": null, "peachPrivateKey": null, "thirdPartyPublicKey": null, "sftpSSHPeachPublicKey": null, "sftpSSHPeachPrivateKey": null, "sftpSSHDisabledAlgorithms": null, "achSECCode": "PPD", "confirmFileUpload": true, "isDebugLogging": false, "fundingInstruments": [] } } ``` ### 2. Create and Manage Payment Instruments Allow borrowers to add their bank accounts through the borrower portal, or create them via API: ``` POST /api/people/{personId}/payment-instruments Content-Type: application/json X-API-KEY: { "accountHolderName": "John Doe", "accountHolderType": "personal", "accountNumber": "4995672067", "accountType": "savings", "instrumentType": "bankAccount", "routingNumber": "123456789", "createdAt": "2023-01-01T00:00:00Z", "updatedAt": "2023-01-01T00:00:00Z", "deletedAt": null, "isExternal": false, "pendingAt": null, "externalId": "ext-123", "status": "pending", "inactiveReason": "updated", "verified": false, "nickname": "My Savings", "institutionName": "Example Bank", "sendNotice": true } ``` To retrieve payment instrument details: ``` GET /api/people/{personId}/payment-instruments/{paymentInstrumentId} X-API-KEY: ``` ### 4. Setting Up Recurring Payments (Optional) The following is an example **Create Autopay** request that schedules recurring weekly payments for Fridays using the bank account associated with paymentInstrumentId. Since `isAlignedToDueDates` is set to `true`, these payments will process on the loan's regular due dates. The request configures: * Payment frequency: Monthly payments * Processing day: Every Friday * Payment method: Bank account referenced by `paymentInstrumentId` * Notifications: Sends confirmation to borrower (sendNotice: true) ### Request ``` POST /api/people/{personId}/loans/{loanId}/autopay Content-Type: application/json X-API-KEY: { "paymentInstrumentId": "PT-OB5R-M8QJ", "previewMode": true, "isAlignedToDueDates": true, "paymentFrequency": "monthly", "sendNotice": true } ``` ### 5. Monitor Transaction Status Retrieve transaction details to monitor status: ``` GET /api/people/{personId}/loans/{loanId}/transactions/{transactionId} X-API-KEY: ``` ### 6. Set Up Webhooks for Real-Time Updates Configure webhooks to receive payment status notifications: ``` POST /api/webhooks Content-Type: application/json X-API-KEY: { "webhookType": "direct", "eventTypes": [ "payment.initiated", "payment.succeeded" ], "enabled": true, "hydrateData": false, "webhookDirectDetails": { "webhookUrl": "https://api.example.com/webhooks/peach-finance " } } ``` ## Next steps - **[External Processing](/payments/external-processing)** — Compare BYOB to fully external processing where you control settlement. - **[Payment Processing Overview](/payments)** — Index of payment processing options and concepts.