{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":[]},"type":"markdown"},"seo":{"title":"Payment Instrument Setup","siteUrl":"https://docs.peachfinance.com","description":"API and product documentation for Peach Finance, a lending-as-a-service platform.","llmstxt":{"hide":false,"sections":[{"title":"Table of contents","includeFiles":["**/*"],"excludeFiles":[]}],"excludeFiles":[]}},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"payment-instrument-setup","__idx":0},"children":["Payment Instrument Setup"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["This guide walks you through setting up payment instruments. We'll continue working with James Smith to add a bank account and debit card for loan payments."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"overview","__idx":1},"children":["Overview"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["A payment instrument represents any method a borrower can use to make payments:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Bank accounts (ACH)"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Debit cards"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Credit cards"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["You can add multiple payment instruments and designate them for different purposes like autopay or one-time payments."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"prerequisites","__idx":2},"children":["Prerequisites"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Before you begin, make sure you have:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["A Peach account with API access"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Your API key"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["borrower ID:"]}]},{"$$mdtype":"Tag","name":"blockquote","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Note"]},": The following examples use commonly used fields, but for full details, including additional data and parameters, refer to the ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"/api-docs/api-public"},"children":["API Reference"]},"."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"check-existing-payment-instruments","__idx":3},"children":["Check Existing Payment Instruments"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Let's first see what payment methods James already has:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"http","header":{"controls":{"copy":{}}},"source":"GET /people/{personId}/payment-instruments\nX-API-KEY: <YOUR-API-KEY>\n","lang":"http"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"adding-a-bank-account","__idx":4},"children":["Adding a Bank Account"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Now let's add James' checking account for automatic payments:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"http","header":{"controls":{"copy":{}}},"source":"POST /people/{personId}/payment-instruments\nX-API-KEY: <YOUR-API-KEY>\nContent-Type: application/json\n\n{\n  \"instrumentType\": \"bankAccount\",\n  \"accountType\": \"checking\",\n  \"accountHolderType\": \"personal\",\n  \"accountHolderName\": \"James Smith\",\n  \"accountNumber\": \"123456789\",\n  \"routingNumber\": \"021313103\",\n  \"nickname\": \"Primary Checking\",\n  \"status\": \"pending\",\n  \"verified\": false\n}\n","lang":"http"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"verify-bank-account-with-microdeposits","__idx":5},"children":["Verify Bank Account with Microdeposits"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["After creating the bank account, Peach will initiate two small deposits to verify account ownership. Once James sees these deposits, we can verify the account:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"http","header":{"controls":{"copy":{}}},"source":"POST /people/{personId}/payment-instruments/{instrumentId}/verify\nX-API-KEY: <YOUR-API-KEY>\nContent-Type: application/json\n\n{\n  \"deposit1\": 32,\n  \"deposit2\": 45\n}\n","lang":"http"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["If successful, the account's ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["verified"]}," status will change to ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["true"]},"."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"adding-a-debit-card","__idx":6},"children":["Adding a Debit Card"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Let's also add James' debit card as a backup payment method:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"http","header":{"controls":{"copy":{}}},"source":"POST /people/{personId}/payment-instruments\nX-API-KEY: <YOUR-API-KEY>\nContent-Type: application/json\n\n{\n  \"instrumentType\": \"card\",\n  \"cardType\": \"debit\",\n  \"accountHolderName\": \"James Smith\",\n  \"cardNumber\": \"4111111111111111\",\n  \"expirationMonth\": 12,\n  \"expirationYear\": 2025,\n  \"cvv\": \"123\",\n  \"nickname\": \"Personal Debit\",\n  \"status\": \"pending\",\n  \"address\": {\n    \"addressLine1\": \"1 Main St\",\n    \"city\": \"Houston\",\n    \"state\": \"TX\",\n    \"postalCode\": \"77002\",\n    \"country\": \"US\"\n  }\n}\n","lang":"http"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"payment-instrument-states","__idx":7},"children":["Payment Instrument States"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Each payment instrument has a status that indicates its usability:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["pending"]}," - Initial state after creation"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["active"]}," - Ready for use in payments"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["inactive"]}," - Temporarily unavailable"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["failed"]}," - Failed verification or validation"]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"verification-methods","__idx":8},"children":["Verification Methods"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Different payment types have different verification requirements:"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"bank-accounts","__idx":9},"children":["Bank Accounts"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Microdeposit verification (2-3 business days)"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Plaid instant verification (if configured)"]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"cards","__idx":10},"children":["Cards"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Address verification (AVS)"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Card verification value (CVV)"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Test authorization"]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"managing-payment-instruments","__idx":11},"children":["Managing Payment Instruments"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"update-payment-details","__idx":12},"children":["Update Payment Details"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["If James's card expires, we can update it:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"http","header":{"controls":{"copy":{}}},"source":"PUT /people/{personId}/payment-instruments/{instrumentId}\nX-API-KEY: <YOUR-API-KEY>\nContent-Type: application/json\n\n{\n  \"expirationMonth\": 12,\n  \"expirationYear\": 2026,\n  \"status\": \"active\"\n}\n","lang":"http"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"delete-payment-method","__idx":13},"children":["Delete Payment Method"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["To remove an outdated payment instrument:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"http","header":{"controls":{"copy":{}}},"source":"DELETE /people/{personId}/payment-instruments/{instrumentId}\nX-API-KEY: <YOUR-API-KEY>\n","lang":"http"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"see-also","__idx":14},"children":["See also"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/borrowers/quickstart"},"children":["Borrower Quickstart"]}]}," — Walks through creating a borrower and attaching their first contact and payment details."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/borrowers"},"children":["Borrowers overview"]}]}," — Index of borrower-related entities and operations."]}]}]},"headings":[{"value":"Payment Instrument Setup","id":"payment-instrument-setup","depth":1},{"value":"Overview","id":"overview","depth":2},{"value":"Prerequisites","id":"prerequisites","depth":2},{"value":"Check Existing Payment Instruments","id":"check-existing-payment-instruments","depth":2},{"value":"Adding a Bank Account","id":"adding-a-bank-account","depth":2},{"value":"Verify Bank Account with Microdeposits","id":"verify-bank-account-with-microdeposits","depth":3},{"value":"Adding a Debit Card","id":"adding-a-debit-card","depth":2},{"value":"Payment Instrument States","id":"payment-instrument-states","depth":2},{"value":"Verification Methods","id":"verification-methods","depth":2},{"value":"Bank Accounts","id":"bank-accounts","depth":3},{"value":"Cards","id":"cards","depth":3},{"value":"Managing Payment Instruments","id":"managing-payment-instruments","depth":2},{"value":"Update Payment Details","id":"update-payment-details","depth":3},{"value":"Delete Payment Method","id":"delete-payment-method","depth":3},{"value":"See also","id":"see-also","depth":2}],"frontmatter":{"seo":{"title":"Payment Instrument Setup"}},"lastModified":"2026-05-01T14:33:55.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/borrowers/payment-instruments","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}