# Merchant Management (/platform-api/merchant_management)
Manage the merchants in your organization from your backend. Every call uses your Server Secret Token, so keep it on your server.
| Detail | Value |
| -------------- | ------------------------------------------------------------------------------------------- |
| Base URL | `https://api.sandbox.tapaya.com` for sandbox, `https://api.tapaya.com` for production |
| Authentication | Server Secret Token in `Authorization`. See [Authentication](/platform-api#authentication). |
| Amounts | Minor units: `2500` with `EUR` is 25.00 EUR. Relative fees in basis points: `100` is 1%. |
| Related guide | [Merchant Onboarding](/platform-api/merchant_onboarding) |
## All operations [#all-operations]
| Operation | Use it to |
| ------------------------------------------------------------------- | ---------------------------------------------------------------- |
| [Read a saved onboarding](#read-a-saved-onboarding) | Continue a merchant's onboarding form where they left it. |
| [Save channel selections](#save-channel-selections) | Store the payment channels a merchant chose, without submitting. |
| [List members](#list-members) | See who already has access to a merchant. |
| [List terminals](#list-terminals) | Show a merchant's terminals and their devices. |
| [List email invites](#list-email-invites) | Track single-use invites sent to known recipients. |
| [List reusable links](#list-reusable-links) | Track campaign links and whether they are paused. |
| [Create a reusable link](#create-a-reusable-link) | Start a campaign that many merchants can register through. |
| [Change an invite's expiry](#change-an-invites-expiry) | Extend or shorten an invite, including an expired one. |
| [Pause or resume a reusable link](#pause-or-resume-a-reusable-link) | Stop new registrations for a while without revoking the link. |
| [List pricing sets](#list-pricing-sets) | Find the pricing sets your organization may build profiles from. |
| [List commission profiles](#list-commission-profiles) | Choose a profile to assign to an invite. |
| [Create a commission profile](#create-a-commission-profile) | Offer merchants a price list built from a pricing set. |
| [Update a commission profile](#update-a-commission-profile) | Rename a profile or change its rates. |
| [Delete a commission profile](#delete-a-commission-profile) | Remove a profile you no longer offer. |
| [Set the default profile](#set-the-default-profile) | Choose the profile that invites use when they name none. |
| [Read merchant pricing](#read-merchant-pricing) | Show the rates a merchant signed up with. |
## Onboarding drafts [#onboarding-drafts]
**Use it to** continue a merchant's onboarding form with everything they have saved so far.
```bash
curl 'https://api.sandbox.tapaya.com/integrator/merchant/018f8f2a-3b1e-7c2a-9f1a-2e6a1b7c4d3e/onboarding' \
-H 'Authorization: REPLACE_ME'
```
**Good to know:**
* This is the only call that returns the whole saved onboarding; the profile and processor calls return parts of it.
* `pricingConstraints` lists what the merchant may choose, not fee schedules.
**Returns:**
| Field | Description |
| ---------------------- | ------------------------------------------------------------------------------------------------ |
| `identity` | The merchant's identity details. |
| `address` | The merchant's address. |
| `business` | Business information shared by both channels. |
| `kyb` | Bank accounts, the primary account, company stakeholders or the individual, and their documents. |
| `capability` | The selected capability. |
| `terminal` | Saved in-store channel details. |
| `online` | Saved online channel details. |
| `processors` | Status with each payment processor. |
| `commissionProfileIds` | Commission profiles assigned to the merchant. |
| `pricingConstraints` | Allowed settlement currencies and MCCs. |
**Use it to** store the payment channels a merchant chose in your form before they finish onboarding.
```bash
curl -X POST 'https://api.sandbox.tapaya.com/integrator/merchant/018f8f2a-3b1e-7c2a-9f1a-2e6a1b7c4d3e/channel' \
-H 'Authorization: REPLACE_ME' \
-H 'Content-Type: application/json' \
-d '{
"capability": 2,
"terminal": {
"mcc": "5411",
"statementDescriptor": "ACME STORE",
"productDescription": "Groceries",
"averageItemValue": 2500,
"expectedMonthlyTurnover": 500000,
"numberOfTerminals": 1
}
}'
```
**Good to know:**
* Works only for a merchant whose onboarding draft and profile are already saved.
* Updates the draft and returns `200`. It does not submit onboarding or register a processor account.
* Send only the channel sections the merchant selected.
**Parameters:**
| Field | Description |
| ------------ | -------------------------------------------------------------------------------------------------------------------------------------- |
| `capability` | The selected channels. Same values as in [Merchant Onboarding](/platform-api/merchant_onboarding#request-online-payment-capabilities). |
| `terminal` | In-store channel details, with the same fields as in Merchant Onboarding. |
| `online` | Online channel details, with the same fields as in Merchant Onboarding. |
## Members and terminals [#members-and-terminals]
**Use it to** see who already has access to a merchant.
```bash
curl 'https://api.sandbox.tapaya.com/integrator/merchant/018f8f2a-3b1e-7c2a-9f1a-2e6a1b7c4d3e/members' \
-H 'Authorization: REPLACE_ME'
```
**Good to know:**
* Returns an array of current members.
* Pending invitations are not included; they are listed separately.
**Returns:** for each member:
| Field | Description |
| ----------- | ------------------------------------ |
| `userId` | The member's user ID. |
| `firstName` | First name. |
| `lastName` | Last name. |
| `email` | Email address. |
| `joinedAt` | When the member joined the merchant. |
**Use it to** show a merchant's terminals and the devices assigned to them.
```bash
curl 'https://api.sandbox.tapaya.com/integrator/merchant/018f8f2a-3b1e-7c2a-9f1a-2e6a1b7c4d3e/terminal?page=1&pageSize=25' \
-H 'Authorization: REPLACE_ME'
```
**Good to know:**
* Returns terminals, not active locations; locations have their own list.
* The response contains `items` and `totalCount`. Each item has its terminal and location IDs, label and device details.
* `terminalType` and `deviceIdentifier` describe the device assigned now, not the device that captured an earlier payment.
**Parameters:**
| Field | Description |
| --------------- | ----------------- |
| `page` | Page number. |
| `pageSize` | Rows per page. |
| `sortBy` | Field to sort by. |
| `sortDirection` | Sort direction. |
## Registration invites [#registration-invites]
Use an [email invite](/platform-api/merchant_onboarding#invite-a-merchant-to-complete-hosted-onboarding) for a known recipient, or a reusable link for a campaign. Both can restrict channels and assign commission profiles.
**Use it to** track the single-use invites you sent.
```bash
curl 'https://api.sandbox.tapaya.com/integrator/merchant/invites' \
-H 'Authorization: REPLACE_ME'
```
**Good to know:**
* Each invite shows its recipient email, URL, `capability` and `commissionProfileIds`.
* Invites also carry `commissionProfileId`, the single-profile form of `commissionProfileIds`.
**Use it to** track your campaign links and see which ones are paused.
```bash
curl 'https://api.sandbox.tapaya.com/integrator/merchant/reusable-registration-invites' \
-H 'Authorization: REPLACE_ME'
```
**Good to know:**
* Each link shows its `capability`, assigned profiles and `pausedAt`.
* `pausedAt` is `null` while the link is not paused.
* A paused link that has not expired or been revoked still matches `isActive=true`. Check `pausedAt` to tell them apart.
**Use it to** start a campaign that many merchants can register through.
```bash
curl -X POST 'https://api.sandbox.tapaya.com/integrator/merchant/reusable-registration-invites' \
-H 'Authorization: REPLACE_ME' \
-H 'Content-Type: application/json' \
-d '{
"name": "Partner onboarding",
"expiresAt": "2030-12-31T00:00:00Z",
"capability": 2
}'
```
**Good to know:**
* `capability` limits which channels merchants can choose. It does not grant processor approval.
* Omit the profile fields to assign the organization's default profile.
* `commissionProfileId` is still accepted for a single profile. Use `commissionProfileIds` instead, and never send both.
**Parameters:**
| Field | Description |
| ---------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
| `name` | A name for the campaign. |
| `expiresAt` | ISO 8601 UTC timestamp, at least one day in the future. There is no maximum. |
| `capability` | Optional. Same values as for [email invites](/platform-api/merchant_onboarding#invite-a-merchant-to-complete-hosted-onboarding). |
| `commissionProfileIds` | Optional. Same rules as for email invites. |
**Use it to** extend or shorten an invite, including one that has already expired.
```bash
curl -X PUT 'https://api.sandbox.tapaya.com/integrator/merchant/reusable-registration-invites/018f8f2a-4c2f-7d3b-8a2e-3f7b2c8d5e4f/expires-at' \
-H 'Authorization: REPLACE_ME' \
-H 'Content-Type: application/json' \
-d '{"expiresAt": "2031-01-31T00:00:00Z"}'
```
**Good to know:**
* For an email invite, call `PUT /integrator/merchant/invites/{inviteId}/expires-at` with the same body.
* Returns `204`.
* Revoked invites and used email invites cannot be extended.
**Parameters:**
| Field | Description |
| ----------- | ---------------------------------------------------------------------------- |
| `expiresAt` | ISO 8601 UTC timestamp, at least one day in the future. There is no maximum. |
**Use it to** stop new registrations for a while without revoking the link.
```bash
curl -X PUT 'https://api.sandbox.tapaya.com/integrator/merchant/reusable-registration-invites/018f8f2a-4c2f-7d3b-8a2e-3f7b2c8d5e4f/pause' \
-H 'Authorization: REPLACE_ME'
```
**Good to know:**
* Call `.../resume` on the same link to accept registrations again. Resuming does not extend the expiry.
* Both return `204` and are idempotent.
* Opening a paused link returns `410`.
## Commission profiles [#commission-profiles]
A commission profile is the price list you offer merchants. Build it from a pricing set your organization is authorized for.
**Use it to** find the pricing sets you can build commission profiles from.
```bash
curl 'https://api.sandbox.tapaya.com/integrator/organization/pricing-sets?pricingType=instore' \
-H 'Authorization: REPLACE_ME'
```
**Good to know:**
* Each set includes its contractual merchant and integrator schedules.
* Use a returned `pricingSetId` when you create a profile.
**Parameters:**
| Field | Description |
| ------------- | -------------------------------- |
| `pricingType` | Optional. `online` or `instore`. |
**Use it to** choose a profile to assign to an invite.
```bash
curl 'https://api.sandbox.tapaya.com/integrator/organization/commission-profiles?pricingType=online' \
-H 'Authorization: REPLACE_ME'
```
**Good to know:**
* Returns only enabled, complete profiles of your organization.
* Each profile covers one pricing type.
* Keep each profile's `revision` if you plan to update it.
**Parameters:**
| Field | Description |
| ------------- | -------------------------------- |
| `pricingType` | Optional. `online` or `instore`. |
**Use it to** offer merchants a price list built from a pricing set.
```bash
curl -X POST 'https://api.sandbox.tapaya.com/integrator/organization/commission-profiles' \
-H 'Authorization: REPLACE_ME' \
-H 'Content-Type: application/json' \
-d '{
"name": "Standard profile",
"pricingModel": 1,
"cardTypes": [
{"region": 1, "holderType": 1, "scheme": 1, "enabled": true, "referralFeeRelative": 0, "referralFeeAbsolute": 0}
],
"pricings": [
{"currency": "eur", "pricingSetId": "018f8f2a-5d3a-7e4c-9b3f-4a8c3d9e6f5a"}
]
}'
```
**Good to know:**
* A profile covers one pricing type, taken from its pricing sets.
* Integrator costs and revenue shares come from the pricing set; you set only merchant rates.
* `region` is `1` domestic or `2` international, `holderType` is `1` consumer or `2` company, and `scheme` is `1` Visa or `2` Mastercard.
**Parameters:**
| Field | Description |
| -------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| `name` | The profile name. |
| `pricingModel` | `1` for MDR or `2` for IC++. |
| `cardTypes` | Each combination of region, cardholder type and scheme the profile accepts, with its referral fees. |
| `pricings` | Currency and `pricingSetId` for each currency you offer. |
| `merchantPricingOverrides` | Optional. Entries with `holderCategory`, `regionSegment`, `relative` and `absolute`. Combinations you omit keep the pricing set's rates. |
**Use it to** rename a profile or change its rates.
```bash
curl -X PUT 'https://api.sandbox.tapaya.com/integrator/organization/commission-profiles/018f8f2a-7a1c-7b2d-8e3f-6c1d2e3f4a5b' \
-H 'Authorization: REPLACE_ME' \
-H 'Content-Type: application/json' \
-d '{
"name": "Standard profile 2027",
"pricingModel": 1,
"cardTypes": [
{"region": 1, "holderType": 1, "scheme": 1, "enabled": true, "referralFeeRelative": 0, "referralFeeAbsolute": 0}
],
"expectedRevision": 3
}'
```
**Good to know:**
* Send the `revision` you last read as `expectedRevision`. A stale revision returns `409`.
* Omit `pricings` to keep the saved rates.
* A profile that is assigned to merchants, or is not editable, accepts only a new name.
**Parameters:**
| Field | Description |
| ------------------ | ------------------------------------------ |
| `name` | Required. The profile name. |
| `pricingModel` | Required. `1` for MDR or `2` for IC++. |
| `cardTypes` | Required. Same as on create. |
| `pricings` | Optional. Same as on create. |
| `expectedRevision` | The profile's `revision` when you read it. |
**Use it to** remove a profile you no longer offer.
```bash
curl -X DELETE 'https://api.sandbox.tapaya.com/integrator/organization/commission-profiles/018f8f2a-7a1c-7b2d-8e3f-6c1d2e3f4a5b' \
-H 'Authorization: REPLACE_ME'
```
**Good to know:**
* The default profile cannot be deleted. Make another profile the default first.
* A profile assigned to merchants cannot be deleted. Both cases return `400`.
**Use it to** choose the profile that invites use when they name none.
```bash
curl -X PUT 'https://api.sandbox.tapaya.com/integrator/organization/commission-profiles/018f8f2a-7a1c-7b2d-8e3f-6c1d2e3f4a5b/default' \
-H 'Authorization: REPLACE_ME'
```
**Good to know:**
* Your organization has one default profile.
* The default profile cannot be deleted.
## Merchant pricing [#merchant-pricing]
**Use it to** show the rates a merchant signed up with, for in-store and online payments.
```bash
curl 'https://api.sandbox.tapaya.com/integrator/merchant/018f8f2a-3b1e-7c2a-9f1a-2e6a1b7c4d3e/pricing' \
-H 'Authorization: REPLACE_ME'
```
**Good to know:**
* A channel without saved pricing is `null`. A merchant without any saved price list returns `404`.
* Returns contracted rates, not payment provider base schedules. Read rates from `cells`; the `commission` components are not realized commissions.
* An unknown integrator model or cost is `null`, not zero.
* Revenue shares split the distributable margin, not the whole payment amount.
**Returns:**
| Field | Description |
| ------------------------------------- | ------------------------------------------------------------ |
| `instore` | In-store pricing, or `null`. |
| `online` | Online pricing, or `null`. |
| `currency` | The pricing currency. |
| `pricingModel` | The merchant pricing model. |
| `integratorPricingModel` | The integrator pricing model, independent of the merchant's. |
| `priceListId` | The saved merchant price list, when available. |
| `pricingSetVersionId` | The source pricing set version, when available. |
| `pricingSetName` | The source pricing set name, when available. |
| `cells` | Rates by cardholder category and region. |
| `cells[].discountBps` | Final merchant relative rate in basis points. |
| `cells[].transactionFeeMinor` | Final merchant fixed fee in minor units. |
| `cells[].integratorCostRelativeBps` | Contractual integrator relative cost in basis points. |
| `cells[].integratorCostAbsoluteMinor` | Contractual integrator fixed cost in minor units. |
| `cells[].revenueShareTapayaBps` | Tapaya's share of the distributable margin in basis points. |
| `cells[].revenueShareIntegratorBps` | Your share of the distributable margin in basis points. |
## Errors [#errors]
Every operation answers with these status codes when a request fails.
| Code | Description |
| ----- | ------------------------------------------------------------------------------------------------------ |
| `400` | Invalid channel data, profile selection, filters or expiry, or deleting a default or assigned profile. |
| `401` | The Server Secret Token is missing or invalid. |
| `404` | The resource is not available to your organization, or the saved onboarding or pricing does not exist. |
| `409` | A stale profile revision, conflicting onboarding state, or an invite that was used or revoked. |