Creating a terminal session

A terminal session is a regular Checkout session with three additions:

A payment profile that enables Card (Present).
The order.store identifiers that route the payment to a specific terminal.
A publish configuration that initiates the payment on the terminal, and configuration.channel: in_store to classify it as an in-store payment.

The sections below cover each piece in order, then bring them together in a full request.

Endpoint

POST https://api.dintero.com/v1/accounts/{account_id}/payments/sessions-profile
Authorization: Bearer <token>
Content-Type: application/json

The Checkout API is now available under https://api.dintero.com/v1/accounts/{account_id}/payments/.The previous https://checkout.dintero.com/v1/ base is still supported, so existing integrations continue to work without changes.

See POST /sessions-profile for the full schema.

1. Enable the payment method (payment profile)

In-person payments are enabled on a payment profile in Dintero Backoffice → Settings → Payment Profiles. Enable Card (Present) on the profile you reference with profile_id, and the session accepts terminal payments without any payment-method configuration in the request body.

Managing payment methods through profiles means you can add or change methods without redeploying integration code. Avoid sending a hardcoded configuration.seitatech block on the request - let the profile drive the payment method.

2. Route to a terminal (`order.store` identifiers)

The payment profile toggles the payment method on; order.store says which physical terminal the payment runs on. The terminal ID belongs in order.store.terminal_id.

{
  "order": {
    "store": {
      "id": "oslo-center",
      "terminal_id": "T0292",
      "payout_destination_id": "seller-1"
    }
  }
}

The three fields are required together for in-person payments:

Field	Description
`order.store.id`	Your merchant store identifier - the `store_id` you sent when creating the store, the same one you already use in the payment-link flow. Not the Dintero-generated `id`.
`order.store.terminal_id`	The `terminal_id` returned when the terminal was registered (for example `P11223351-T0013`). Must be enrolled and linked to the store.
`order.store.payout_destination_id`	The `payout_destination_id` linked to the store.

The order.store.id you use today in the payment-link flow is fine to keep using - in-person payments use the same store identifier. You just need to add terminal_id and payout_destination_id alongside it.

3. Initiate the payment on the terminal (`publish`)

Add a publish push/terminal configuration to the session request to initiate the payment on the terminal as soon as the session is created. Set configuration.channel to in_store as well.

{
  "configuration": {
    "channel": "in_store",
    "publish": [
      {
        "channel": "push",
        "type": "terminal"
      }
    ]
  }
}

This works whether seitatech.in_person is the only enabled payment method or there are other payment methods on the payment profile. The publish configuration initiates the payment on the terminal in both cases.

Sale: full request

This example combines all three pieces to create a session that immediately triggers a payment on terminal T0292 at store oslo-center for 399.00 NOK. The payment profile referenced by profile_id has Card (Present) enabled, and the publish configuration initiates the payment on the terminal.

{
  "url": {
    "return_url": "https://yourpos.example.com/payment/return",
    "callback_url": "https://yourpos.example.com/payment/callback"
  },
  "order": {
    "amount": 39900,
    "currency": "NOK",
    "merchant_reference": "order-12345",
    "items": [
      {
        "id": "sku-coffee-001",
        "line_id": "1",
        "description": "Premium Coffee Beans 1kg",
        "quantity": 2,
        "amount": 39900,
        "vat_amount": 4275,
        "vat": 12
      }
    ],
    "store": {
      "id": "oslo-center",
      "terminal_id": "T0292",
      "payout_destination_id": "seller-1"
    }
  },
  "configuration": {
    "channel": "in_store",
    "publish": [
      {
        "channel": "push",
        "type": "terminal"
      }
    ]
  },
  "profile_id": "your_profile_id"
}

Amounts are in the smallest unit of the currency. 39900 is 399.00 NOK.

After you create the session

Cancelling a payment

Once Dintero starts the transaction on the terminal, you can cancel it in two ways:

From the terminal — the customer or operator cancels directly on the device.
Via the API — call POST /sessions/{session_id}/cancel to cancel the session programmatically.

