At my current employer, we onboard several new payments partners every year across APAC, Europe, and the US. Each partner — a new acquirer, a new issuer brand, a new corporate gifting platform — represents a commercial relationship, a technical integration, and a compliance checkpoint. Do it well and it's revenue. Do it poorly and it's a costly, trust-damaging delay.
Over two and a half years, I've been part of onboarding partners from Japan, Australia, Germany, France, the UK, and the US. The process is never the same twice. But the failure modes are remarkably consistent. Here's the playbook I've built — and the lessons that went into it.
The Anatomy of a Partner Onboarding
Every partner onboarding has five distinct phases, regardless of geography:
- Commercial alignment: Define the commercial terms — revenue share, transaction fees, settlement currency, SLAs. This happens between business teams but the PM needs visibility to scope the technical work accurately.
- Technical specification: Define the API integration contract — message formats, authentication, error codes, settlement file specifications. This is where most delays originate.
- Sandbox integration: The partner builds and tests their integration against our test environment. Our job is to make this as self-service as possible.
- Certification testing: A structured test suite that validates the partner's integration handles edge cases — timeouts, duplicate transactions, partial authorisations, currency mismatches.
- Production cutover: Controlled go-live, typically starting with low-volume test transactions before full traffic.
Lesson 1: Regulatory Complexity is Not a Legal Problem
The first time a European partner raised PSD2 compliance requirements mid-integration, I treated it as a legal team issue. By the time legal had reviewed and responded, we'd lost six weeks. I learned that regulatory requirements need to be surfaced and resolved in the commercial alignment phase — before a single line of integration code is written.
Now I maintain a regulatory requirements matrix for each market we operate in. Before any partner integration begins, we run through the matrix together: data residency requirements, strong customer authentication needs, local reporting obligations, currency controls. Everything that could cause a surprise later gets surfaced and scoped upfront.
Key markets and their gotchas: Japan requires specific transaction message formats that differ from ISO 8583 standards. Australia has strict data localisation requirements. Germany's gift card regulations differ from the rest of the EU. The US has state-level variations that compound federal requirements. None of this is optional, and none of it can be treated as an afterthought.
Lesson 2: The Integration Spec is a Product, Not a Document
Our original API integration guide was a 120-page PDF that hadn't been updated since 2021. Partners would spend weeks trying to get their first test transaction through, generating a flood of support requests to our engineering team. I treated the integration spec as a product problem, not a documentation problem.
We rebuilt it as a living developer portal with:
- Interactive API reference with test payloads
- Environment-specific configuration guides (sandbox vs production)
- Common error codes with plain-English explanations and remediation steps
- A self-service sandbox registration flow
Time to first successful test transaction dropped from an average of several weeks to under two weeks. Engineering support requests per new partner dropped significantly. The spec was the product.
Lesson 3: Timezones Are a Process Design Problem
Managing a partner in Tokyo and a partner in San Francisco simultaneously means you have a a very wide timezone spread across your key stakeholders. Early on, I handled this reactively — scheduling calls at awkward hours, sending emails and waiting a day for responses. Integration cycles stretched to three months when they should have taken six weeks.
The fix was async-first communication design for the integration process:
- Every integration milestone has a shared tracking document with clear status indicators and next actions — no status updates that require a meeting
- Issues are raised in a shared workspace (we use a shared channel per partner) with enough context that they can be actioned without a synchronous call
- Synchronous calls are reserved for decision points, not status updates
This alone cut our average onboarding cycle from several months to around half that time for standard integrations.
Lesson 4: Certification is a Quality Gate, Not a Formality
We have a mandatory certification test suite every partner must pass before production access. I've had commercial pressure to waive parts of this for "trusted" partners or to accelerate a revenue-critical deadline. I've resisted every time, and it's paid off.
The certification suite has caught, in real partners: misconfigured timeout handling that would have caused transaction losses during network delays; incorrect partial authorisation responses that would have led to incorrect balances; missing idempotency handling that would have caused duplicate transactions under retry scenarios.
Every one of those would have been a live incident. The certification test is the cheapest incident we never had.
Lesson 5: The Relationship is the Integration
The most successful partner onboardings I've been part of had one thing in common: a named integration contact on the partner side who had clear ownership and was genuinely invested in getting the integration live. Where onboardings stalled most often, the partner side had ambiguous ownership — integration tasks bouncing between their IT team, their product team, and their external development vendor.
During the commercial phase, I now explicitly ask for a named integration lead and a named business sponsor. Both need to be in the kickoff call. Both need to be on the shared workspace. Without named ownership, timelines are aspirational at best.
The Playbook in Summary
- Surface regulatory requirements in commercial alignment, not in technical specification
- Treat the integration spec as a product — build for self-service
- Design the integration process for async communication by default
- Never compromise the certification test suite, regardless of commercial pressure
- Insist on named ownership on both sides before integration begins
Partner onboarding isn't the most glamorous part of the PM job. But in a platform business, it's where revenue is directly unlocked. Getting it right is worth every hour of process design you put into it.
