Payment links

A payment link is a shareable URL that charges customers. It is created under a ready payment instance and can optionally use a published form.

Statuses reference

Payment links use three enums — status, amount_mode, and usage_mode — all defined in Statuses and enums → Payment link. Customer payments produce transactions.

Endpoints

Method	Path	Description
`GET`	`/links`	List payment links (paginated).
`POST`	`/links`	Create a link (starts as `draft`).
`GET`	`/links/{id}`	Retrieve one link.
`PUT`	`/links/{id}`	Update a link.
`POST`	`/links/{id}/publish`	Publish a draft (`status` → `active`).
`POST`	`/links/{id}/pause`	Pause an active link.
`POST`	`/links/{id}/resume`	Resume a paused link.
`POST`	`/links/{id}/archive`	Archive a link (terminal).

The payment link object

Field	Type	Description
`id`	string (uuid)	Unique identifier.
`payment_instance_id`	string (uuid)	Parent instance.
`form_id`	string (uuid) \| null	Attached form, if any.
`slug`	string	Used to build the public payment URL.
`title` / `description`	string	Shown on the payment page.
`logo`	string \| null	Public logo URL.
`amount_mode`	string	`fixed` or `open` — see statuses.
`amount` / `min_amount` / `max_amount`	string \| null	Pricing, depending on `amount_mode`.
`currency`	string \| null	3‑letter code (for example, `DZD`).
`usage_mode`	string	How often it can be paid — see statuses.
`max_uses` / `target_amount`	number \| null	Limits for `limited` / `capped_amount`.
`starts_at` / `ends_at` / `expires_at`	string \| null	Window / expiry.
`paid_count`	integer	Successful payments so far.
`total_collected`	string	Sum collected so far.
`status`	string	Lifecycle state — see statuses.
`allowed_payers`	array	Whitelisted payers, when loaded.
`metadata`	object \| null	Your own key/value data, echoed in webhooks.
`created_at` / `updated_at`	string (ISO 8601)	Timestamps.

List payment links

Query parameters: payment_instance_id, status, usage_mode, search, sort_by, sort_dir, per_page.

Request

curl "https://api.mytpe.app/api/ext/links?payment_instance_id=3e4f...&status=active" \
  -H "X-Api-Key: $MYTPE_API_KEY" \
  -H "X-Api-Secret: $MYTPE_API_SECRET"

200 OK

