Terminal onboarding - Dintero Documentation

Before you can charge a customer on a terminal, the terminal has to be linked to a store, and the store has to be linked to a payout destination. You can complete the whole onboarding in Backoffice, or automate the store and terminal steps via the management API.

Step 1: Onboard a payout destination

The payout destination is the seller of record - the entity that receives the funds. KYC is a one-time step per legal entity.

Backoffice
Management API

Go to Settings → Sellers and click Add new Seller.
Provide the company or individual details and click Continue. A link is generated to complete the declaration form and sign the agreement.
Open the link and complete the declaration form and sign the agreement. The seller is ready when case_status becomes ACTIVE.
Note the payout_destination_id. You’ll send this as order.store.payout_destination_id when creating sessions.

Create a payout destination with POST /accounts/{aid}/management/settings/approvals/payout-destinations.

POST /accounts/{aid}/management/settings/approvals/payout-destinations
Authorization: Bearer <token>
Content-Type: application/json

{
  "payout_destination_id": "my-seller",
  "payout_reference": "My Company AS",
  "organization_number": "923663487",
  "country_code": "NO",
  "bank_accounts": [
    {
      "bank_account_number": "12345678901",
      "bank_account_currency": "NOK"
    }
  ],
  "form_submitter": {
    "email": "contact@example.com"
  }
}

Open the URL in the response links array to complete the declaration form and sign the agreement.Track approval status by:

Webhook: subscribe to approval_payout_destination_update. The payout destination is ready when case_status is ACTIVE.
Polling: GET /accounts/{aid}/management/settings/approvals/payout-destinations

For more detail on the KYC flow and reminder emails, see Add sellers.

Step 2: Create a store

A store represents a physical location. Stores are linked to one payout destination.

Backoffice
Management API

Go to Settings → Stores and add a new store.
Link the store to the payout destination you onboarded in step 1.
Note the store_id. You’ll send this as order.store.id.

Create a store with POST /v1/accounts/{aid}/stores.

POST /v1/accounts/{aid}/stores
Authorization: Bearer <token>
Content-Type: application/json

{
  "store_id": "oslo-center",
  "store_name": "Oslo Center",
  "organization": {
    "organization_number": "923663487"
  },
  "payout_destination": {
    "payout_destination_id": "seller-1"
  }
}

The response returns two identifiers:

store_id - the merchant identifier you sent, used as order.store.id in checkout sessions.
id - a Dintero-generated identifier (for example P11223351-0026). You’ll need this when registering a terminal.

When a store is linked to an active payout destination, address, phone number, and other fields are set automatically from the validated organization data. The store’s organization.organization_number must match the organization on the payout destination.

Step 3: Register a terminal

A terminal is a physical card reader. Each terminal is linked to a single store.

Backoffice
Management API

Go to Settings → Terminals and add a new terminal.
Provide the device serial number.
Link the terminal to the store from step 2.
Note the terminal_id. You’ll send this as order.store.terminal_id.

POST /v1/accounts/{aid}/terminals
Authorization: Bearer <token>
Content-Type: application/json

{
  "device_serial_number": "158222607285",
  "store_id": "P11223351-0026"
}

The store_id field on this endpoint expects the store’s id from the create-store response (for example P11223351-0026), not the merchant store_id. Subsequent reads of the terminal will return the merchant store_id (the backend translates it).

The response includes the terminal_id Dintero assigned (for example P11223351-T0013). Use that value as order.store.terminal_id when creating a session.Use GET /v1/accounts/{aid}/terminals/{terminal_id} to inspect a terminal, or GET /v1/accounts/{aid}/terminals to list all terminals.

Terminal statuses

Check the current status with GET /v1/accounts/{aid}/terminals/{terminal_id}.

`PENDING`

The terminal has been registered and is waiting to be provisioned. No action is required. The status will update automatically.

`ACTION_REQUIRED`

The terminal needs to fetch its configuration before it can be activated. When status_reason is CHECK_UPDATE, perform these steps first:

Connect the terminal to a Wi-Fi network.
Fetch the settings from the terminal’s service menu: Service → enter service password → Get settings. The service password is a rotating code you can find in Backoffice or request from Dintero support.

Then trigger the check update:

Backoffice
API

Open the terminal in Settings → Terminals and click Check update. The terminal contacts Seitatech to fetch its configuration.

Send a check_update operation with POST /v1/admin/terminals/operations:

POST /v1/admin/terminals/operations
Authorization: Bearer <token>
Content-Type: application/json

{
  "terminal_id": "P11223351-T0013",
  "operation": "check_update"
}

The command is dispatched asynchronously.

`ACTIVE`

The terminal is provisioned and ready to accept payments.

`ERROR`

Provisioning failed. Retry the onboarding or contact Dintero support.

Next step

With the payout destination, store, and terminal in place, you can now create a session that drives the terminal.

​Step 1: Onboard a payout destination

​Step 2: Create a store

​Step 3: Register a terminal

​Terminal statuses

​PENDING

​ACTION_REQUIRED

​ACTIVE

​ERROR

​Next step

Step 1: Onboard a payout destination

Step 2: Create a store

Step 3: Register a terminal

Terminal statuses

`PENDING`

`ACTION_REQUIRED`

`ACTIVE`

`ERROR`

Next step