If the payment is successfully cancelled, the transaction is created with status DECLINED.

Receiving the result

Use the callback_url and webhooks to know when the transaction is authorized and captured. Terminal payments use auto-capture by default. See Checkout webhooks and transaction management.

Refund

seitatech.in_person supports both full and partial refunds. The refund requires a terminal_id in the request body, and the cardholder must be present at the terminal to approve by tapping their card. Refunds use the standard refund endpoint:

POST https://api.dintero.com/v1/accounts/{account_id}/payments/transactions/{transaction_id}/refund
Authorization: Bearer <token>
Content-Type: application/json

{
  "amount": 19950,
  "reason": "Partial return",
  "terminal_id": "T0292",
  "items": [
    {
      "line_id": "1",
      "amount": 19950,
      "quantity": 1
    }
  ]
}

Refund flow

Your server sends the refund request. The API returns 202 Accepted and the transaction receives an INITIATE_REFUND event while the status remains CAPTURED.
The terminal prompts the cardholder to approve the refund by tapping their card.
The refund completes when the cardholder approves, or is voided if they cancel on the terminal.

Terminal requirements

The terminal must be active on the same payout_destination_id as the original transaction. It does not have to be the same terminal that processed the original payment. A valid terminal_id always returns 202 Accepted. If the terminal is offline, the INITIATE_REFUND event expires after 120 seconds and the transaction is updated with a failed refund event.

Use callback_url with report_event=REFUND or a webhooks subscription to receive a notification when the refund status is updated.

Quick reference: answers to common integration questions

Question	Answer
How do I enable in-person payments?	Enable Card (Present) on a payment profile in Backoffice and reference it with `profile_id`.
Where does `terminal_id` go?	`order.store.terminal_id`.
Is `order.store.id` enough?	Yes - reuse the same store ID you already send. Just add `terminal_id` and `payout_destination_id` alongside it.
How do I trigger a sale?	Create the session against an in-person payment profile with the `order.store` identifiers and a `publish` push/terminal configuration. The terminal prompts the customer. Also set `configuration.channel` to `in_store` so the transaction is recorded as an in-store payment.
How do I cancel a payment?	Cancel from the terminal, or call POST /sessions/{session_id}/cancel via the API. The transaction status will be `DECLINED`.
How do I refund?	POST /v1/transactions/{transaction_id}/refund. Both full and partial refunds are supported. Include `terminal_id` in the request body — the cardholder must approve on the terminal.
When is the refund complete?	When the cardholder approves on the terminal. A valid `terminal_id` always returns `202 Accepted`. If the terminal is offline, the `INITIATE_REFUND` event expires after 120 seconds and the transaction is updated with a failed refund event. Use `callback_url` with `report_event=REFUND` or webhooks to get notified.
How do I test a terminal payment?	Use the Visa CDET Android app to simulate contactless test cards against a sandbox terminal. See In-person payment test data.

Checkout Integration

Express Checkout

Payment Methods

Tokenization

Split Payout

In-Person Payments

Endpoint

1. Enable the payment method (payment profile)

2. Route to a terminal (`order.store` identifiers)

3. Initiate the payment on the terminal (`publish`)

Sale: full request

After you create the session

Cancelling a payment

Receiving the result

Refund

Refund flow

Terminal requirements

Quick reference: answers to common integration questions

​Endpoint

​1. Enable the payment method (payment profile)

​2. Route to a terminal (order.store identifiers)

​3. Initiate the payment on the terminal (publish)

​Sale: full request

​After you create the session

​Cancelling a payment

​Receiving the result

​Refund

​Refund flow

​Terminal requirements

​Quick reference: answers to common integration questions

Endpoint

1. Enable the payment method (payment profile)

2. Route to a terminal (`order.store` identifiers)

3. Initiate the payment on the terminal (`publish`)

Sale: full request

After you create the session

Cancelling a payment

Receiving the result

Refund

Refund flow

Terminal requirements

Quick reference: answers to common integration questions