Maintenance Orders

The Maintenance Orders endpoint allows you to submit hardware service requests for an existing POI device. Supported service types include swaps, repairs, and warranty claims.

How It Works

1

Identify the POI

Retrieve the poiUid for the device requiring maintenance. Use GET /orders/{orderId} or your entity management system to confirm the correct identifier.

2

Submit the maintenance request

POST /pois/orders/maintenance/{poiUid} — Specify the type of maintenance required (swap, repair, warranty) and any supporting details.

3

Track the order

Use GET /orders/{orderId} (see Orders — Common) to monitor the maintenance order status through to completion.

API Reference

POI Maintenance Order Request

POI Maintenance Order Request

post

Submits a POI Maintenance Order Request

Path parameters

poiUidstring · uuidRequired

The Verifone allocated unique id for this terminal/POI. This is allocated by Verifone when an order is initially received.

Example: 04f5ea24-cc4f-11e8-a8d5-f2801f1b9fd1

Body

application/json

orderReferencestring · min: 1Required

Client reference for the Order.

Example: ORD-1234

customerEntityUidstring · uuidRequired

Verifone allocated ID for the customer this order is for (packages and bundles are associated with this entity).

requestedDatestring · date-timeOptional

The requested date for this order.

deferredOrderProcessingDatestring · date-timeOptional

Defers order processing until the specified ISO 8601 UTC datetime (e.g. 2026-06-20T09:00:00Z). The workflow will not start before this point. If absent, processing begins immediately.

Example: 2026-06-20T09:00:00Z

poRefstringOptional

Purchase Order Reference

Example: 85219587

notesstringOptional

Notes for the Order

Example: Current in draft, caller got busy, callback anothertime.

maintenanceTypestring · enumRequiredPossible values:

Responses

201

Create POI Maintenance Order Response

application/json

400

Bad Request

application/json

401

Unauthorised Request

application/json

403

Forbidden Request.

application/json

404

Not Found Request

application/json

429

Too Many Requests

application/json

500

Internal Error

application/json

503

Service Not Available

application/json

504

Service Timeout

application/json

post

/pois/orders/maintenance/{poiUid}

HTTPcURLJavaScriptPython