{
  "data": [
    {
      "id": "5a6b7c8d-9e0f-1a2b-3c4d-5e6f7a8b9c0d",
      "payment_instance_id": "3e4f5a6b-7c8d-9e0f-1a2b-3c4d5e6f7a8b",
      "form_id": "4f5a6b7c-8d9e-0f1a-2b3c-4d5e6f7a8b9c",
      "slug": "ord-10428-x9f2",
      "title": "Order #10428",
      "description": null,
      "logo": null,
      "amount_mode": "fixed",
      "amount": "4500.00",
      "min_amount": null,
      "max_amount": null,
      "currency": "DZD",
      "usage_mode": "one_shot",
      "max_uses": null,
      "target_amount": null,
      "starts_at": null,
      "ends_at": null,
      "expires_at": null,
      "paid_count": 0,
      "total_collected": "0.00",
      "status": "active",
      "metadata": { "order_id": "10428" },
      "created_at": "2026-06-09T13:00:00.000000Z",
      "updated_at": "2026-06-09T13:05: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 }
}

Response


Status	`200 OK`
Body	A paginated array of payment link objects.

Errors follow the shared envelope. See Responses.

Create a payment link

Field	Type	Required	Notes
`payment_instance_id`	uuid	yes	Instance must be `ready`.
`title`	string	yes	Max 191.
`description`	string	no	Max 5000.
`form_id`	uuid	no	Must be a published form.
`amount_mode`	enum	yes	`fixed`, `open`.
`amount`	number	conditional	Required when `amount_mode` is `fixed`.
`min_amount` / `max_amount`	number	no	Bounds for `open`.
`currency`	string	no	3 chars.
`usage_mode`	enum	yes	`one_shot`, `limited`, `reusable`, `capped_amount`, `time_window`, `whitelist`.
`max_uses`	integer	conditional	Required when `usage_mode` is `limited`.
`target_amount`	number	conditional	Required when `usage_mode` is `capped_amount`.
`starts_at` / `ends_at`	date	conditional	Required when `usage_mode` is `time_window`.
`expires_at`	date	no	Must be in the future.
`allowed_payers`	array	conditional	Required when `usage_mode` is `whitelist`. Items: `{ email?, phone? }`.
`metadata`	object	no	Your own reference data.

Request

curl -X POST https://api.mytpe.app/api/ext/links \
  -H "X-Api-Key: $MYTPE_API_KEY" \
  -H "X-Api-Secret: $MYTPE_API_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "payment_instance_id": "3e4f5a6b-7c8d-9e0f-1a2b-3c4d5e6f7a8b",
    "title": "Order #10428",
    "amount_mode": "fixed",
    "amount": 4500,
    "currency": "DZD",
    "usage_mode": "one_shot",
    "metadata": { "order_id": "10428" }
  }'

201 Created

{
  "data": {
    "id": "5a6b7c8d-9e0f-1a2b-3c4d-5e6f7a8b9c0d",
    "payment_instance_id": "3e4f5a6b-7c8d-9e0f-1a2b-3c4d5e6f7a8b",
    "form_id": null,
    "slug": "ord-10428-x9f2",
    "title": "Order #10428",
    "description": null,
    "amount_mode": "fixed",
    "amount": "4500.00",
    "min_amount": null,
    "max_amount": null,
    "currency": "DZD",
    "usage_mode": "one_shot",
    "max_uses": null,
    "target_amount": null,
    "paid_count": 0,
    "total_collected": "0.00",
    "status": "draft",
    "metadata": { "order_id": "10428" },
    "created_at": "2026-06-09T13:00:00.000000Z",
    "updated_at": "2026-06-09T13:00:00.000000Z"
  }
}

Response


Status	`201 Created`
Body	The created payment link object, wrapped in `data`. A new link is `draft` until you publish it.

Errors follow the shared envelope. See Responses.

Retrieve a payment link

Request

curl https://api.mytpe.app/api/ext/links/5a6b7c8d-9e0f-1a2b-3c4d-5e6f7a8b9c0d \
  -H "X-Api-Key: $MYTPE_API_KEY" \
  -H "X-Api-Secret: $MYTPE_API_SECRET"

200 OK

{
  "data": {
    "id": "5a6b7c8d-9e0f-1a2b-3c4d-5e6f7a8b9c0d",
    "payment_instance_id": "3e4f5a6b-7c8d-9e0f-1a2b-3c4d5e6f7a8b",
    "form_id": null,
    "slug": "ord-10428-x9f2",
    "title": "Order #10428",
    "amount_mode": "fixed",
    "amount": "4500.00",
    "currency": "DZD",
    "usage_mode": "one_shot",
    "paid_count": 1,
    "total_collected": "4500.00",
    "status": "exhausted",
    "metadata": { "order_id": "10428" },
    "created_at": "2026-06-09T13:00:00.000000Z",
    "updated_at": "2026-06-09T14:30:00.000000Z"
  }
}

Response


Status	`200 OK`
Body	One payment link object, wrapped in `data`.

Errors follow the shared envelope. See Responses.

Update a payment link

Accepts title, description, form_id, max_uses, target_amount, expires_at, metadata.

Request

curl -X PUT https://api.mytpe.app/api/ext/links/5a6b7c8d-9e0f-1a2b-3c4d-5e6f7a8b9c0d \
  -H "X-Api-Key: $MYTPE_API_KEY" \
  -H "X-Api-Secret: $MYTPE_API_SECRET" \
  -H "Content-Type: application/json" \
  -d '{ "title": "Order #10428 (updated)", "metadata": { "order_id": "10428", "channel": "web" } }'

200 OK

{
  "data": {
    "id": "5a6b7c8d-9e0f-1a2b-3c4d-5e6f7a8b9c0d",
    "title": "Order #10428 (updated)",
    "status": "draft",
    "metadata": { "order_id": "10428", "channel": "web" },
    "updated_at": "2026-06-09T13:10:00.000000Z"
  }
}

Response


Status	`200 OK`
Body	The updated payment link object, wrapped in `data`.

Errors follow the shared envelope. See Responses.

Publish, pause, resume

These actions return the updated link.

Request — publish

curl -X POST https://api.mytpe.app/api/ext/links/5a6b7c8d-9e0f-1a2b-3c4d-5e6f7a8b9c0d/publish \
  -H "X-Api-Key: $MYTPE_API_KEY" \
  -H "X-Api-Secret: $MYTPE_API_SECRET"

200 OK

{
  "data": {
    "id": "5a6b7c8d-9e0f-1a2b-3c4d-5e6f7a8b9c0d",
    "slug": "ord-10428-x9f2",
    "status": "active",
    "updated_at": "2026-06-09T13:05:00.000000Z"
  }
}

POST /links/{id}/pause returns the link with status: "paused"; POST /links/{id}/resume returns it back to status: "active".

Response


Status	`200 OK`
Body	The updated payment link object, wrapped in `data`, with `status` set to `active`, `paused`, or `active` respectively. Publishing also locks the slug, which can no longer change.

Errors follow the shared envelope. See Responses.

Archive a payment link

Request

curl -X POST https://api.mytpe.app/api/ext/links/5a6b7c8d-9e0f-1a2b-3c4d-5e6f7a8b9c0d/archive \
  -H "X-Api-Key: $MYTPE_API_KEY" \
  -H "X-Api-Secret: $MYTPE_API_SECRET"

200 OK

{ "message": "Payment link archived." }

amount_mode, amount, and usage_mode are fixed once a link has been paid. To change pricing, archive the link and create a new one.

Response


Status	`200 OK`
Body	The link with `status` now `archived`, wrapped in `data`. Archiving is the end of the lifecycle — links are never deleted, because transactions reference them.

Errors follow the shared envelope. See Responses.

Payment links

On this page