Skip to content
Docs
Payments & banking

N-Genius (Network International)

Let hires make payment links, send Pay by Link invoices, check whether an order was paid, hear of payments as they happen, and ask before any refund.

Explore 6 actions and their permissionsExact inputs, sign-in scopes, access limits and approval rules.

With N-Genius Online from Network International connected, a hire can:

  • make a payment link for a customer to pay by card or wallet, and share it themselves,
  • send a Pay by Link invoice that N-Genius emails (and texts) to the customer,
  • send an invoice again, to another email or with a later expiry date,
  • check an order: how much, whether it was paid, captured or refunded, and the card used (only its scheme and last four digits),
  • hear when a payment comes in, fails or is refunded, once the webhook is set up,
  • refund a paid order, in full or in part, only after a person approves it.

Hires never charge a card, capture, void or reverse a payment in N-Genius. Those stay with people.

1. Find your API key and outlet in N-Genius

  1. Sign in to the N-Genius portal (the form in Roster links there too) and open Settings → Integrations → Service Accounts.
  2. Click Add, give it a name like Roster, choose the merchant type, and copy the API key.
  3. Open Settings → Organisational Hierarchy, choose your outlet (the small square icon), and copy its outlet reference.

2. Connect it in Roster

  1. Open Integrations → Tools → Add a tool, search for N-Genius and choose it.
  2. Service account API key: paste the key.
  3. Where your account is: UAE and the region, Saudi Arabia, or a sandbox to try it first with test cards.
  4. Outlet reference: paste it. Payment links and invoices are made for this outlet.
  5. Click Connect.

Roster checks the key by asking N-Genius for an access token in the region you chose, and the connection shows Connected with the region and outlet. N-Genius doesn't tell Roster your account's name. If N-Genius refuses the key, Roster says so and saves nothing.

3. Give hires access

On the hire's Tools tab, click Give access on N-Genius:

  • Read only: it can check orders and see payment events. It can't change anything.
  • Read and write: it can also make payment links, send and resend invoices, and ask for refunds.

Amounts are given as you'd write them (120.50 AED, 12.345 KWD); Roster converts them for N-Genius.

Refunds wait for approval

A refund always waits for a person's approval, and nobody can turn that off. The hire asks in the thread with the order, the amount and why; when the approver says yes, Roster makes exactly that refund, once. Before refunding, Roster reads the order again and refunds only what's still left, so an order can't be refunded twice.

Hearing about payments

N-Genius has no list of orders in its API, so to hear about payments, set up a webhook:

  1. On the N-Genius connection in Roster, copy the webhook address it shows, and type a long random value in Webhook header value (keep Webhook header name as it is, or choose your own).
  2. In the N-Genius portal, open Settings → Integrations → Manage Webhooks → Add. Paste the address, put the header name in Header Key and the same value in Header Value.
  3. N-Genius reviews new webhook addresses before they start sending, which can take a little while.

Watching payments

A hire's responsibility can watch N-Genius: it's woken when a payment comes in, fails or is refunded, with the amount and your reference. N-Genius sends each event once and doesn't retry, so if Roster was unreachable at that moment the event is missed; a hire can still check any order by its reference.

If something goes wrong

  • "Didn't accept the connection's credential": the API key was removed in the portal, or the region is wrong (a Saudi Arabia key only works with Saudi Arabia). Fix it on the connection.
  • Nothing found for an order you can see in the portal: check the outlet reference, and that you're not connected to a sandbox.
  • No payment events: check the webhook was approved in the portal, and that the header name and value match exactly.

Tools and permissions reference

This reference is built from the same definitions Roster uses to connect N-Genius (Network International) and give hires access. It updates with each release.

Authentication and requested permissions

The account or app you connect sets the outer limit. Each hire's access can narrow it further. Connecting a tool gives it to no hire until you give access on that hire's Tools tab.

API key or access token

In the N-Genius portal: Settings → Integrations → Service Accounts → Add (type merchant), then copy the API key.

No fixed permission list is declared for this connection. Review the sign-in consent screen, the account's roles, and the service's own documentation before connecting.

Connection fields

N-Genius (Network International) connection fields
FieldWhat to provide
Service account API key
apiKey
Required · sealed secret		In the N-Genius portal: Settings → Integrations → Service Accounts → Add (type merchant), then copy the API key.
Where your account is
region
Optional		Use the value for your account or connection.

Choices: UAE and the region (live) (uae); Saudi Arabia (live) (ksa); Sandbox (testing) (sandbox); Saudi Arabia sandbox (testing) (ksa-sandbox).

