Register Your Merchants

Set up your partner account and implement the merchant registration flow. Teya sends each merchant's credentials to your registration webhook so you can take payments on their behalf.

1. Set up your partner account

1 Coordinate with Teya to set up a partner test account and a Staging company/store

2 Get access to the plugin registration endpoints

3 Implement the registration webhook endpoint on your platform

2. Merchant registration flow

When a merchant chooses to connect Teya in your platform:

1 Redirect merchant to Teya registration page

2 Merchant signs in with Teya ID & selects store

3 Teya sends credentials to your registrationWebhook

4 Verify signature, store credentials, enable payments

Build the registration URL using the appropriate environment endpoint and append these query parameters:

Parameter	Required	Description
`registrationWebhook`	Yes	HTTPS URL that receives `store_id`, `client_id`, `client_secret`, and `payment_webhook_public_key`
`paymentsWebhook`	Recommended	HTTPS URL to receive payment events
`pluginType`	Yes	Identifier for your platform (e.g. `WOOCOMMERCE`, `SHOPIFY`) See notes below for use in development and production
`pluginVersion`	No	Your plugin version (e.g. `1.0.0`)
`state`	Recommended	An opaque string you generate (e.g. a random nonce or session token). Teya returns it unchanged in the signed registration webhook payload so you can verify the callback originated from a request you initiated (CSRF protection). We recommend expiring the state after 10 minutes if no callback is received from Teya

```admonition icon: fas fa-info-circle title: Plugin type for production content: During development, use TESTING as the pluginType. When you are ready to go live, contact us at partnersupport@teya.com to be assigned a dedicated ENUM for your plugin. ```

Example: Registration URL

```text https://business.teya.xyz/ecom/plugin-registration ?registrationWebhook=https://yourplatform.com/api/teya/register &paymentsWebhook=https://yourplatform.com/api/teya/webhooks &pluginType=TESTING &pluginVersion=1.0.0 &state=a1b2c3d4e5f6 ```

Redirect the merchant to this URL. After the merchant signs in and selects their store, Teya POSTs credentials to your registrationWebhook.

Example: Registration webhook payload

Teya POSTs the following JSON to your registrationWebhook endpoint. Verify the x-teya-signature header (SHA256withRSA, Base64 encoded) before trusting the payload.

```json { "store_id": "550e8400-e29b-41d4-a716-446655440000", "client_id": "ecom_abc123", "client_secret": "secret_xyz789", "payment_webhook_public_key": "-----BEGIN PUBLIC KEY-----\nMIIBIjANBgkqh...\n-----END PUBLIC KEY-----", "state": "a1b2c3d4e5f6" } ```

Your endpoint should return 200 OK to acknowledge receipt. Verify that state matches the value you originally sent in the registration URL before trusting the payload. The store_id identifies the store the merchant selected, so you can link the credentials to the correct store. Store the credentials securely and use them to authenticate API requests on behalf of this merchant.

```admonition icon: fas fa-exclamation-triangle title: Keep credentials secure content: Store client_secret and payment_webhook_public_key in encrypted configuration or a secrets store. Never expose them in client-side code. ``` ```admonition icon: fas fa-key title: A separate Client ID and Client Secret per merchant content: Unlike POSLink credentials, these aren't shared across your merchant base. Each merchant gets its own Client ID and Client Secret via this webhook - keep each merchant's credentials separate and don't reuse one set across multiple merchants. ```

3. Deactivate credentials

Every registration creates a brand new pair of credentials. Teya does not reuse or replace the old ones, so a store that registers twice ends up with two working sets of credentials.

Call the deactivation endpoint whenever a set of credentials is no longer needed - for example when a merchant disconnects Teya in your platform, uninstalls your plugin, or registers the same store again.

Deactivating a registration:

Revokes the client_id and client_secret, so they can no longer be used to get an access token
Deletes the webhooks created during that registration, so no more payment events are sent to the endpoint you registered

Example: Deactivate a registration

```bash curl -X DELETE 'https://api.teya.xyz/v1/ecommerce/registrations/current' \ -H 'Authorization: Bearer ' ```

There is no ID in the path. The endpoint always acts on the registration behind the access token you send, so use the credentials you want to deactivate to request that token.

Response	Meaning
`204`	The credentials were deactivated and the webhooks were deleted
`401`	The access token is missing or invalid
`403`	The token is missing the `ecommerce/registrations/current` scope, or the credentials were already deactivated

```admonition icon: fas fa-exclamation-triangle title: Deactivation cannot be undone content: Once credentials are deactivated they cannot be brought back. To reconnect the store, send the merchant through the registration flow again to get a new pair of credentials. ```

4. API URLs

Service	Staging	Production
Online Payments API	`https://api.teya.xyz`	`https://api.teya.com`
OAuth	`https://id.teya.xyz/oauth/v2/oauth-token`	`https://id.teya.com/oauth/v2/oauth-token`
Registration	`https://business.teya.xyz/ecom/plugin-registration`	`https://business.teya.com/ecom/plugin-registration`
Signature Public Key	`https://cdn.teya.xyz/dynamic/4eb143f2/public-key`	`https://cdn.teya.com/dynamic/4eb143f2/public-key`

5. Required scopes by product

Request the scopes for the products you integrate as a space-separated string in your OAuth token request.

Pay By Link

scope: 'payment-links/create payment-links/id/get payment-links/id/update ecommerce/registrations/current'

Scope	Description
`payment-links/create`	Create a payment link
`payment-links/id/get`	Get payment link by ID
`payment-links/id/update`	Update a payment link
`ecommerce/registrations/current`	Deactivate the registration and its credentials

Hosted Checkout

scope: 'checkout/sessions/create checkout/sessions/id/get refunds/create ecommerce/registrations/current'

Scope	Description
`checkout/sessions/create`	Create a hosted checkout session
`checkout/sessions/id/get`	Get hosted checkout session by ID
`refunds/create`	Issue a refund for a completed payment
`ecommerce/registrations/current`	Deactivate the registration and its credentials

Embedded Components: Checkout

Scope	Description
`checkout/sessions/create`	Create a checkout session for the SDK
`checkout/sessions/id/get`	Get checkout session by ID
`ecommerce/registrations/current`	Deactivate the registration and its credentials

Embedded Components: Card, Split Card, Apple Pay

Scope	Description
`transactions/online/create`	Process an online transaction
`transactions/online/id/get`	Get online transaction details
`checkout/sessions/create`	Create a session for the SDK
`ecommerce/registrations/current`	Deactivate the registration and its credentials

Next steps

Pay By Link via API - Create payment links programmatically
Hosted Checkout - Redirect customers to a Teya-hosted payment page
Embedded Components - Embed payment fields in your own UI
Webhooks - Receive payment notifications
Testing - Test cards and integration checklist
API Reference - Full API endpoint documentation