Forms

A form is a reusable set of fields collected from the payer at checkout. Build it from sections and fields, publish it, then attach it to a payment link via form_id.

Statuses reference

Form status (draft, published, archived) and field data_type values are defined in Statuses & enums → Forms.

Endpoints

Method	Path	Description
`GET`	`/forms`	List forms (paginated).
`POST`	`/forms`	Create a form (`draft`).
`GET`	`/forms/{id}`	Retrieve a form with sections and fields.
`PATCH`	`/forms/{id}`	Update a form.
`POST`	`/forms/{id}/publish`	Publish a form.
`DELETE`	`/forms/{id}`	Delete a form.
`POST`	`/forms/{id}/sections`	Add a section.
`PATCH`	`/forms/{id}/sections/{sectionId}`	Update a section.
`DELETE`	`/forms/{id}/sections/{sectionId}`	Remove a section.
`POST`	`/forms/{id}/fields`	Add a field.
`PATCH`	`/forms/{id}/fields/{fieldId}`	Update a field.
`DELETE`	`/forms/{id}/fields/{fieldId}`	Remove a field.

The form object

Field	Type	Description
`id`	string (uuid)	Unique identifier.
`trader_id`	string (uuid)	Owner.
`name`	string	Form name.
`description`	string \| null	Optional description.
`industry`	string \| null	Optional industry tag.
`status`	string	`draft`, `published`, `archived` — see statuses.
`is_template`	boolean	Whether this form is a template.
`template_id`	string \| null	Source template if cloned.
`meta`	object	Arbitrary metadata.
`sections`	array	Ordered sections (`{ id, form_id, title, description, position }`).
`fields`	array	Ordered fields (see field object below).
`created_at` / `updated_at`	string (ISO 8601)	Timestamps.

List forms

Request

curl "https://api.mytpe.appp/api/ext/forms?per_page=15" \
  -H "X-Api-Key: $MYTPE_API_KEY" \
  -H "X-Api-Secret: $MYTPE_API_SECRET"

200 OK

{
  "data": [
    {
      "id": "4f5a6b7c-8d9e-0f1a-2b3c-4d5e6f7a8b9c",
      "trader_id": "9c1f0e2a-4b6d-4a8e-9f10-2c3d4e5f6a7b",
      "name": "Checkout details",
      "description": null,
      "industry": "ecommerce",
      "status": "published",
      "is_template": false,
      "template_id": null,
      "meta": [],
      "created_at": "2026-06-09T12:00:00+00:00",
      "updated_at": "2026-06-09T12:30:00+00:00"
    }
  ],
  "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 }
}

Create a form

Field	Type	Required	Notes
`name`	string	yes	Max 255.
`description`	string	no	Max 2000.
`industry`	string	no	Max 50.
`meta`	object	no

Request

curl -X POST https://api.mytpe.appp/api/ext/forms \
  -H "X-Api-Key: $MYTPE_API_KEY" \
  -H "X-Api-Secret: $MYTPE_API_SECRET" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Checkout details", "industry": "ecommerce" }'

201 Created

{
  "data": {
    "id": "4f5a6b7c-8d9e-0f1a-2b3c-4d5e6f7a8b9c",
    "trader_id": "9c1f0e2a-4b6d-4a8e-9f10-2c3d4e5f6a7b",
    "name": "Checkout details",
    "description": null,
    "industry": "ecommerce",
    "status": "draft",
    "is_template": false,
    "template_id": null,
    "meta": [],
    "sections": [],
    "fields": [],
    "created_at": "2026-06-09T12:00:00+00:00",
    "updated_at": "2026-06-09T12:00:00+00:00"
  }
}

Retrieve a form

Returns the form with its sections and fields loaded.

Request

curl https://api.mytpe.appp/api/ext/forms/4f5a6b7c-8d9e-0f1a-2b3c-4d5e6f7a8b9c \
  -H "X-Api-Key: $MYTPE_API_KEY" \
  -H "X-Api-Secret: $MYTPE_API_SECRET"

200 OK

{
  "data": {
    "id": "4f5a6b7c-8d9e-0f1a-2b3c-4d5e6f7a8b9c",
    "name": "Checkout details",
    "status": "published",
    "is_template": false,
    "meta": [],
    "sections": [
      { "id": "7c8d...", "form_id": "4f5a...", "title": "Delivery", "description": null, "position": 1 }
    ],
    "fields": [
      {
        "id": "9e0f...",
        "form_section_id": "7c8d...",
        "input_name": "wilaya",
        "label": "Wilaya",
        "help_text": null,
        "data_type": "select",
        "is_required": true,
        "validation_rules": null,
        "options": [{ "value": "16", "label": "Alger" }],
        "meta": [],
        "position": 1
      }
    ],
    "created_at": "2026-06-09T12:00:00+00:00",
    "updated_at": "2026-06-09T12:30:00+00:00"
  }
}

