> ## Documentation Index
> Fetch the complete documentation index at: https://docs.droplinked.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Merchant PSP onboarding

> How a merchant connects their own payment provider to Droplinked — the OAuth onramps, the credential paste-in onramps, the Stripe Connect account types, and who is merchant of record.

A merchant can connect their own provider account so that payments route through it. There
are three shapes of onramp, and which one a merchant used determines who is merchant of
record and who carries chargeback liability — so this page states each one explicitly.

All routes below are on `https://apiv3.droplinked.com` and require a merchant
**Bearer JWT** unless marked otherwise.

## 1. OAuth onramps

The merchant authorises Droplinked against an account they already own. Nothing is created
on their behalf.

| Provider | Start | Callback |
| - | - | - |
| Stripe | `POST /v2/merchant/psp-connect/stripe/oauth-start` | `GET /v2/merchant/psp-connect/stripe/callback` |
| PayPal | `POST /v2/merchant/psp-connect/paypal/oauth-start` | `GET /v2/merchant/psp-connect/paypal/callback` |
| Paymob | `POST /v2/merchant/psp-connect/paymob/oauth-start` | `GET /v2/merchant/psp-connect/paymob/callback` |

`oauth-start` mints an authorize URL bound to the calling merchant. The `state` token
embeds the merchant id, an expiry, and an HMAC signature; the callback verifies the HMAC
and enforces one-time use before exchanging the authorization code. The callback is the one
route in this surface that is **not** behind the merchant JWT — it is reached by the
provider's redirect, and its trust comes from the signed state token instead.

A generic form also exists: `POST /v2/merchant/psp-connect/:pspName/oauth/start`.

`503` from `oauth-start` means the onramp flag is off or its environment variables are
unset on that plane — not that the merchant is ineligible.

## 2. Credential paste-in onramps

For providers without an OAuth flow, the merchant pastes credentials they obtained from the
provider directly.

| Provider | Route |
| - | - |
| Telr | `POST /v2/merchant/psp-connect/telr/credentials` |
| MamoPay | `POST /v2/merchant/psp-connect/mamopay/credentials` |
| Bonum | `POST /v2/merchant/psp-connect/bonum/credentials` |

These are **idempotent**: re-pasting credentials transitions any existing connection row
back to `ACTIVE` rather than creating a duplicate.

## 3. Platform-created Stripe Connect accounts

Droplinked can also create a connected account for a merchant. **Two onramps exist and they
create different account types** — this is the question a payments partner asks first, so
here is the precise answer:

| Route | Account type created |
| - | - |
| `GET /stripe/account-onboarding` | **Standard** |
| `POST /stripe/connect/account` | **Express** |

> [!WARNING]
>
> `GET /stripe/account-onboarding` is described in the generated OpenAPI summary as creating
> an "Express" account. **That summary is wrong** — the implementation calls
> `accounts.create({ type: 'standard' })`. Accounts created through that route are Standard.
> Trust this page over that summary; the summary is being corrected upstream.

Supporting routes:

| Route | Purpose |
| - | - |
| `GET /stripe/connect/account/status` | Read connected-account readiness |
| `GET /stripe/connect/onboarding/refresh` | Re-issue an expired onboarding link |

## Reading a merchant's connections

```bash theme={null}
curl https://apiv3.droplinked.com/v2/merchant/psp-connect/me \
  -H "Authorization: Bearer <merchant JWT>"
```

Returns every connection row for the merchant with its status. **Only `ACTIVE` rows route
traffic** — a row in any other state is a record, not a capability.

To disconnect: `DELETE /v2/merchant/psp-connect/:pspName`.

## Merchant of record and chargeback liability

| Merchant state | Where the charge lands | Who answers a chargeback |
| - | - | - |
| Own account connected (OAuth or platform-created Connect account) | The merchant's own provider account; Droplinked takes an application fee | The merchant, under their own acquiring relationship |
| No account connected | Droplinked's platform account | Droplinked |

Two consequences worth being explicit about:

* **Connecting an account is a liability transfer, not just a settlement change.** A
  merchant who connects Stripe takes on 3DS/SCA posture, chargeback response, and payout
  timing under their own Stripe agreement.
* **A connected account is not automatically a working one.** Stripe must also enable
  charges on it. Until it does, the
  [checkout intent resolver](/api-reference/public/checkout-intent-resolver.md) will report
  `PSP_ACCOUNT_NOT_READY` / `STRIPE_CHARGES_DISABLED` and the card slot will not be
  offered. Always resolve at request time; never infer availability from the fact that a
  connection row exists.

> [!NOTE]
>
> Merchant **payout and withdrawal** for the platform-account path is not a self-serve API
> surface today and is not documented here. Reconciliation for that path is handled
> off-platform. Do not build against an automated merchant payout endpoint — ask us about
> your specific settlement requirement instead.

## Related

* [Payment method coverage](/guides/payments/psp-coverage.md)
* [PCI posture and card-data handling](/guides/payments/pci-and-compliance.md)
* [Stripe integration guide](/guides/integrations/stripe.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.