Integration overview

Get your API keys, learn the base URL and auth headers, and understand the order you build things in.

This page gets you from zero to your first authenticated API call, and explains the order the rest of the guide follows.

1. Get your API keys

Every external request is authenticated with an API key + secret pair tied to your trader account.

Generate a key pair

Click Generate. You will receive an api_key and an api_secret.

{
  "api_key": "mtk_live_8f3c1a9b2d4e5f60718293a4b5c6d7e8",
  "api_secret": "mts_live_a1b2c3d4e5f6071829304a5b6c7d8e9f"
}

Store the secret now

The api_secret is shown once. Store it in your server‑side secret manager. If you lose it, revoke the pair and generate a new one.

Treat the secret like a password. Never ship it to a browser, mobile app, or public repository. All external API calls must be made from your backend.

2. Make an authenticated request

The external API lives under /api/ext. Send your key and secret as headers on every request.


Base URL	`https://api.mytpe.appp/api/ext`
Local dev	`http://localhost:8010/api/ext`
Auth headers	`X-Api-Key`, `X-Api-Secret`
Content type	`application/json` (or `multipart/form-data` for file uploads)

Verify your credentials

curl https://api.mytpe.appp/api/ext/me \
  -H "X-Api-Key: $MYTPE_API_KEY" \
  -H "X-Api-Secret: $MYTPE_API_SECRET"

200 OK

{
  "data": {
    "id": "9c1f0e2a-4b6d-4a8e-9f10-2c3d4e5f6a7b",
    "email": "trader@example.com",
    "name": "Boutique Centrale",
    "role": "trader",
    "created_at": "2026-01-12T09:30:00.000000Z"
  }
}

If the credentials are missing or invalid you get 401:

401 Unauthorized

{
  "error": "UNAUTHORIZED",
  "message": "Invalid API credentials."
}

See Authentication for the full details, and Responses for the envelope and error format used everywhere.

3. Build in this order

KYC resources depend on each other, and a payment instance depends on all three. Follow the order below — each step links to its guide.

KYC

Create an identification, then a brand and a bank account under it. Wait for each to reach accepted.

Payment instance

Request activation of a virtual TPE that bundles your approved identification, brand, and bank account. Wait for acceptance_status: ready.

Form (optional)

Create and publish a form if you want to collect data at checkout.

Payment link

Create, publish, and share a link under a ready instance.

Once KYC and a ready instance are in place, every payment you create comes down to three decisions: do you need data from the payer?, how much do they pay?, and how many times / how long can the link be paid? This flowchart walks the whole path and where each decision lands.

Do you need a form?

A form is optional. It only decides whether the payer fills in fields before paying.

No form (anonymous payment). Leave form_id empty. The payer sees only the amount and the card entry — nothing else is collected. Use this for quick charges, donations, or any case where you already know who is paying (or don't need to).
With a form. Attach a published form with form_id to collect structured data at checkout — full name, phone, delivery address, an order reference, or industry‑specific fields. On submit, the answers are stored (encrypted, with an immutable snapshot) and a form.submitted webhook fires.

If you don't attach a form, the payment is automatically anonymous. There's nothing extra to configure — an empty form_id is the anonymous flow.

Choosing the amount mode

You want…	`amount_mode`	Set
A fixed price (an invoice, a product)	`fixed`	`amount`
The payer to choose (tips, donations, top‑ups)	`open`	optional `min_amount` / `max_amount`

Choosing the link type

The usage_mode controls reuse and lifetime. Pick by scenario:

Scenario	`usage_mode`	Notes
One customer pays one invoice, then the link is dead	`one_shot`	Becomes `exhausted` after the first payment.
Sell a fixed quantity (50 workshop seats, 100 tickets)	`limited`	Set `max_uses`; `exhausted` when reached.
A permanent storefront / "pay us" link	`reusable`	Unlimited until you `archive` it.
Raise a target sum, then stop (crowdfund, zakat goal)	`capped_amount`	Set `target_amount`; closes when `total_collected` reaches it.
Only payable during a sale or event	`time_window`	Set `starts_at` / `ends_at`.
Only specific people may pay (private invoices)	`whitelist`	Set `allowed_payers` (email/phone).

See the full value lists in Statuses & enums → Payment link.

Worked example: an e‑commerce order

You sell one order to one customer and need their delivery address. That means a form, a fixed amount, and a one‑shot link.

POST /links

{
  "payment_instance_id": "3e4f5a6b-7c8d-9e0f-1a2b-3c4d5e6f7a8b",
  "title": "Order #10428",
  "form_id": "4f5a6b7c-8d9e-0f1a-2b3c-4d5e6f7a8b9c",
  "amount_mode": "fixed",
  "amount": 4500,
  "currency": "DZD",
  "usage_mode": "one_shot",
  "metadata": { "order_id": "10428" }
}

More example mappings

Use case	Form?	`amount_mode`	`usage_mode`
Online store order with delivery details	Yes	`fixed`	`one_shot`
"Pay your bill" link reused for every client	No (anonymous)	`fixed` or `open`	`reusable`
100 event tickets, ask attendee name	Yes	`fixed`	`limited` (`max_uses: 100`)
Donation drive with a goal	Optional	`open`	`capped_amount`
Flash sale, open Friday only	Optional	`fixed`	`time_window`
Private invoice to two named clients	Yes	`fixed`	`whitelist`

Keep your own IDs mapped

MyTPE generates a UUID for every resource. Store these UUIDs against your own records (orders, customers, stores) so you can reconcile webhooks and reads later.

Save payment_instance.id against the store/branch it represents.
Save payment_link.id against the order/invoice it charges for.
Use the metadata object on payment links to carry your own reference back into every webhook.

You never have to store card data. MyTPE Pay handles the card entry and the gateway redirect; your system only ever sees IDs, statuses, and amounts.