For AI agents: the complete documentation index is at /llms.txt, and the full text of every page is at /llms-full.txt. Most pages are also available as Markdown by adding .md to the URL.

Order a Device

Order and manage devices for in-store payments

Partners can easily order devices that merchants can use for card-present transactions. This guide walks you through how to use our API to place new orders, list all orders for a merchant, and track order statuses — helping you equip your merchants with the right hardware.

Prerequisites

Before starting the steps in this guide, make sure you:

Get set up in our Sandbox test environment:
- Get registered
- Get Partner-level Sandbox test credentials (contact our support team)
- Create an access token
Have boarded at least one merchant under your partnership

Step 1: Initiate a device order

You can place an order directly by sending a request with all required product, shipping, and payment details. A webhook is provided once an order is submitted and an account is created.

Sample request

curl --location --request POST 'https://apis.sandbox.globalpay.com/ucp/MER_c97487d9538044a89588dd67263970c9/orders' \
--header 'X-GP-Version: 2021-03-22' \
--header 'Authorization: Bearer eM1BIwT2CAr1MpC2VlwMvhNXvmy4' \
--header 'Content-Type: application/json' \
--data-raw '{
    "products": [
        {
            "id": "PRO_TRA_CP-US-CARD-A920_SP",
            "device": {
                "quantity": 1,
                "manufacturer_model": "Sample AppA920",
                "account_name_format": "SERIAL_NUMBER"
            }
        }
    ],
    "pricing_profile" : "test",
    "reference" : "12346519681",
    "addresses": [
        {
            "functions": [
                "SHIPPING",
                "BUSINESS"
            ],
            "name": "Paul Blick",
            "email": "shawn.may@globalpay.com",
            "line_1": "525 Animas View Drive",
            "line_2": "#38",
            "line_3": "",
            "city": "Durango",
            "state": "CO",
            "postal_code": "81301",
            "country": "US",
            "contact_phone": {
                "country_code": "01",
                "subscriber_number": "4169490125"
            }
        }
    ],
    "payment_method": {
        "name": "",
        "card": {
            "number": "",
            "cvv": "",
            "expiry_month": "",
            "expiry_year": "",
            "avs_postal_code": ""
        }
    },
    "notifications": {
        "status_url": "https://webhook.site/b9b59cd4-96df-4324-bff2-9ae51d0eb10a/"
    }
}'

Sample response

{
    "id": "ORD_ga1QBDuapiWi6suSUbu7RjiCU1XBLY",
    "merchant_id": "MER_c97487d9538044a89588dd67263970c9",
    "merchant_name": "Halie13",
    "status": "INITIATED",
    "time_created": "2025-04-14T14:25:32.246Z",
    "time_last_updated": "2025-04-14T14:25:32.246Z",
    "action": {
        "id": "ACT_ga1QBDuapiWi6suSUbu7RjiCU1XBLY",
        "type": "ORDER_INITIATED",
        "time_created": "2025-04-14T14:25:32.246Z",
        "result_code": "SUCCESS",
        "app_id": "HNokpqb8huzaGIgBJNTTundAQXIACpDH",
        "app_name": "Sample App"
    }
}

You’ll receive a webhook informing you that the order was initiated successfully. However, to check when the device will actually be shipped, you need to perform a GET request on orders (Step 3) using the Order ID.

Sample webhook notification

