PayPal

PayPal is a payment method and a wallet rather than only a card gateway. On the PayPal side sit the buyer's account, the order and capture objects behind each transaction, any subscriptions or billing agreements, refunds, and PayPal's own dispute and buyer-protection process. On the AppBO side sit the contact, the order record, the pipeline and the workflows that act on a confirmed payment.

You add it alongside cards rather than instead of them. Some buyers will not type a card number into a page they do not recognize but will happily click a PayPal button, and in several markets that preference is strong enough to be the difference between an abandoned checkout and a sale. The point of the integration is that a PayPal payment produces the same downstream consequences as a card payment (same fulfillment workflow, same tags, same opportunity movement) so the rest of your automation does not have to care which button the customer pressed.

The reconciliation problem is the interesting part. Two processors means two sources of truth about money, two refund processes, two dispute processes and two sets of payout timing. The integration is only finished when a person looking at a contact in AppBO can see what was paid regardless of method, and when your finance process can tie both back to the bank without a spreadsheet of exceptions. That takes a deliberate choice of which field records the method and which identifier is stored where.

1. Confirm the PayPal account is the right type and fully verified: a business account, with the bank account attached, the business name confirmed, and any identity review completed. Payments into an unverified account can be held.
2. Decide what PayPal is for. Will it accept one-off payments only, or also recurring billing? Recurring through PayPal behaves differently from card subscriptions, and deciding later means rebuilding the checkout.
3. In the AppBO sub-account, open the payments settings and start the PayPal connection, authorizing against the business account that should receive funds. Confirm afterwards which PayPal account the connection resolved to.
4. Where the connection requires API credentials rather than a hosted authorization, create them in PayPal's developer dashboard for the correct environment, and store them in the platform's payment settings rather than anywhere else.
5. Keep sandbox and live strictly separate. PayPal's sandbox has its own accounts, its own credentials and its own buyer logins; build and test entirely in sandbox before touching live credentials.
6. Configure the checkout experience: where the PayPal button appears relative to the card fields, which currency, and whether guest checkout without a PayPal account is allowed. Burying the button defeats the purpose of adding it.
7. Set the brand name and return behavior so the buyer recognizes the page they are redirected to and lands back somewhere sensible. An unbranded interstitial increases abandonment at the worst possible moment.
8. Decide the identity key. PayPal returns the email on the buyer's PayPal account, which is frequently not the email they typed into your form. Choose whether your contact match uses the form email or the PayPal email, and apply it consistently or you will create a second contact for every PayPal buyer.
9. Add a custom field on the contact to record the payment method, and another to hold the PayPal transaction or capture identifier. These two fields are what make later reconciliation possible.
10. Build the automation on the payment-confirmed event, not on the buyer returning to your page. A PayPal redirect can be abandoned after the money moved, and the browser returning is not proof of capture.
11. Build the reversal paths explicitly: refund, and separately the PayPal dispute or claim process, which has its own lifecycle and timings. Whatever a successful payment granted must be revocable.
12. Verify in sandbox end to end with a sandbox buyer account: complete a payment, confirm the platform records it, confirm the workflow ran, and confirm the method and identifier fields were populated.
13. Test the abandonment case in sandbox: start a PayPal payment and close the tab after approving. Confirm what your system believes happened, and fix it if the answer is wrong.
14. Switch to live credentials and run one small real transaction with a real PayPal account, end to end, then refund it and confirm the reversal workflow fires and the funds return.
15. Set up reconciliation as a routine, not a reaction: a regular comparison of PayPal activity against platform records, with someone owning the exceptions. Alert on payments present in one system and absent in the other.

Platform to PayPal

• Order details for the intended payment: amount, currency, item description and your own reference identifiers.
• The return and cancel destinations the buyer comes back to after approving or abandoning.
• Capture requests, where the flow authorizes first and captures second.
• Refund requests against a prior capture, where initiated from the platform.

PayPal to the platform

• Payment approval and capture outcomes: completed, pending, declined, or requiring further action.
• The transaction, order and capture identifiers, which are the keys for every later reconciliation or refund.
• The payer's details as PayPal holds them. Name, PayPal account email, and the shipping address on their PayPal account.
• Refund confirmations, and notifications of disputes, claims and chargebacks.
• Recurring payment outcomes where a subscription or billing agreement is in use.

What does not move

• Card or funding-source detail. The buyer's funding instrument stays inside PayPal entirely.
• PayPal's buyer-protection and dispute process. Cases are handled in PayPal's resolution center, not in the platform.
• Payout and balance movements. When funds leave the PayPal balance for the bank is a PayPal matter.
• Historical PayPal transactions from before the connection existed.
• A unified ledger across processors. Nothing automatically merges PayPal and card transactions into one authoritative total. That is reporting work you have to do.

