Agency-Phone Custom Apps

🧩 Build a custom app for Agency-Phone

There are two ways to put an app on the phone. Pick the one that fits you:

If you ship an app to other servers, use Method A. It needs no source from us and keeps working across updates.

A SDK: register an app from your own resource

agency-phone exposes exports that let any resource put an app with its own icon on the phone home screen at runtime. Your app's interface lives in your own resource; the phone shows the icon and hands control to you when the player taps it. No edits to agency-phone, no unlocked build.

Minimal example

-- client side of YOUR resource
CreateThread(function()
    Wait(1500) -- let agency-phone boot
    exports['agency-phone']:RegisterApp({
        id        = 'myshop',
        label     = 'My Shop',
        icon      = 'fa-solid fa-cart-shopping', -- FontAwesome 6 class
        -- image  = 'https://cfx-nui-myresource/icon.png', -- or your own image instead
        color     = '#ff9500',
        colorDark = '#e08600',
    })
end)

-- fired when the player taps your icon on the phone
AddEventHandler('agency-phone:client:openApp', function(appId)
    if appId ~= 'myshop' then return end
    exports['agency-phone']:ClosePhone()
    -- open your own NUI here
end)

RegisterApp config

SDK exports (client)

The tap event

When the player taps your icon, agency-phone fires both of these on the client. Use whichever you prefer:

Add dependency 'agency-phone' to your fxmanifest.lua so the start order is correct.

B Drop-in, a native screen inside the phone

For a screen rendered by the phone itself (not your resource). This edits agency-phone's own files.

Steps 3 and 4 live in escrow-encrypted files, so a native screen needs a source / unlocked build. If you only have the escrow version, use Method A instead (your screen lives in your own resource). Reference files inside the resource: apps/testapp_client.lua and apps/dispatch_client.lua.

📋 Other phone exports

Client

Server

⇄ NUI ↔ Lua bridge (Method B)

💳 AgencyPay checkout

Charge the player's wallet from any resource.

exports['agency-phone']:StartAgencyPayCheckout({
    merchant = 'My Shop', title = 'Agency Pay', subtitle = 'Checkout',
    label = 'Premium Coffee', amount = 24.50,
    icon = 'fa-solid fa-mug-hot', accent = '#ff9f0a',
    clientEvent = 'myshop:client:agencyPayResult',
    serverEvent = 'myshop:server:agencyPayResult',
    metadata = { orderId = 'order_2048' },
})

RegisterNetEvent('myshop:client:agencyPayResult', function(result)
    if result.status == 'paid' then
        -- deliver the goods
    end
end)

The result payload includes status (paid / cancelled / failed), amount, cardId, balance and your metadata.

A paid result that reaches your resource from the client proves nothing on its own. Pass your own id to StartAgencyPayCheckout and call exports['agency-phone']:VerifyAgencyPayCharge(source, id, amount) on the server before you hand anything out. It returns true and the amount only if this player paid that checkout in the last 60 seconds, and it uses the charge up, so the same payment cannot be claimed twice.

🐛 Troubleshooting

Questions, or need a hand? Join the Agency Scripts Discord.