{
    "id": "ORD_oAb3WOvM6igWbYwVZAS6tMK5bDRoiy",
    "merchant_id": "",
    "merchant_name": "",
    "status": "",
    "time_created": "",
    "time_last_updated": "",
    "total_amount": "",
    "products": {
    "id": "",
    "name": "",
    "account": {
    "id": "",
    "type": "",
    "name": "",
    "status": "",
   "channel": "",
    "time_created": "",

     "permissions": [],

    "action": {
        "id": "ACT_FW8Ks2fsPYzvOetzYDJ7n7x5nK5Yl7",
        "type": "ORDER_STATUS_NOTIFICATION",
        "time_created": "2023-02-01T15:28:28.049Z",
        "result_code": "SUCCESS",
        "app_id": "U1lRHKomEn7DN907RCDPxVhyMfiMLcfy",
        "app_name": "Sample App"
    }

Step 2: List all orders for a merchant

Next, we retrieve a list of all device orders placed for a specific merchant. This is useful for reporting, auditing, or tracking all order events.

Sample request

curl --location --request GET'https://apis.sandbox.globalpay.com/ucp/MER_c97487d9538044a89588dd67263970c9/orders' \
--header 'X-GP-Version: 2021-03-22' \
--header 'Authorization: Bearer eM1BIwT2CAr1MpC2VlwMvhNXvmy4' \
--header 'Content-Type: application/json'

Sample response

{
    "total_record_count": 8,
    "current_page_size": 5,
    "merchant_id": "MER_c97487d9538044a89588dd67263970c9",
    "merchant_name": "Halie13",
    "account_id": "MMA_fb564ac9d7ea4907aac889c068ee410d",
    "account_name": "Sample App MMA",
    "filter": {
        "from_time_created": "2024-04-14T00:00:00.000Z",
        "to_time_created": "2025-04-14T23:59:59.999Z"
    },
    "paging": {
        "page_size": 5,
        "page": 1,
        "order": "ASC",
        "order_by": "TIME_CREATED"
    },
    "orders": [
        {
            "id": "ORD_lQF1yV2DfNMEl5YzDenX2EJRjH4JFu",
            "merchant_id": "MER_c97487d9538044a89588dd67263970c9",
            "merchant_name": "Halie13",
            "status": "IN_PROGRESS",
            "account_id": "",
            "account_name": "",
            "time_created": "2025-03-21T18:31:05.000Z",
            "time_last_updated": "2025-03-21T18:31:05.000Z",
            "reference": ""
        },
        {
            "id": "ORD_LGSaJFoUZ2JryXkFJ4l2R4SxYo1AaR",
            "merchant_id": "MER_c97487d9538044a89588dd67263970c9",
            "merchant_name": "Halie13",
            "status": "IN_PROGRESS",
            "account_id": "",
            "account_name": "",
            "time_created": "2025-03-21T18:38:27.000Z",
            "time_last_updated": "2025-03-21T18:31:59.000Z",
            "reference": ""
        },
        {
            "id": "ORD_5C7zH3lbpKJXBE8Rg8xWyAg8kuom8b",
            "merchant_id": "MER_c97487d9538044a89588dd67263970c9",
            "merchant_name": "Halie13",
            "status": "IN_PROGRESS",
            "account_id": "",
            "account_name": "",
            "time_created": "2025-03-31T06:53:53.000Z",
            "time_last_updated": "2025-03-31T06:53:53.000Z",
            "reference": ""
        },
        {
            "id": "ORD_60H7yVfr4XBsIRJeibGOUUfcV67jSH",
            "merchant_id": "MER_c97487d9538044a89588dd67263970c9",
            "merchant_name": "Halie13",
            "status": "IN_PROGRESS",
            "account_id": "",
            "account_name": "",
            "time_created": "2025-04-01T11:11:44.000Z",
            "time_last_updated": "2025-03-31T06:54:53.000Z",
            "reference": ""
        },
        {
            "id": "ORD_SLRT0uCrfJMoQOYGYh31LdmjpCitZK",
            "merchant_id": "MER_c97487d9538044a89588dd67263970c9",
            "merchant_name": "Halie13",
            "status": "IN_PROGRESS",
            "account_id": "",
            "account_name": "",
            "time_created": "2025-04-03T01:14:05.000Z",
            "time_last_updated": "2025-04-03T01:14:05.000Z",
            "reference": ""
        }
    ],
    "action": {
        "id": "ACT_TzAvJXCT1CGWKaHOUfmZMsjlSck65q",
        "type": "ORDER_LIST",
        "time_created": "2025-04-14T14:40:15.337Z",
        "result_code": "SUCCESS",
        "app_id": "HNokpqb8huzaGIgBJNTTundAQXIACpDH",
        "app_name": "Sample App"
    }
}

Step 3: Get information about a specific order

Here, we retrieve information about a specific order, including status and tracking number. You can use the Order ID to track the status of an order and check if the device was shipped.

Sample request

curl --location --request GET'https://apis.sandbox.globalpay.com/ucp/MER_c97487d9538044a89588dd67263970c9/orders/ORD_lQF1yV2DfNMEl5YzDenX2EJRjH4JFu' \
--header 'X-GP-Version: 2021-03-22' \
--header 'Authorization: Bearer eM1BIwT2CAr1MpC2VlwMvhNXvmy4' \
--header 'Content-Type: application/json'

Sample response

{
    "id": "ORD_lQF1yV2DfNMEl5YzDenX2EJRjH4JFu",
    "merchant_id": "MER_c97487d9538044a89588dd67263970c9",
    "merchant_name": "Halie13",
    "status": "IN_PROGRESS",
    "tax_amount": "0",
    "tax_percentage": "0",
    "total_amount": "0",
    "account_id": "",
    "account_name": "",
    "time_created": "2025-03-21T18:31:05.000Z",
    "time_last_updated": "2025-03-21T18:31:05.000Z",
    "reference": "",
    "products": [
        {
            "id": "PRO_TRA_CP-US-CARD-A920_SP",
            "name": "Card Present transaction processing on Device A920",
            "quantity": 1,
            "items": [
                {
                    "manufacturer_model": "A920",
                    "account_name_format": "SERIAL_NUMBER",
                    "amount": "0",
                    "serial_number": "",
                    "tracking_reference": ""
                }
            ]
        }
    ],
    "addresses": [
        {
            "functions": [
                "SHIPPING",xz
                "BUSINESS"
            ],
            "name": "john doe",
            "email": "john.doe@email.com",
            "city": "Beverly Hills",
            "state": "CA",
            "country": "US",
            "line_1": "1234 W Main ST",
            "line_2": "",
            "line_3": "",
            "postal_code": "90210",
            "contact_phone": {
                "country_code": "01",
                "subscriber_number": "777777777"
            }
        }
    ],
    "action": {
        "id": "ACT_3iYyAGlR6Q5B871WaFpinLYP5ikLfN",
        "type": "ORDER_SINGLE",
        "time_created": "2025-04-14T14:37:57.428Z",
        "result_code": "SUCCESS",
        "app_id": "HNokpqb8huzaGIgBJNTTundAQXIACpDH",
        "app_name": "Sample App"
    }
}

Integration references

To get a deeper understanding of merchant boarding, we recommend that you use our provided integration references. For the full detailed API specification, see the API Explorer.

/transfers - API Explorer

See the full API specification for creating an access token.

/transactions - API Explorer

See the full API specification for creating a sale or refund.

SDKs & Libraries

Add server-side or client-side code to your integration.

Testing

This solution is available for testing in our free Sandbox environment for registered users of this developer portal. Use our resources below to start testing different scenarios.

Test Cards

Test different transaction outcomes with simulated cards or banks.

Postman Collection

View, import, or fork our API collection in Postman.

Responses

View successful responses, HTTP status codes, action response data, and errors.

Next steps

Below are recommended next steps for your partner integration.

Risk Management

Proactively monitor merchant limits and disputes.

Merchant Management & Reporting

Use account data to better support your merchants.

Initiate a Deposit to Fund Your Merchants

Credit or debit a merchant’s bank account from an ACH deposit.

Policies

Connect

Additional Resources

Order a Device

Prerequisites

Step 1: Initiate a device order

Sample request

Sample response

Sample webhook notification

Step 2: List all orders for a merchant

Sample request

Sample response

Step 3: Get information about a specific order

Sample request

Sample response

Integration references

/transfers - API Explorer

/transactions - API Explorer

SDKs & Libraries

Testing

Test Cards

Postman Collection

Responses

Next steps

Risk Management

Merchant Management & Reporting

Initiate a Deposit to Fund Your Merchants