POST /pois/orders/maintenance/{poiUid} HTTP/1.1
Host: api.verifone.com
Content-Type: application/json
Accept: */*
Content-Length: 570

{
  "orderReference": "ORD-1234",
  "customerEntityUid": "123e4567-e89b-12d3-a456-426614174000",
  "requestedDate": "2026-06-15T14:31:41.658Z",
  "deferredOrderProcessingDate": "2026-06-20T09:00:00Z",
  "poRef": "85219587",
  "paymentDetails": {
    "paymentType": "CREDIT"
  },
  "notes": "Current in draft, caller got busy, callback anothertime.",
  "additionalOrderData": [
    {
      "variableName": "VAT_ID or BAX_ID",
      "variableValue": "1234566"
    }
  ],
  "maintenanceType": "Swapout",
  "deliveryPackage": {
    "packageBundleId": "PREMIUM-36MONTH",
    "additionalPackageData": [
      {
        "variableName": "VAT_ID or BAX_ID",
        "variableValue": "1234566"
      }
    ]
  }
}

{
  "orderReference": "ORD-1234",
  "customerEntityUid": "123e4567-e89b-12d3-a456-426614174000",
  "requestedDate": "2026-06-15T14:31:41.658Z",
  "deferredOrderProcessingDate": "2026-06-20T09:00:00Z",
  "poRef": "85219587",
  "paymentDetails": {
    "paymentType": "CREDIT"
  },
  "notes": "Current in draft, caller got busy, callback anothertime.",
  "additionalOrderData": [
    {
      "variableName": "VAT_ID or BAX_ID",
      "variableValue": "1234566"
    }
  ],
  "maintenanceType": "Swapout",
  "deliveryPackage": {
    "packageBundleId": "PREMIUM-36MONTH",
    "additionalPackageData": [
      {
        "variableName": "VAT_ID or BAX_ID",
        "variableValue": "1234566"
      }
    ]
  },
  "orderId": "32c480b5-4dfb-4c53-959f-49edf45a0931",
  "status": "DRAFT",
  "createdUserUid": "04f5ea24-cc4f-11e8-a8d5-f2801f1b9fd1",
  "createdBy": "text",
  "createdDate": "2026-06-15T14:31:41.658Z",
  "modifiedUserUid": "04f5ea24-cc4f-11e8-a8d5-f2801f1b9fd1",
  "modifiedBy": "text",
  "modifiedDate": "2026-06-15T14:31:41.658Z",
  "orderType": "POIMaintenanceOrder",
  "entityUid": "14f5ea24-cc4f-11e8-a8d5-f2801f1b9fd9",
  "merchantCompanyEntityUid": "14f5ea24-cc4f-11e8-a8d5-f2801f1b9fd9",
  "merchant": {
    "merchantName": "text"
  },
  "internal": {
    "oracleOrderNumber": 1,
    "oracleShippingTrackingReference": "text",
    "kycReportUid": "123e4567-e89b-12d3-a456-426614174000",
    "tokenScopeUid": "123e4567-e89b-12d3-a456-426614174000",
    "extendedDetails": {
      "status": "DRAFT",
      "code": "text",
      "information": "text",
      "lastChangeTime": "2020-01-06T18:16:14.243Z",
      "canCancel": true
    },
    "orderStats": {
      "minsSinceCreatedToLastUpdate": 0,
      "minsSinceLastStatusUpdate": 0
    },
    "vmssApplication": {
      "visaStatus": "NA ",
      "visaMatches": 1,
      "mcdStatus": "NA ",
      "mcdMatches": 1,
      "mcdTransactionReference": "text"
    },
    "salesforceApplicationId": "text",
    "signingInformation": {
      "provider": "SIGNICAT",
      "providerRef": "text",
      "signedFileUrl": "text",
      "signingRequests": [
        {
          "providerRef": "text",
          "contact": {
            "contactType": "BUSINESS",
            "name": {
              "firstName": "text",
              "lastName": "text",
              "prefix": "text",
              "alternateFullName": "text",
              "middleName": "text",
              "suffix": "text"
            },
            "phoneNumbers": [
              {
                "callingCode": "text",
                "value": "text",
                "extension": "text",
                "isPrimary": false,
                "phoneType": "HOME"
              }
            ],
            "email": "[e-mail]",
            "businessTitle": "text"
          },
          "signed": false,
          "signedDateTime": "2026-06-15T14:31:41.658Z",
          "signingLink": "text"
        }
      ]
    },
    "econtractNotificationReminder": {
      "lastNotificationSentDateTime": "2026-06-15T14:31:41.658Z",
      "notificationCount": 1,
      "templateName": "text",
      "notifications": [
        {
          "sentDateTime": "2026-06-15T14:31:41.658Z",
          "template": "text",
          "responseReferenceId": "text"
        }
      ]
    },
    "draftNotificationReminder": {
      "lastNotificationSentDateTime": "2026-06-15T14:31:41.658Z",
      "notificationCount": 1,
      "templateName": "text",
      "notifications": [
        {
          "sentDateTime": "2026-06-15T14:31:41.658Z",
          "template": "text",
          "responseReferenceId": "text"
        }
      ]
    },
    "notificationReminders": {
      "econtract": {
        "lastNotificationSentDateTime": "2026-06-15T14:31:41.658Z",
        "notificationCount": 1,
        "templateName": "text",
        "notifications": [
          {
            "sentDateTime": "2026-06-15T14:31:41.658Z",
            "template": "text",
            "responseReferenceId": "text"
          }
        ]
      },
      "draft": {
        "lastNotificationSentDateTime": "2026-06-15T14:31:41.658Z",
        "notificationCount": 1,
        "templateName": "text",
        "notifications": [
          {
            "sentDateTime": "2026-06-15T14:31:41.658Z",
            "template": "text",
            "responseReferenceId": "text"
          }
        ]
      },
      "docRequired": {
        "lastNotificationSentDateTime": "2026-06-15T14:31:41.658Z",
        "notificationCount": 1,
        "templateName": "text",
        "notifications": [
          {
            "sentDateTime": "2026-06-15T14:31:41.658Z",
            "template": "text",
            "responseReferenceId": "text"
          }
        ]
      }
    },
    "customerOrderLink": {
      "orderLink": "https://example.com",
      "linkInitiatorUserUid": "04f5ea24-cc4f-11e8-a8d5-f2801f1b9fd1",
      "linkInitiatorUsername": "text",
      "linkReceiverUserUid": "04f5ea24-cc4f-11e8-a8d5-f2801f1b9fd1",
      "linkReceiverUsername": "text",
      "linkSendTime": "2026-06-15T14:31:41.658Z",
      "linkOpendByCustomerTime": "2026-06-15T14:31:41.658Z",
      "customerUpdateTime": "2026-06-15T14:31:41.658Z"
    },
    "cancellationHistory": [
      {
        "cancelReasonEnum": "ADMIN_REASON",
        "cancelAdditionalReason": "text",
        "cancelledUserUid": "04f5ea24-cc4f-11e8-a8d5-f2801f1b9fd1",
        "cancelledBy": "text",
        "cancelledDate": "2026-06-15T14:31:41.658Z"
      }
    ],
    "externalOnboarding": {
      "provider": "BANKAXEPT",
      "agreementId": "123e4567-e89b-12d3-a456-426614174000",
      "agreementStatus": "text"
    }
  }
}

Device Exchange

post

Submits a device exchange request, recording the old device being sent for repair and the replacement device being exchanged in. Returns the DID associated with the replacement device.

Body

application/json

oldDeviceSerialNumberstringRequired

Serial number of the device being sent for repair / exchanged out.

newDeviceSerialNumberstringOptional

Serial number of the replacement device being exchanged in.

priorityExchangebooleanRequired

true = Advance Exchange (a new DID is assigned to the replacement device); false = Non-Priority Exchange (the existing DID is retained).

customerEntityUidstring · uuidOptional

Customer entity UID for profile lookup.

Responses

200

Device exchange processed successfully

application/json

400

Bad Request

application/json

404

Not Found Request

application/json

409

Conflict — serial number / DID cross-validation mismatch.

application/json

500

Internal Error

application/json

503

Service Not Available

application/json

post

/devices/exchange

HTTPcURLJavaScriptPython

POST /devices/exchange HTTP/1.1
Host: api.verifone.com
Content-Type: application/json
Accept: */*
Content-Length: 146

{
  "oldDeviceSerialNumber": "text",
  "newDeviceSerialNumber": "text",
  "priorityExchange": true,
  "customerEntityUid": "123e4567-e89b-12d3-a456-426614174000"
}

{
  "deviceId": "text"
}