Locations

How to send your merchant accounts' events to each location's URL, without creating an integration per customer.

By the end, each merchant account sends its events to its location's URL. You need a connected merchant account: see Connect merchant accounts.

STEP 1Create a locationin the Portal STEP 2Assign each merchantPUT /my-integration/tenant STEP 3Check which URL each event goes toa single one per event

What a location is

A location (tenant in the API and the Portal) sends the events of its merchant accounts to its own URL: a branch, a franchise or each customer of your SaaS. With locations you have a single integration, without creating one per customer.

How they relate

Piece	What it is
Integration	Your product. Its credentials, event subscription and signing secret apply to every location.
Location	A `key` you choose, with its webhook URL and an optional validation-token. It only changes where events go.
Merchant account	The one that collects. It's in a single location at a time; a location has many.

Create a location and assign a merchant account

The Tenants section of the Portal appears only on integrations with locations enabled. To enable them, ask support.

In the Portal, under Tenants, create the location with a key (unique per integration), a name, the webhook URL (HTTPS) and, if you want, a validation-token of at least 16 characters. From there you also edit or delete it: a location with assigned accounts can't be deleted.

After connecting the merchant through OAuth, assign it to the location with its id_token, on the Integration API:

cURL

curl -X PUT https://integration-api.test.chytapay.com.ar/my-integration/tenant \
  -H "Authorization: Bearer $ID_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "tenantKey": "sucursal-centro" }'

From then on, that account's events go to the location's URL. You can try it with the test webhook.

Which URL each event goes to

Each event goes to a single URL. The first rule that applies wins:

Situation	Where the event goes
The charge was created with `webhookUrl`	Only to that URL, without `validation-token`. Only for `payment_request.*`: `payment.unmatched` doesn't use it.
The merchant account is in a location	To the location's URL, with its `validation-token`
No location, and the integration has a single URL	To that URL
No location, and the integration has no URL	To none

Warning: An event with no destination is neither sent nor retried. Assign each merchant account to a location before it collects.

All of them are signed with the integration's secret: see Webhooks.

Common errors

See the location errors

Error	When
`409 TenantDuplicateKeyError`	You already have an active location with that `key`: it's unique per integration.
`400 TenantWebhookUrlInvalidError`	The URL points to a private network or can't be validated.
`409 TenantHasBoundUsersError`	The location you want to delete still has merchant accounts.
`404` on `PUT /my-integration/tenant`	The `tenantKey` doesn't exist, was deleted or belongs to another integration. See Operations and errors.

WebhooksSignature, retries and event subscription.CommissionsCharge a commission on every payment.Connect merchant accountsOAuth and tokens.How it worksOne integration and its locations.