Update a form

Accepts the same fields as create.

Request

curl -X PATCH https://api.mytpe.appp/api/ext/forms/4f5a6b7c-8d9e-0f1a-2b3c-4d5e6f7a8b9c \
  -H "X-Api-Key: $MYTPE_API_KEY" \
  -H "X-Api-Secret: $MYTPE_API_SECRET" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Checkout details v2" }'

200 OK

{
  "data": {
    "id": "4f5a6b7c-8d9e-0f1a-2b3c-4d5e6f7a8b9c",
    "name": "Checkout details v2",
    "status": "draft",
    "updated_at": "2026-06-09T12:40:00+00:00"
  }
}

Add a section

Field	Type	Required
`title`	string	yes
`description`	string	no
`position`	integer	no

Request

curl -X POST https://api.mytpe.appp/api/ext/forms/4f5a.../sections \
  -H "X-Api-Key: $MYTPE_API_KEY" \
  -H "X-Api-Secret: $MYTPE_API_SECRET" \
  -H "Content-Type: application/json" \
  -d '{ "title": "Delivery", "position": 1 }'

201 Created

{
  "data": {
    "id": "7c8d9e0f-1a2b-3c4d-5e6f-7a8b9c0d1e2f",
    "form_id": "4f5a6b7c-8d9e-0f1a-2b3c-4d5e6f7a8b9c",
    "title": "Delivery",
    "description": null,
    "position": 1
  }
}

PATCH /forms/{id}/sections/{sectionId} updates a section and returns the same shape. DELETE /forms/{id}/sections/{sectionId} removes it and returns { "message": "Section removed." }.

Add a field

Field	Type	Required	Notes
`input_name`	string	yes	Machine name (e.g. `full_name`).
`label`	string	yes	Shown to the payer.
`data_type`	enum	yes	See field types.
`is_required`	boolean	no
`help_text`	string	no
`validation_rules`	string	no	Extra Laravel‑style rules.
`options`	array	conditional	Required for `select`, `multi_select`, `radio`, `checkbox`. Items: `{ value, label }`.
`form_section_id`	uuid	no	Place the field in a section.
`position`	integer	no	Ordering.
`meta`	object	no

Request

curl -X POST https://api.mytpe.appp/api/ext/forms/4f5a.../fields \
  -H "X-Api-Key: $MYTPE_API_KEY" \
  -H "X-Api-Secret: $MYTPE_API_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "input_name": "wilaya",
    "label": "Wilaya",
    "data_type": "select",
    "is_required": true,
    "options": [{ "value": "16", "label": "Alger" }]
  }'

201 Created

{
  "data": {
    "id": "9e0f1a2b-3c4d-5e6f-7a8b-9c0d1e2f3a4b",
    "form_section_id": null,
    "input_name": "wilaya",
    "label": "Wilaya",
    "help_text": null,
    "data_type": "select",
    "is_required": true,
    "validation_rules": null,
    "options": [{ "value": "16", "label": "Alger" }],
    "meta": [],
    "position": 1
  }
}

PATCH /forms/{id}/fields/{fieldId} updates a field and returns the same shape. DELETE /forms/{id}/fields/{fieldId} removes it and returns { "message": "Field removed." }.

Publish a form

Request

curl -X POST https://api.mytpe.appp/api/ext/forms/4f5a.../publish \
  -H "X-Api-Key: $MYTPE_API_KEY" \
  -H "X-Api-Secret: $MYTPE_API_SECRET"

200 OK

{
  "data": {
    "id": "4f5a6b7c-8d9e-0f1a-2b3c-4d5e6f7a8b9c",
    "name": "Checkout details",
    "status": "published",
    "updated_at": "2026-06-09T12:45:00+00:00"
  }
}

Only a published form can be attached to a payment link.

Delete a form

Request

curl -X DELETE https://api.mytpe.appp/api/ext/forms/4f5a6b7c-8d9e-0f1a-2b3c-4d5e6f7a8b9c \
  -H "X-Api-Key: $MYTPE_API_KEY" \
  -H "X-Api-Secret: $MYTPE_API_SECRET"

200 OK

{ "message": "Form deleted." }

On submission, MyTPE stores an immutable snapshot of the form alongside the (encrypted) answers and fires a form.submitted webhook event.

Forms

On this page