Confirm the payment

Every integration ends the same way: before you confirm an order to your customer or deliver, your server retrieves the order from myTU and checks its status. A webhook tells you when to do that.

Every payment is an order with one or more transactions. The order stands for what your customer buys. A transaction is a payment attempt for that order, with a specific payment method. Both have a status, and you base your business logic on one of them.

Which status to checkCopy Anchor Link

When to checkCopy Anchor Link

Retrieve the order with GET /v1/orders/{order_id}/ to get the latest status at any moment. To make sure you never miss a status change, combine these three mechanisms:

1. When your customer returns. Retrieve the order as soon as your customer lands on your return_url, and show the result.
2. On a webhook. Retrieve the order when you receive a webhook. Webhooks are fast, but can be delayed or lost because of network problems, so don't rely on them alone.
3. Periodically. Retrieve every order that isn't final yet (new or processing) at a regular interval. Pick an interval that suits your business: if you reserve concert tickets for 15 minutes, check within those 15 minutes.

Retrieve the orderCopy Anchor Link

curl https://api.gw.mytu.co/v1/orders/4c6afd74-a840-4aab-b411-1e6e0636d341/ \
  --user "$API_KEY:"

The response contains the order and all of its transactions. This example shows a completed card payment (shortened):

{
  "id": "4c6afd74-a840-4aab-b411-1e6e0636d341",
  "amount": 100,
  "currency": "EUR",
  "description": "Example order #1",
  "merchant_order_id": "EXAMPLE001",
  "return_url": "https://www.example.com/order/EXAMPLE001",
  "created": "2026-09-20T08:51:10.078503+00:00",
  "completed": "2026-09-20T08:52:02.357623+00:00",
  "status": "completed",
  "transactions": [
    {
      "id": "6a0bdf56-53c3-4ce3-8189-4a73d775ac66",
      "amount": 100,
      "currency": "EUR",
      "payment_method": "credit-card",
      "payment_method_brand": "visa",
      "payment_method_details": {
        "truncated_pan": "414141******4141",
        "vault_token": "e3ed069e-c931-40ae-8035-e022e8a4e5e7"
      },
      "events": [
        {
          "event": "new",
          "id": "3cb2259b-a3f9-4908-bb98-eb51c773fc70",
          "occurred": "2026-09-20T08:51:10.091203+00:00",
          "source": "set_status"
        }
      ],
      "status": "accepted"
    }
  ]
}

See Get an order in the API reference for all fields.

Act on the order status:

See Order and transaction statuses for what every status means.

WebhooksCopy Anchor Link

A webhook is an HTTP POST request that myTU sends to your server every time the status of an order changes. Webhooks keep your system up to date without constant polling, and they matter most when your customer doesn't come back to your website after paying, for example because they closed the browser.

Set the webhook URLCopy Anchor Link

You can set the webhook URL in two places:

curl https://api.gw.mytu.co/v1/orders/ \
  --user "$API_KEY:" \
  --header "Content-Type: application/json" \
  --data '{
    "currency": "EUR",
    "amount": 995,
    "merchant_order_id": "EXAMPLE001",
    "description": "Example order",
    "return_url": "https://www.example.com/order/EXAMPLE001",
    "webhook_url": "https://www.example.com/webhook"
  }'

What you receiveCopy Anchor Link

myTU sends a POST request with a JSON body to your webhook URL:

POST /webhook HTTP/1.1
Host: www.example.com
Content-Type: application/json

{
  "event": "status_changed",
  "order_id": "4c6afd74-a840-4aab-b411-1e6e0636d341",
  "project_id": "b5f39273-44e7-4385-8e08-44612ef3e117"
}

event is always status_changed: the status of the order with the order_id changed. See Order status changed in the API reference.

The webhook deliberately doesn't contain the status. Retrieve the order and act on the status in that response, so you only act on data that comes from myTU directly.

Respond to the webhookCopy Anchor Link

Respond with HTTP status 200 OK. The response body can be empty: myTU ignores it.

Delivery counts as failed when:

• your server responds with a 4xx or 5xx status code;
• connecting to your webhook URL times out;
• reading the response from your server times out;
• your server refuses the connection.

The timeout for connecting and reading is 4 seconds for the first attempt and 10 seconds for every retry. Respond quickly: if you need to do heavy work, store the notification and process it in the background.

RetriesCopy Anchor Link

After a failed delivery, myTU retries the webhook every 2 minutes. After the 10th failed attempt, myTU stops trying.

Example handlerCopy Anchor Link

This handler retrieves the order and stores its status. updateOrderInYourShop and update_order_in_your_shop stand for your own code:

import express from 'express';

const app = express();
app.use(express.json());

const authorization = `Basic ${Buffer.from(`${process.env.API_KEY}:`).toString('base64')}`;

app.post('/webhook', async (req, res) => {
  try {
    const response = await fetch(`https://api.gw.mytu.co/v1/orders/${req.body.order_id}/`, {
      headers: { Authorization: authorization },
    });
    if (!response.ok) throw new Error(`Status request failed: ${response.status}`);

    const order = await response.json();
    await updateOrderInYourShop(order.merchant_order_id, order.status);
    res.sendStatus(200);
  } catch (error) {
    console.error(error);
    res.sendStatus(500); // myTU retries the webhook
  }
});

app.listen(3000);

Best practicesCopy Anchor Link

• Make your handler idempotent. Because of retries, you can receive the same notification more than once. Processing it twice must not, for example, ship an order twice.
• Always fetch the order. Never derive the status from the webhook itself.
• Have a backup. A webhook can be delayed or lost. Regularly retrieve orders that aren't final yet, as described in When to check.
• Allow the traffic. If a firewall, WAF or bot protection runs in front of your server, make sure it doesn't block webhook requests.
• Use HTTPS for your webhook URL.