Payment instances
Request and manage virtual TPEs — the terminals that accept card payments.
A payment instance is a virtual TPE. It bundles an approved identification, brand, and bank account with a SATIM acceptance license, and is the parent of payment links.
Statuses reference
An instance carries two enums — status (active, suspended) and acceptance_status
(pending_documents, documents_submitted, rejected, ready). Both are defined in
Statuses & enums → Payment instance. It can only
accept payments when acceptance_status is ready.
Endpoints
| Method | Path | Description |
|---|---|---|
GET | /instances | List instances (paginated). |
POST | /instances | Request activation of a new instance. |
GET | /instances/{id} | Retrieve one instance. |
PUT | /instances/{id} | Update an instance. |
DELETE | /instances/{id} | Delete an instance. |
The instance object
| Field | Type | Description |
|---|---|---|
id | string (uuid) | Unique identifier. |
user_id | string (uuid) | Owner. |
title | string | Internal label for the terminal. |
logo | string | null | Public logo URL. |
status | string | Operational status — see statuses. |
acceptance_status | string | License status — see statuses. |
acceptance_reason | string | null | Reason when rejected. |
identification_id / brand_id / bank_account_id | string (uuid) | Backing KYC resources. |
identification / brand / bank_account | object | Nested summaries when loaded. |
created_at / updated_at | string (ISO 8601) | Timestamps. |
List instances
Query parameters: search, status, acceptance_status, identification_id, brand_id,
bank_account_id, sort_by, sort_dir, per_page.
curl "https://api.mytpe.appp/api/ext/instances?acceptance_status=ready&per_page=15" \
-H "X-Api-Key: $MYTPE_API_KEY" \
-H "X-Api-Secret: $MYTPE_API_SECRET"{
"data": [
{
"id": "3e4f5a6b-7c8d-9e0f-1a2b-3c4d5e6f7a8b",
"user_id": "9c1f0e2a-4b6d-4a8e-9f10-2c3d4e5f6a7b",
"title": "Boutique Centrale — Alger",
"logo": null,
"status": "active",
"acceptance_status": "ready",
"acceptance_reason": null,
"identification_id": "0b1d2e3f-4a5b-6c7d-8e9f-0a1b2c3d4e5f",
"brand_id": "1c2d3e4f-5a6b-7c8d-9e0f-1a2b3c4d5e6f",
"bank_account_id": "2d3e4f5a-6b7c-8d9e-0f1a-2b3c4d5e6f7a",
"created_at": "2026-06-09T10:20:00.000000Z",
"updated_at": "2026-06-09T11:00:00.000000Z"
}
],
"links": { "first": "...?page=1", "last": "...?page=1", "prev": null, "next": null },
"meta": { "current_page": 1, "from": 1, "to": 1, "per_page": 15, "last_page": 1, "total": 1 }
}Request activation
Creating an instance submits its documents and opens a transaction for the activation fee. The
response describes that transaction — not yet a usable instance. Send as multipart/form-data.
| Field | Type | Required | Notes |
|---|---|---|---|
title | string | yes | Max 191. |
identification_id | uuid | yes | Must be accepted. |
brand_id | uuid | yes | Must be accepted. |
bank_account_id | uuid | yes | Must be accepted. |
payment_method | enum | yes | online, bank_transfer, or cheque — see payment methods. |
payment_proof | file | no | jpg/png/pdf, max 5 MB. Required for offline methods. |
curl -X POST https://api.mytpe.appp/api/ext/instances \
-H "X-Api-Key: $MYTPE_API_KEY" \
-H "X-Api-Secret: $MYTPE_API_SECRET" \
-F "title=Boutique Centrale — Alger" \
-F "identification_id=0b1d..." \
-F "brand_id=1c2d..." \
-F "bank_account_id=2d3e..." \
-F "payment_method=online"{
"data": {
"transaction_id": "8e7d6c5b-4a39-2817-0f6e-5d4c3b2a1908",
"status": "processing",
"payment_method": "online",
"amount": "3000.00",
"currency": "DZD",
"form_url": "https://gateway.satim.dz/payment/redirect/abc123"
}
}For online, redirect the trader to form_url. For offline methods, a MyTPE officer confirms the
uploaded proof. Watch payment_instance.acceptance_changed for the license reaching ready.
Retrieve an instance
curl https://api.mytpe.appp/api/ext/instances/3e4f5a6b-7c8d-9e0f-1a2b-3c4d5e6f7a8b \
-H "X-Api-Key: $MYTPE_API_KEY" \
-H "X-Api-Secret: $MYTPE_API_SECRET"{
"data": {
"id": "3e4f5a6b-7c8d-9e0f-1a2b-3c4d5e6f7a8b",
"user_id": "9c1f0e2a-4b6d-4a8e-9f10-2c3d4e5f6a7b",
"title": "Boutique Centrale — Alger",
"logo": null,
"status": "active",
"acceptance_status": "ready",
"acceptance_reason": null,
"identification_id": "0b1d2e3f-4a5b-6c7d-8e9f-0a1b2c3d4e5f",
"identification": { "id": "0b1d2e3f-4a5b-6c7d-8e9f-0a1b2c3d4e5f", "name": "Boutique Centrale SARL" },
"brand_id": "1c2d3e4f-5a6b-7c8d-9e0f-1a2b3c4d5e6f",
"brand": { "id": "1c2d3e4f-5a6b-7c8d-9e0f-1a2b3c4d5e6f", "name": "Boutique Centrale" },
"bank_account_id": "2d3e4f5a-6b7c-8d9e-0f1a-2b3c4d5e6f7a",
"bank_account": { "id": "2d3e4f5a-6b7c-8d9e-0f1a-2b3c4d5e6f7a", "account_number": "00799999000123456789", "bank_code": "007" },
"created_at": "2026-06-09T10:20:00.000000Z",
"updated_at": "2026-06-09T11:00:00.000000Z"
}
}Update an instance
Accepts title, identification_id, brand_id, bank_account_id, and a logo file (all
optional). Send as multipart/form-data when including logo.
curl -X PUT https://api.mytpe.appp/api/ext/instances/3e4f5a6b-7c8d-9e0f-1a2b-3c4d5e6f7a8b \
-H "X-Api-Key: $MYTPE_API_KEY" \
-H "X-Api-Secret: $MYTPE_API_SECRET" \
-F "title=Boutique Centrale — Alger Centre" \
-F "logo=@instance-logo.png"{
"data": {
"id": "3e4f5a6b-7c8d-9e0f-1a2b-3c4d5e6f7a8b",
"user_id": "9c1f0e2a-4b6d-4a8e-9f10-2c3d4e5f6a7b",
"title": "Boutique Centrale — Alger Centre",
"logo": "https://api.mytpe.appp/storage/instances/3e4f.../logo.png",
"status": "active",
"acceptance_status": "ready",
"acceptance_reason": null,
"identification_id": "0b1d2e3f-4a5b-6c7d-8e9f-0a1b2c3d4e5f",
"brand_id": "1c2d3e4f-5a6b-7c8d-9e0f-1a2b3c4d5e6f",
"bank_account_id": "2d3e4f5a-6b7c-8d9e-0f1a-2b3c4d5e6f7a",
"created_at": "2026-06-09T10:20:00.000000Z",
"updated_at": "2026-06-09T12:00:00.000000Z"
}
}Delete an instance
curl -X DELETE https://api.mytpe.appp/api/ext/instances/3e4f5a6b-7c8d-9e0f-1a2b-3c4d5e6f7a8b \
-H "X-Api-Key: $MYTPE_API_KEY" \
-H "X-Api-Secret: $MYTPE_API_SECRET"{ "message": "Payment instance deleted." }
Open in Postman