Scenario: a checkout page offers card and PayPal side by side. A buyer chooses PayPal, pays with a different email from the one on the form, and later opens a dispute.

1. The buyer completes the form on the checkout step with jane.smith@company.com, which creates or matches the contact in AppBO.
2. They click the PayPal button instead of entering a card, and are redirected to PayPal to approve the payment.
3. They sign in to PayPal with jsmith.personal@example.com (a different address) and approve.
4. PayPal confirms the capture and returns the transaction identifier along with the payer's PayPal email.
5. The platform records the payment against the contact that was already created from the form email, because the integration was configured to match on form email rather than payer email. The payer email is written to a separate custom field so support can find the buyer in PayPal later.
6. The payment-confirmed workflow fires: it writes PayPal to the payment method field, writes the transaction identifier to its custom field, tags the contact purchased, moves the opportunity to Won, and sends the receipt and delivery email.
7. The buyer's browser never returns to the thank-you page because they closed the tab. The order is complete regardless, because the automation ran on the payment event rather than on the page view.
8. At the end of the week the finance process exports PayPal activity and compares transaction identifiers against the custom field in the platform. Every PayPal payment has a matching record; the one exception is a pending payment awaiting clearance, which is noted and checked again the following week.
9. Three weeks later the buyer opens a dispute in PayPal. A notification arrives and a workflow tags the contact payment-disputed, removes the purchased tag, revokes the download access, and raises a task for finance with the transaction identifier.
10. Finance submits evidence in PayPal's resolution center (the only place the case can be worked) using the delivery record the platform holds against the contact.
11. PayPal resolves in the merchant's favor. The task is closed, the dispute tag is removed, the purchased tag is restored and access is reinstated, with the whole sequence visible on the contact's timeline.

Rate limiting

PayPal applies its own API limits and they differ by endpoint; consult PayPal's current documentation rather than assuming a figure, and add backoff on throttled responses. The practical constraint for most AppBO accounts is not the API limit but the reconciliation workload, which grows linearly with transaction volume unless it is automated from the start.

Retries and idempotency

PayPal supports a request identifier on order and capture calls so a retried request is not treated as a new payment. Use it, and check the current field name in PayPal's reference rather than guessing. Notifications are delivered at least once and retried, so dedupe on the transaction or event identifier. The riskiest retry is a capture: retrying it without the idempotency header can take the money twice, and refunding a duplicate capture is a worse customer experience than a failed checkout.

Field mapping traps

The payer email is the biggest trap in PayPal integrations: it is the buyer's PayPal account address, not necessarily the one on your form, and treating them as the same thing creates duplicate contacts at scale. Currency codes must match what the PayPal account is configured to accept. Amount formatting and decimal precision are strict. The shipping address PayPal returns is the one on the buyer's PayPal account, which may not be where they expect delivery: decide which address is authoritative and say so at checkout.

Pending and delayed states

Unlike a card authorization, a PayPal payment can legitimately sit in a pending state. Under review, awaiting an e-check, or held for a verification step. Treating pending as paid ships goods you have not been paid for; treating it as failed loses sales. Handle it as its own state with its own workflow, and have a path that completes the order when it clears.

Duplicate creation

Two drivers: the payer-email mismatch described above, and buyers who abandon and retry the PayPal redirect, producing two orders for one intent. Key orders on your own reference identifier passed into the PayPal order, and check for an existing completed payment against that reference before capturing another.

Sandbox versus live

PayPal's sandbox is a fully separate world with its own buyer and merchant accounts and its own credentials. Sandbox credentials in a live checkout fail silently in confusing ways; live credentials in a test produce real charges. Label the credential entries unambiguously and confirm the environment as part of go-live, not after.

Auth expiry

API credentials can be rotated or revoked in PayPal, and the connection can also be broken by account restrictions following a review. The symptom is the PayPal button failing at checkout, which costs sales silently, so monitor checkout success rate by method rather than only in aggregate.

What commonly breaks

• Fulfillment triggered by the buyer returning to the thank-you page, so abandoned-tab payments never fulfill.
• Pending payments treated as completed.
• Duplicate contacts from payer-email mismatch.
• Sandbox credentials left in a live configuration.
• Refunds issued in PayPal with no corresponding reversal in the platform, leaving access granted.
• Disputes handled late because nobody owns the notification.
• Currency or decimal mismatches rejecting otherwise valid orders.