Partner Onboarding Runbook

Step-by-step procedure for onboarding a new partner from creation to go-live.

This page is for internal operations staff only. It is not intended for merchants or partners.

Prerequisites

Before starting the onboarding process, confirm you have:

Admin access to the JoPay admin portal
The partner's business name and desired URL slug
The partner's preferred display currency (from the 28 supported currencies)
The partner's preferred blockchain (Polygon, Base, Ethereum, Optimism, or Arbitrum)
The partner's preferred payment asset (USDC or EURC)
The partner's branding assets (logo, primary color) if applicable
A technical contact at the partner who will configure webhooks

Create partner in admin portal

Navigate to the admin portal and create a new partner record with the following fields:

Field	Description	Example
`name`	Business display name	Acme Payments
`slug`	URL-safe identifier (lowercase, hyphens only)	acme-payments
`display_currency`	Default fiat currency for display	USD
`chain`	Default blockchain network	polygon
`asset`	Payment stablecoin	USDC
`min_fiat_per_request`	Minimum payment amount in display currency (in cents)	100 (= $1.00)
`branding`	Logo URL and primary color hex code	#2563EB

The slug must be unique across all partners and cannot be changed after creation. Double-check spelling before saving.

Generate API credentials

After the partner record is created:

Generate an API key pair in the admin portal for the new partner.
Record the partner_id and api_key.
Securely deliver the credentials to the partner's technical contact. Use an encrypted channel (e.g., a one-time secret sharing service). Never send credentials via plain email.

Configure webhook

Work with the partner's technical team to set up webhooks:

The partner provides their webhook endpoint URL (must be HTTPS).
Enter the URL in the admin portal under the partner's webhook settings.
The system generates a webhook signing secret. Deliver this to the partner securely.
Advise the partner to implement HMAC-SHA256 signature verification using the code examples in the Webhook events reference.

Create first merchant invite

Create a test merchant invite to verify the onboarding flow:

In the admin portal, create a merchant invite for a test email address controlled by the partner.
Verify the invite email is delivered successfully.
Have the partner's technical contact accept the invite and complete the merchant setup flow.
Confirm the merchant appears in the partner's merchant list in the admin portal.

Test payment flow

Run a complete end-to-end payment test:

Log in as the test merchant and create a payment request for a small amount (e.g., $1.00).
Open the payment link in a separate browser or incognito window.
Send the exact USDC amount from a test wallet to the merchant's address on the configured chain.
Wait for the Trails engine to verify the payment. The dashboard should update to show the payment as verified.
Confirm the payment receipt is generated and accessible.

Use Polygon or Base for test payments to minimize gas costs. A test payment on Polygon costs less than $0.01 in gas.

Verify webhook delivery

Confirm webhooks are working end-to-end:

After the test payment is verified, check the WebhookDelivery table for the partner.
Confirm a payment.proof_attached event was delivered and received a 200 response.
Confirm a payment.proof_verified event was delivered and received a 200 response.
Ask the partner to confirm they received both events and that signature verification passed on their end.
If deliveries failed, troubleshoot using the webhook delivery failing procedure in the Admin Playbook.

Go live

Once all tests pass, the partner is ready for production:

Remove or disable the test merchant if it was only for testing.
Confirm the partner's production webhook URL is configured (it may differ from the test URL).
Verify FX rates are loading correctly for the partner's display currency.
Confirm rate limits are appropriate for the partner's expected traffic volume.
Provide the partner with links to relevant documentation: Webhook events, Error codes, Rate limits.
Add the partner to the monitoring dashboard for ongoing health checks.

Item	Status
Partner record created with correct slug, currency, chain, asset	_____
API credentials generated and securely delivered	_____
Webhook URL configured and test delivery succeeded	_____
Webhook signing secret delivered securely	_____
Test merchant invite created and accepted	_____
End-to-end test payment done and verified	_____
Both webhook events (proof_attached, proof_verified) received by partner	_____
FX rates loading for partner's currency	_____
Rate limits reviewed and verified	_____
Partner added to monitoring dashboard	_____
Documentation links shared with partner	_____

Issue	Cause	Resolution
Invite email not delivered	Email provider blocked the invite	Check spam folder. Verify the sending domain is not blocklisted. Resend the invite.
Webhook test delivery fails	Partner endpoint not reachable or returning errors	See the Admin Playbook "Webhook delivery failing" procedure.
Test payment not verifying	Wrong chain, amount, or recipient address	Verify the transaction on the block explorer. Check that the chain, amount, and recipient match exactly.
FX rates showing $0.00	Currency not configured or FX provider issue	Verify the display currency is in the supported list. Try a manual FX refresh.