
⏱ About a 5-minute read. Click “Read more” or “Sample file” whenever you want the details.
Sree sells handmade gifts online and gets paid through PayPal. The money shows up in the wallet straight away, but getting it into the bank account is a separate journey.
- Not a banker? Just look at the pictures and read the “In one line” boxes. That is enough to get the idea.
- Work in banking or operations? Open “Read more” under each file and each payment type.
- Product owner? Read the status codes, the “Status, rules, security and data” boxes and the product owner rows. Those are the decisions that land on your desk.
- Developer? Open every “Sample file”, then read the data mapping section and the developer rows.
- Operations or support? Use the runbook table: what to watch at each file, and who acts.
- Tester? Use the “What to test” rows as your starting checklist.
- Forward deployed engineer? Jump to “For forward deployed engineers”. It covers what to ask the client, set-up, testing, go-live and where things usually go wrong.
How PayPal and Venmo work
In one line: Inside their own system, PayPal and Venmo move money in seconds. Adding money or cashing out to a bank uses the ACH and card rails.
- Coming in: taps in the app or REST API calls (JSON). Businesses can also send bulk payouts by API or by uploading a file.
- Inside: moving money between two PayPal or Venmo balances is just an entry in PayPal’s own ledger. That is why it is instant.
- Out to banks: cash-outs go by ACH (a NACHA file, usually 1–3 business days), or instantly to a debit card for a fee. Top-ups pull money from a bank by ACH or from a card (ISO 8583).
- Coming back: webhooks with the status, disputes and chargebacks, and monthly activity statements.
Status, rules, security and data
| Status flow | Created → Funding checked → Completed (in wallet) → Withdrawn to bank → Settled Side paths: Pending (review), Reversed, Disputed / chargeback |
| Regulation and rules | PayPal is licensed as a money transmitter in US states. Regulation E applies to consumer accounts. Card funding follows the card network rules. Bank pulls and payouts follow the Nacha Operating Rules. OFAC and anti-money-laundering rules apply too. |
| Security standards | Strong login and device checks, two-step verification and real-time fraud scoring. PCI DSS for stored card data. Nacha’s data security rules for bank account numbers. |
| Data governance | Keep the wallet transaction ID, the funding source and the bank or card reference together, so a dispute can be traced from end to end. Mask card and account numbers. |
Read more: PayPal and Venmo
For tech teams, product owners and testers
| For developers | Use the REST APIs with OAuth tokens. Check webhook signatures. Store PayPal transaction IDs. Treat “completed in the wallet” and “settled to the bank” as two different statuses. |
| For product owners | Standard or instant cash-out (with a fee), limits, and how disputes are handled. Make it very clear that money in the wallet is not yet in the bank. |
| What to test | Bank funding that comes back (R01) after the wallet already showed the money. Card funding declined. Instant cash-out to a card that is not supported. A dispute after cash-out. A webhook delivered twice. |
Step by step
- Sree sends money in the PayPal or Venmo app. Or a business calls the PayPal REST API, for example to pay many sellers at once.
- PayPal checks the login, the device, the limits and any fraud signals. Then it picks where the money comes from: the PayPal balance, a linked bank account or a card.
- If the balance is used, PayPal moves the money between the two wallets in its own ledger. The payee sees it straight away.
- If a bank account pays, PayPal pulls the money by ACH (a NACHA debit). If a card pays, a card approval request (ISO 8583) goes to the bank that issued the card.
- When the payee cashes out, PayPal sends the money to their bank by ACH (usually 1–3 business days), or instantly to a debit card for a fee.
- The status comes back by webhook and in the app. ACH returns, card chargebacks and buyer disputes can reverse a payment later.
- PayPal checks its wallet ledger against the bank and card settlement reports. Users see everything in their activity statement.
When things go wrong: rejected, returned, cancelled
Not every payment goes through. On PayPal, there are three ways a payment can fail. Each one means something different for the money.
Rejected. PayPal can decline a payment before it moves: a fraud signal, a limit, or a funding source that doesn’t work (a declined card, for example). Nothing moves, and the app or API shows a message.
Returned. Money can come back later in several ways: the seller refunds the buyer, the buyer opens a dispute, the card issuer starts a chargeback, or the bank returns the ACH pull (for example R01, not enough money). PayPal reverses the ledger entry, which can leave a balance negative, and sends a webhook.
Cancelled. A payment can be cancelled only while it is unclaimed, for example when the receiver doesn’t have an account yet. Unclaimed payouts go back to the sender automatically after 30 days.
Codes you will see: Statuses: PENDING · COMPLETED · DECLINED · REFUNDED · REVERSED · UNCLAIMED · RETURNED
Which files carry the bad news?
Each path has its own file or message. Here is what travels, who sends it, and what is inside.
| Path | File or message | From → to | What it says |
|---|---|---|---|
| Rejected | API error + PAYMENT.CAPTURE.DENIED webhook | PayPal → merchant | Declined or failed |
| Returned | PAYMENT.CAPTURE.REFUNDED / REVERSED webhooks | PayPal → merchant | Refund done, or money pulled back |
| Returned | CUSTOMER.DISPUTE.CREATED webhook | PayPal → merchant | Buyer opened a dispute |
| Returned (bank leg) | NACHA return entry (for example R01) | Customer’s bank → PayPal’s bank | Bank funding failed |
| Cancelled | PAYMENT.PAYOUTS-ITEM.CANCELED / RETURNED | PayPal → sender | Unclaimed payout cancelled or sent back |
Sample file: PayPal webhooks
Fictional data, shortened. Real files carry more fields.
{
"id": "WH-7YX49823S2290830K-0JE13296W68552352",
"event_type": "PAYMENT.CAPTURE.REFUNDED",
"resource": {
"id": "1JU08902781691411",
"amount": { "value": "64.00", "currency_code": "USD" },
"status": "COMPLETED"
},
"create_time": "2026-11-21T09:30:00Z"
}
Other event types for the same flows:
PAYMENT.CAPTURE.DENIED declined / failed
PAYMENT.CAPTURE.REVERSED money pulled back (for example a chargeback)
CUSTOMER.DISPUTE.CREATED buyer opened a dispute
PAYMENT.PAYOUTS-ITEM.UNCLAIMED receiver has no account yet
PAYMENT.PAYOUTS-ITEM.RETURNED unclaimed for 30 days, sent back
PAYMENT.PAYOUTS-ITEM.CANCELED sender cancelledSample file: NACHA return entry (R03)
Fictional data, shortened. Real files carry more fields.
Record 6 = the original payment coming back (transaction code 21)
Record 7, type 99 = return addenda: reason R03, original trace number
6212223334459876543210 0000125050INV-7781 ACME SUPPLIES INC 1123456780000001
799R03222333440000001 12345678 123456780000001PayPal runbook: what to watch at each file
This is the day-to-day runbook for the files above, in the same order. For each step: the file you are looking at, what “good” looks like, what to do when it isn’t, and who acts. L1 is the service desk, L2 is payment operations and app support, and L3 is engineering.
| Step | File | Check | If it goes wrong | Who |
|---|---|---|---|---|
| 1. Create the order | REST API (Orders) | OAuth token valid, request ID set to avoid duplicates. | API errors climbing? Check PayPal status before changing code. | L2, L3 if it’s technical |
| 2. Capture | REST API (Captures) | Capture completed. | PAYMENT.CAPTURE.DENIED? Tell the buyer, don’t ship. | L2 |
| 3. Webhooks | Webhook events | Signature verified, each event processed once. | Webhooks failing? Fix the endpoint, then replay missed events. | L3 |
| 4. Payouts | Payouts API or batch file | Batch completed; unclaimed items followed up. | UNCLAIMED for 30 days? It returns to you. Tell the receiver. | L2 |
| 5. Refunds and disputes | REFUNDED, REVERSED, DISPUTE events | Every dispute answered before PayPal’s deadline. | Deadline close? Escalate with evidence. | L2 with disputes team |
| 6. Reconcile | PayPal settlement and activity reports | Wallet ledger matches bank and card settlement. | Break? Open an item and own it. | L2 with finance |
Golden rules
- “Completed in the wallet” is not “money in the bank”.
- Verify every webhook signature.
- Process each webhook event once, even if it arrives twice.
Want the full picture, from building it to running it live? Read the PayPal Integration Runbook.
For forward deployed engineers (FDE)
As an FDE, you sit with the client and make the integration actually work. Here is your checklist for this rail.
| First call with the client | Checkout, payouts to many sellers, or person to person? Which funding sources? Standard or instant cash-out? |
| Set up and connectivity | PayPal REST API credentials (sandbox and live), OAuth, the webhook URL and how it is verified, and payout limits. |
| Test and certify | Sandbox payments, refunds, disputes, payouts and webhook retries. A bank-funded payment that comes back later. |
| Go-live and hypercare | Start with small payout batches. Watch disputes and reversals. |
| Where it usually breaks | Treating “completed in the wallet” as “money in the bank”. Webhooks that are not verified, or not protected against duplicates. Disputes after the money was cashed out. |
The files on this rail
PayPal starts with APIs, but its bank and card legs use the same files as everyone else. For all the other files, see the full guide: how payment files are processed in US banks.
API (JSON): real-time requests
In one line: How apps and fintechs start payments one at a time, especially instant ones.
- How it starts: someone presses “Pay” in an app, or a platform calls the bank’s API.
- What is inside: JSON with the amount, the accounts, the payee and a reference. The headers carry the security token and an idempotency key (a unique ID that stops the same payment going twice).
- What happens next: the bank runs the same internal steps as for a file. It replies quickly, then sends a webhook later with the final status.
Sample file: API (JSON)
Made-up data, shortened. Real files have more fields.
POST /v1/payments
Authorization: Bearer <OAuth token>
Idempotency-Key: 6f1c2a90-7b1e-4d3a-9c55-7e0d9e5b1a11
Content-Type: application/json
{
"rail": "RTP",
"amount": { "value": "1250.50", "currency": "USD" },
"debtor_account": "1112223334",
"creditor": { "name": "Acme Supplies Inc.", "aba": "123456780", "account": "9876543210" },
"end_to_end_id": "INV-7781",
"remittance": "Invoice INV-7781"
}
HTTP/1.1 202 Accepted
{ "payment_id": "pmt_8KQ2", "status": "PENDING", "end_to_end_id": "INV-7781" }
Webhook a few seconds later:
{ "event": "payment.settled", "payment_id": "pmt_8KQ2", "status": "COMPLETED",
"network_reference": "8a562c67-ca16-48ba-b074-65581be6f001" }Read more: API (JSON)
For tech teams, product owners and testers
| For developers | Use OAuth 2.0 and mutual TLS. Require an Idempotency-Key so a retry never pays twice. Reply with 202 (accepted), then send the final result by a signed webhook. |
| For product owners | An API needs rate limits, a sandbox, versioning and clear error codes. Treat it as a product, not just a pipe. |
| What to test | The same Idempotency-Key sent twice. An expired token. A webhook that arrives twice or late. A timeout when the payment actually went through. |
NACHA file: the ACH format
In one line: A plain text file where every line is exactly 94 characters long. US ACH has used it for decades.
- How it starts: the company builds it in its payroll software, or the bank builds it from a pain.001, pain.008, CSV file or API call.
- What is inside: each line starts with a record type. 1 is the file header. 5 is the batch header (company, SEC code, date). 6 is one payment. 7 is an addenda with extra details. 8 is the batch total and 9 is the file total. At the end, lines of 9s fill the file up to a multiple of 10 lines.
- How it travels: from the company to the bank, then from the bank to FedACH or EPN at set times during the day.
Sample file: NACHA file
Made-up data. Every line is exactly 94 characters. The last line of 9s brings the file up to 10 lines (one block).
101 123456780 2223334452611191705A094101RECEIVING BANK SREE CORP BANK PAYROLL1
5220SREE CORP 1234567890CCDPAYMENT 261120261120 1222333440000001
6221234567809876543210 0000125050INV-7781 ACME SUPPLIES INC 1222333440000001
705INVOICE INV-7781 PAID IN FULL 00010000001
822000000200123456780000000000000000001250501234567890 222333440000001
9000001000001000000020012345678000000000000000000125050
9999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999Read more: NACHA file
For tech teams, product owners and testers
| For developers | Every field sits at a fixed position. The amount, in cents, is in positions 30–39. The receiving bank is in 4–11, with a check digit in 12. The account is in 13–29, the name in 55–76 and the trace number in 80–94. The entry hash is the sum of the 8-digit routing numbers, keeping only the last 10 digits. |
| For product owners | Decide whether clients can send you NACHA files directly. It is fast, but you must check them carefully. The alternative is to accept only pain.001 or API and build the NACHA file yourself. |
| What to test | A line with 93 or 95 characters. A wrong entry hash. Wrong totals in record 8 or 9. Lowercase letters. The wrong transaction code for savings versus checking (32 versus 22). Missing 9s at the end. |
ISO 8583: card messages
In one line: Very short messages that ask “can this card pay?” and get an answer in about a second.
- How it starts: the shopper taps or types in a card. The terminal or website sends a request through the merchant’s processor.
- What is inside: a message type (0100 is a request, 0110 the answer, 0400 a reversal) and numbered data elements. For example, DE2 is the card number, DE4 the amount and DE39 the response code.
- The money moves later, in daily clearing files such as Visa BASE II and Mastercard IPM.
Sample file: ISO 8583
Made-up data, shortened. Real files have more fields.
Authorization request MTI 0100
DE2 PAN (card number) 4111 **** **** 1111 (never stored in clear)
DE3 Processing code 000000 (purchase)
DE4 Amount 000000006400 ($64.00)
DE7 Transmission time 1120143522
DE11 Trace number (STAN) 004512
DE22 Entry mode 071 (contactless chip)
DE41 Terminal ID TRM00017
DE42 Merchant ID MERCH0001234
DE49 Currency 840 (USD)
Authorization response MTI 0110
DE38 Approval code A1B2C3
DE39 Response code 00 (00 = approved, 05 = do not honour, 51 = no funds)Read more: ISO 8583
For tech teams, product owners and testers
| For developers | Never write full card numbers in logs. PCI DSS forbids it. If a request times out, send a reversal (0400) so the shopper is not charged twice. |
| For product owners | Decide what decline messages people see, whether you allow partial approvals, and how disputes are handled. |
| What to test | A timeout followed by a reversal. A partial approval. DE39 codes 00, 05 and 51. A duplicate STAN (the trace number). |
Read next
- All payment files, one by one
- PayPal integration runbook on this site
- ACH, file by file
- Card payments, step by step
Sources: PayPal developer documentation; Nacha Operating Rules; card network rules. Sample files are fictional and shortened.
Working on a payments project?
I help banks and fintechs deliver real-time payments, ISO 20022, and AI-driven AML and compliance change, from strategy to go-live.
Connect on LinkedInSee how I can help