Getting started
Terminology
When working with the Nexpay API you may find in our documentation and our API specific terms that may not be used outside of the payments industry or Nexpay itself. Use this table to understand what these terms mean.
These are the most common terms used by Nexpay:
| Term | Meaning |
|---|---|
| Payment | A payment is the core entity in Nexpay. It represents a cross-border money transfer from a payer to a payee. A payment has a status that tracks its lifecycle (e.g. created, processing, collected, paid, cancelled, refunded). Each payment has a transactionType that determines its shape: provider (e.g. university tuition), company (business-to-business), or private (individual transfers). |
| Payer | The person or entity sending money. Payers have a type (e.g. student, parent, agent, other-company) and provide identity documents and details required for compliance. Payers can be saved and reused across multiple payments. |
| Payee | The recipient of funds (also known as a beneficiary). Payees have bank account details, a country, and a currency. For example, a university receiving tuition payments. |
| Payout | A payout represents the outgoing settlement to a payee. Each payment may have one or more payouts, each with its own settlementChannel (e.g. the payment gateway used) and settlementMethod (e.g. bank-transfer, dmt). |
| Quote | A quote provides the exchange rate and fee details for a payment before it's created. Quotes have an expiresOn timestamp and a list of variants, each with id, fromAmount, fromCurrency, toCurrency, fxRate, and fee. See FX quotes and rates. |
| Settlement channel | The payment gateway or provider used to process a payout (e.g. Checkout, Volt, Ebanx, Flutterwave). |
| Settlement method | The specific payment method used by the payer to send funds (e.g. bank transfer, credit card, PayID, GrabPay, PromptPay). |
| Commission | Earnings accrued by an organization on payments. Commissions can be tracked, exported, and withdrawn via commission requests with supporting invoice documentation. |
| Organization | The business entity using Nexpay. An organization has branding, a logo, and compliance documents. Organizations operate under a tenant. |
| Tenant | The top-level multi-tenant isolation unit. Each tenant has its own branding configuration. |
| User | A user is created by a "super admin" on Nexpay, and has access to the Dashboard. Users are bound by roles and permissions. |
| Conversation | A message thread scoped to a specific payment, enabling communication between parties. Conversations support text messages and file attachments. |
| Payment intent | Nexpay's unified payment object. One endpoint (POST /v2/payment-intents) handles every scenario: manual operator-driven payments, reusable payment links, batch payroll, refunds. See Manual payment with splits and Payment links. |
useCase | The business reason for a payment intent. Values include education_provider_tuition, education_provider_tuition_with_tenant_split, supplier_payment, payroll_payment, tenant_funded_refund, allowance_payment, generic_service_invoice, owed_commission_invoice, legacy_transaction_reissue. |
deliveryMode | How the payer completes the payment: manual (operator-executed), reusable_payment_link (shareable URL), payment_link_submission (one submission of a link), or bulk (batch). |
amountMode | Where the amount comes from on a payment intent. Each value dictates which field on recipients[i].amount you must populate: payer_fixed, recipient_fixed, fixed_payee_amounts, free_entry_with_portions, mixed_composite, legacy_reissue. |
splitRole | Classifies each recipient on a split payment intent and drives the GL account your finance system books the leg against. Values: principal_provider_amount, tenant_commission, tenant_service_fee, tenant_tax_component, other. |
| Subject | On a payment intent, the person the payment is for — usually a student. Distinct from the payer (who pays). On a tuition payment the subject is the student; on a refund or allowance the payer (tenant or family) and subject (student) diverge. |
| Party | Umbrella term for a saved student or saved payer that can be referenced on a payment intent via partyId. Both students (POST /v2/students) and payers (POST /v2/payers) are stored with Mongo _id and are interchangeable as partyId values. See Parties. |
| Connector | The underlying payment rail that executes a payment intent (e.g. the legacy provider connector, PayNow v1 for reusable links). Surfaced as executions[].connector on the intent. |
| Rule | The matched scenario template that determines required fields and connector limits for a payment intent. Returned on dry-run as rule.key and rule.status (enabled, contract_gated, blocked). |
| Child submission | The payment intent created automatically each time a payer completes a reusable payment link. Has deliveryMode: "payment_link_submission" and createdFrom.paymentIntentId pointing back to the parent link intent. |
| Identifiers | Nexpay uses a few different identifier conventions: integer id for Payment and Payee; string id (24-char Mongo) for Payment Intent; _id for raw Mongo resources (Student, Payer, Employee); UUID documentId for Document; UUID quoteId for Quote; opaque publicLinkId for reusable payment links. |