Starts with: uae.

Outlet reference
outlet
Required		In the N-Genius portal: Settings → Organisational Hierarchy → your outlet. Payment links and invoices are made for this outlet.
Webhook header name
webhookHeader
Optional		Optional, with the value below: the Header Key you give the webhook in the N-Genius portal.

Starts with: X-Webhook-Token.

Webhook header value
webhookSecret
Optional · sealed secret		Optional. To hear of payments: in the N-Genius portal, Settings → Integrations → Manage Webhooks → Add, with the address Roster shows on this connection, the header name above, and a long random value pasted here too.

Per-hire limits

Read-only hires receive only actions that read. Read-and-write access also allows actions that change things, where the connection itself permits them. An empty resource allowlist usually means everything the connected account can reach; each field below explains its meaning.

No additional fields.

Actions

6 actions: 2 only read and 4 change something. A read action may still need approval when your workspace or hire is set to ask. A locked approval requirement always applies.

6 of 6 actions. Open an action for its arguments and full input schema.

get_orderRead only

One N-Genius order by its reference: amount, whether it's been paid, captured or refunded, the card used (scheme and last four digits only), and the payment page if it's still unpaid.

Approval: Uses your workspace and hire approval settings.

Arguments for get_order
ArgumentTypeDetails
orderRequiredstringSee input schema below.
Full input schema (JSON)
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "order": {
      "type": "string",
      "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
    }
  },
  "required": [
    "order"
  ]
}
list_payment_eventsRead only

Payment events N-Genius sent Roster lately, newest first: paid, declined, failed, refunded… with the order reference to read. Only works once the connection's webhook is set up (N-Genius has no list of orders in its API).

Approval: Uses your workspace and hire approval settings.

Arguments for list_payment_events
ArgumentTypeDetails
orderOptionalstringonly this order's events
limitOptionalintegerSee input schema below.Default: 30
Full input schema (JSON)
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "order": {
      "description": "only this order's events",
      "type": "string",
      "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
    },
    "limit": {
      "default": 30,
      "type": "integer",
      "minimum": 1,
      "maximum": 100
    }
  }
}
create_payment_linkRead and write

Make a payment link: an N-Genius payment page for the customer to pay by card or wallet, taken in full when they pay. N-Genius notifies nobody: share the address yourself.

Approval: Uses your workspace and hire approval settings.

Arguments for create_payment_link
ArgumentTypeDetails
linesRequiredobject[]what they pay for: description, quantity, price each
currencyRequiredstringSee input schema below.
emailOptionalstringthe customer's email, shown on the payment page
referenceOptionalstringyour invoice or order number
languageOptional"en" | "ar" | "fr"See input schema below.Default: "en"
Full input schema (JSON)
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "lines": {
      "minItems": 1,
      "maxItems": 50,
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "description": {
            "type": "string",
            "minLength": 1,
            "description": "what was sold, as it should read on the invoice"
          },
          "quantity": {
            "default": 1,
            "type": "number",
            "exclusiveMinimum": 0
          },
          "rate": {
            "type": "number",
            "minimum": 0,
            "description": "price per unit, before tax"
          }
        },
        "required": [
          "description",
          "rate"
        ]
      },
      "description": "what they pay for: description, quantity, price each"
    },
    "currency": {
      "type": "string",
      "pattern": "^[A-Za-z]{3}$"
    },
    "email": {
      "description": "the customer's email, shown on the payment page",
      "type": "string",
      "format": "email",
      "pattern": "^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"
    },
    "reference": {
      "description": "your invoice or order number",
      "type": "string",
      "pattern": "^[A-Za-z0-9-]{1,50}$"
    },
    "language": {
      "default": "en",
      "type": "string",
      "enum": [
        "en",
        "ar",
        "fr"
      ]
    }
  },
  "required": [
    "lines",
    "currency"
  ]
}
send_invoiceRead and write

Send a Pay by Link invoice: N-Genius emails the customer (and texts them, with a mobile number) a link to pay it. With notify false, nothing is sent and you share the link yourself.

Approval: Uses your workspace and hire approval settings.

