Skip to main content

Integration Checklist & Go-Live Runbook

This runbook takes a new integration partner from first contact through to production. It is organised into stages, each with a checklist. Work through the checkboxes in order. A stage is complete only when every box is ticked, and each stage must be complete before the next begins.

Business and technical tasks are intentionally mixed within each stage, because they happen together: a single person or a small team typically drives a stage end to end rather than handing off between a "business" and a "technical" track. The Owner label on each item tells you who normally leads it (Business, Solution Architect, or Developer), but every item belongs to the same checklist.

KYC must be approved before the engagement begins:

The collaboration does not start until KYC is approved by the PaymentsAI compliance team. KYC happens in Stage 0, before discovery, kickoff, or any technical integration. See KYC Overview.

Stage 0: Invitation & KYC​

Before any discovery or technical work, the merchant is invited to a production organisation and must pass KYC. The engagement only begins once KYC is approved.

  • Merchant receives an invitation to the production organisation. The invitation is sent by the Integration Consultant, or by the business partner who is introducing the merchant to PaymentsAI. (Owner: Integration Consultant / business partner)
  • Merchant accepts the invitation and joins the production organisation. (Owner: Business)
  • Merchant submits KYC information and required documents. (Owner: Business)
  • KYC is reviewed and approved by the PaymentsAI compliance team. See KYC Onboarding Flow. (Owner: PAI Compliance)

Approval gate:

Discovery, kickoff, stage access, and integration do not begin until KYC reaches the approved status. See KYC Statuses.

Stage 1: Discovery​

With KYC approved, Discovery defines what you are building and agrees the technical approach.

  • Define your business goals and expected transaction volume. (Owner: Business)
  • Choose your technical architecture: direct API, SDK, or hosted checkout. (Owner: Solution Architect, with Business)
  • Review the Decision Matrix below ahead of the kickoff. (Owner: Business, with Solution Architect)
  • Schedule the kick-off call with the Integration Team. (Owner: Business)
  • Confirm all Decision Matrix choices at the kickoff meeting. (Owner: Business, with Integration Team)

Integration Team roles​

These are the PaymentsAI roles assigned to your integration. They are your contacts on the PaymentsAI side throughout the engagement.

RoleResponsibility
Integration ConsultantPrimary business point of contact for project flow and commercial matters
Solution ArchitectTechnical strategy and API design guidance
PPOProject scope and timeline
QA SpecialistTest plans and integration validation
Backend DeveloperDeep API support and debugging

Decision Matrix​

Review the following decisions during Discovery and confirm them at the kickoff meeting with your Integration Team. Most are documented in detail in the Business Decision Matrix. Review that page with your Integration Consultant beforehand. The two decisions specific to this runbook are described inline below.

DecisionDetails
Gateway ModelDefault PAI gateway vs High-Risk gateway. See Business Decision Matrix.
Dynamic DescriptorCustom bank-statement text (maximum 22 characters, no special characters). See Business Decision Matrix.
Tax CalculationPAI handles tax, or the merchant uses a third-party service. See Business Decision Matrix.
Express MethodsApple Pay, Google Pay, and PayPal (required or optional). See Business Decision Matrix.
3D SecureMandatory for EU/UK (PSD2 SCA) and Japan, optional for the US (enables liability shift). See Business Decision Matrix.
BIN exposureRequires an Attestation of Compliance (AoC) and written business justification.
Backup GatewayA second gateway configured for failover.

Stage 2: Stage Access​

The stage environment is used for all integration and testing before go-live. The Integration Consultant provides everything you need to access stage, including keys, credentials, accesses, and documentation. You receive a ready-to-use credential set; there is no key exchange on stage. The Temporal API Key and the Temporal-to-Permanent exchange apply to production only, at go-live (see Stage 5: Go-Live).

  • Integration Consultant delivers your stage access (keys, credentials, accesses, and documentation) via 1Password. (Owner: Integration Consultant)
  • Confirm you have received your stage credential set (Owner: Developer):
    • Organization ID (format org_xxx)
    • Account ID
    • API Key (ready to use on stage, no exchange required)
  • Configure your environment variables: API_URL (use staging-api), API_KEY, ORGANIZATION_ID. (Owner: Developer)

Copying a value from 1Password:

If a credential field is non-selectable in 1Password, triple-click the field to select the entire value.

Stage 3: Client Testing​

