1. Set up your partner account

2. Merchant registration flow

When a merchant chooses to connect Teya in your platform:

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

Example: Registration URL

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.

{
  "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.

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

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

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.

4. API URLs

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'

Hosted Checkout

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

Embedded Components: Checkout

Embedded Components: Card, Split Card, Apple Pay

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