Arguments for send_invoice
ArgumentTypeDetails
first_nameRequiredstringSee input schema below.
last_nameRequiredstringSee input schema below.
emailRequiredstringSee input schema below.
mobileOptionalstringfor an SMS too: country code, a space, then the number
linesRequiredobject[]what they pay for: description, quantity, price each
currencyRequiredstringSee input schema below.
expiresOptionalstringwhen the link stops working, yyyy-mm-dd; default in 30 days
subjectOptionalstringSee input schema below.
messageOptionalstringshown to the customer with the link
notifyOptionalbooleanSee input schema below.Default: true
Full input schema (JSON)
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "first_name": {
      "type": "string",
      "minLength": 1,
      "maxLength": 50
    },
    "last_name": {
      "type": "string",
      "minLength": 1,
      "maxLength": 50
    },
    "email": {
      "type": "string",
      "format": "email",
      "pattern": "^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"
    },
    "mobile": {
      "description": "for an SMS too: country code, a space, then the number",
      "type": "string",
      "pattern": "^\\+\\d{1,4} ?\\d{6,12}$"
    },
    "lines": {
      "minItems": 1,
      "maxItems": 50,
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "description": {
            "type": "string",
            "minLength": 1,
            "description": "what was sold, as it should read on the invoice"
          },
          "quantity": {
            "default": 1,
            "type": "number",
            "exclusiveMinimum": 0
          },
          "rate": {
            "type": "number",
            "minimum": 0,
            "description": "price per unit, before tax"
          }
        },
        "required": [
          "description",
          "rate"
        ]
      },
      "description": "what they pay for: description, quantity, price each"
    },
    "currency": {
      "type": "string",
      "pattern": "^[A-Za-z]{3}$"
    },
    "expires": {
      "description": "when the link stops working, yyyy-mm-dd; default in 30 days",
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}$"
    },
    "subject": {
      "type": "string",
      "maxLength": 150
    },
    "message": {
      "description": "shown to the customer with the link",
      "type": "string",
      "maxLength": 1000
    },
    "notify": {
      "default": true,
      "type": "boolean"
    }
  },
  "required": [
    "first_name",
    "last_name",
    "email",
    "lines",
    "currency"
  ]
}
resend_invoiceRead and write

Send a Pay by Link invoice again, optionally to another email or with a later expiry date.

Approval: Uses your workspace and hire approval settings.

Arguments for resend_invoice
ArgumentTypeDetails
invoiceRequiredstringSee input schema below.
emailRequiredstringSee input schema below.
expiresOptionalstringa new expiry date, yyyy-mm-dd
Full input schema (JSON)
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "invoice": {
      "type": "string",
      "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
    },
    "email": {
      "type": "string",
      "format": "email",
      "pattern": "^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"
    },
    "expires": {
      "description": "a new expiry date, yyyy-mm-dd",
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}$"
    }
  },
  "required": [
    "invoice",
    "email"
  ]
}
refund_paymentRead and writeApproval required · locked

Refund a paid N-Genius order to the customer's card, in full or in part. Money moving always waits for a person's approval: Roster asks in the thread and makes exactly this refund, once, when they approve. Give the amount with its currency for a part refund; leave both out to refund whatever is left.

Approval: Always asks for approval. This requirement cannot be turned off.

Arguments for refund_payment
ArgumentTypeDetails
orderRequiredstringSee input schema below.
amountOptionalnumberhow much to refund, e.g. 120.50
currencyOptionalstringthe order's currency, e.g. AED; needed with amount
reasonOptionalstringwhy, for the approver
Full input schema (JSON)
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "order": {
      "type": "string",
      "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
    },
    "amount": {
      "description": "how much to refund, e.g. 120.50",
      "type": "number",
      "exclusiveMinimum": 0,
      "maximum": 10000000
    },
    "currency": {
      "description": "the order's currency, e.g. AED; needed with amount",
      "type": "string",
      "pattern": "^[A-Za-z]{3}$"
    },
    "reason": {
      "description": "why, for the approver",
      "type": "string",
      "maxLength": 300
    }
  },
  "required": [
    "order"
  ]
}

Watches and incoming events

  • This integration supports a responsibility that watches for changes. The guide above explains what it checks and how to limit it.
  • Incoming webhooks are supported. Use the callback address shown on the connection and follow the setup guide.

Limits and troubleshooting

  • Permission errors: check both the connected account's rights and the hire's resource and read/write limits.
  • Expired or revoked access: reconnect or replace the key on the connection.
  • Rate limits and unavailable services can interrupt work. The hire's timecard records the outcome.
  • The action schema describes accepted inputs. It does not grant additional access or bypass approvals.

Service documentation · Integration source reference

Mercury

Accounts, transactions and payments in Mercury.

Paddle

Customers, subscriptions, transactions and invoices in Paddle.

On this page

1. Find your API key and outlet in N-Genius2. Connect it in Roster3. Give hires accessRefunds wait for approvalHearing about paymentsIf something goes wrongTools and permissions reference