Implement and validate the full payment flow on stage.

  • Implement tokenization. For web, FramePay is recommended. See the FramePay documentation. (Owner: Developer)
  • Create a customer and attach a payment instrument. (Owner: Developer)
  • Run your first transaction and first subscription. (Owner: Developer)
  • Set up your webhook endpoint and verify HMAC signature verification. (Owner: Developer)
  • Test all card scenarios: 3DS challenge, 3DS frictionless, declined, and insufficient funds. (Owner: Developer, with QA Specialist)

Stage 4: Pre-Production​

  • Security scan: check for API key exposure, sensitive data in logs, and PCI compliance. (Owner: Developer)
  • Load test: confirm your infrastructure handles your expected peak volume. (Owner: Developer)
  • Final validation: run the complete flow end-to-end with the Solution Architect. (Owner: Developer + Solution Architect)

Compliance and website requirements​

The following must be in place before go-live (Owner: Business):

  • Terms and Conditions visible on the merchant website
  • Privacy Policy visible
  • Refund Policy visible
  • Customer contact methods (email and phone) published
  • Primary transaction currency displayed at checkout
  • No prohibited items in the product catalog (malware, adult content, hate speech, counterfeit goods, or weapons)
  • Restricted items (Forex, crypto, supplements, gaming) have prior written PAI approval

Stage 5: Go-Live​

Who acts: Merchant, with the Solution Architect.

Four elements are required to go live.

1. Organization ID​

Your unique organization identifier, assigned when your organization is created.

  • Where to find it: PAI panel → Settings tab
  • Format: org_xxx

2. Account ID​

The unique identifier for your processing account. Generated by the platform and delivered to you by the Solution Architect.

3. Permanent API Key​

A Temporal API Key is issued only for production, and only at this point. You receive it via 1Password and use it once to generate your Permanent API Key. (On stage you used a ready-to-use API Key with no exchange; that does not apply to production.)

For security, the Permanent API Key is not sent to you directly. You generate it yourself using your Temporal API Key. After you generate it, the Temporal API Key is automatically deleted and cannot be reused. PAI does not store or log your Permanent API Key or secret, so you must save these credentials in a secure location immediately.

The full procedure, secret policy, and key-rotation endpoints are documented in the Account & API Key Generation guide. The exchange is a single PATCH request against the production API in which you set your account secret and receive your API key in the response.

First, export your values so the request below can reference them:

export ACCOUNT_ID="Your Account ID Here"
export TEMPORAL_API_KEY="Your Temporal API Key Here"

Then run the exchange request:

curl --location --request PATCH \
  "https://api.payments.ai/v1/accounts/public-api/${ACCOUNT_ID}" \
  --header "Authorization: ApiKey ${TEMPORAL_API_KEY}" \
  --header 'Content-Type: application/json' \
  --data '{ "secret": "YOUR_CHOSEN_SECRET" }'

Secret policy:

  • Between 12 and 30 characters
  • At least 1 uppercase letter
  • At least 1 alphanumeric character
  • Rotate every 90 days; cannot reuse any of the last 4 secrets

The Permanent API Key is returned in the response body. The Authorization header format is:

ApiKey <accountId>_<apiKey>_<apiKeyId>

The separator is an underscore (_).

4. Mandatory Billing Setup​

Log in to the PAI Admin Panel and add a Primary Payment Instrument (credit card or bank account) for service fees. This unlocks production features.

Go-live confirmation:

  • Organization ID located in Settings
  • Account ID received from the Solution Architect
  • Permanent API Key generated and stored securely
  • Primary Payment Instrument added in the Admin Panel

Final technical checklist​

Complete every item below before switching to production. This confirms the technical work from the stages above is in place.

Webhooks

  • Webhook endpoints are live and returning HTTP 200
  • Webhook HMAC signature verification is implemented and tested

Credentials and security

  • API keys are stored in backend environment variables (not in frontend code and not in source control)
  • Monitoring and alerting are configured for payment failures and webhook delivery failures
  • Post-launch monitoring plan agreed with the Solution Architect

Compliance and website

  • KYC approved by the PAI compliance team
  • Terms and Conditions, Privacy Policy, and Refund Policy visible on the website
  • Customer contact methods (email and phone) published
  • Primary transaction currency displayed at checkout
  • No prohibited items in the product catalog
  • Restricted items (if applicable) have prior PAI approval