Nylon Pay Docs

TypeScript and PHP share the same camelCase field names. Python uses snake_case. Tabs below show TypeScript and Python shapes; for PHP, use the TypeScript field names as associative-array keys (PHP matches TypeScript naming).

Configuration

NylonPayConfig

type NylonPayConfig = {
  apiKey: string;
  apiSecret: string;
  baseUrl?: string;
  timeoutMs?: number;
  maxRetries?: number;
  maxPollIntervalMs?: number;
  maxPollDurationMs?: number;
  maxPollAttempts?: number;
  fetch?: typeof globalThis.fetch;
  force?: boolean;
  hooks?: SdkHooks;
};

Request Types

CollectPaymentInput

type CollectPaymentInput = {
  amount: number;
  currency: Currency;
  customer: Customer;
  description: string;
  reference?: string;  // UUID, auto-generated as v4 if omitted
  method?: PaymentMethod;
  bank?: BankDetails;
  metadata?: Record<string, string>;
  tags?: string[];  // business labels, max 10, each up to 50 chars
  testOutcome?: "success" | "fail" | FailureCode;  // sandbox only; omit for 70/30 random
};

MakePayoutInput

type MakePayoutInput = {
  amount: number;
  currency: Currency;
  customer: Customer;
  destination: Destination;
  description: string;
  reference?: string;  // UUID, auto-generated as v4 if omitted
  metadata?: Record<string, string>;
  tags?: string[];  // business labels, max 10, each up to 50 chars
  testOutcome?: "success" | "fail" | FailureCode;  // sandbox only; omit for 70/30 random
};

CreateInvoiceInput

type CreateInvoiceInput = {
  amount: number;
  currency: Currency;
  customerEmail: string;
  customerName?: string;
  customerPhone?: string;
  description?: string;
  dueDate?: string;
  items?: InvoiceItem[];
  merchantReference?: string;
  tags?: string[];
  metadata?: Record<string, string>;
};

GetStatusInput

type GetStatusInput = { reference: string };

GetTransactionInput

type GetTransactionInput = { id?: string; reference?: string };

VerifyPhoneInput

type VerifyPhoneInput = {
  phoneNumber: string;
  purpose?: "collection" | "payout";
};

verifyPhone has no currency. Local 0XXXXXXXXX is treated as Uganda. Other markets need the international form (+254…, +255…, +250…, +243…). See Phone Number Format.

ListTransactionsInput

type ListTransactionsInput = {
  tags?: string[];  // transactions carrying ALL of these tags (AND)
  status?: TransactionStatus;
  type?: TransactionType;
  limit?: number;   // 1-100, default 20
  offset?: number;  // zero-based, default 0
  createdAfter?: string;   // ISO 8601
  createdBefore?: string;  // ISO 8601
};

Omitting filters returns the most recent transactions for the calling key's account and mode. tags, status, and type combine with AND semantics.

TransactionSummary

type TransactionSummary = {
  id: string;
  reference: string;
  amount: number;
  currency: Currency;
  status: TransactionStatus;
  type: TransactionType;
  method: string | null;
  mode: TransactionMode;
  tags: string[];  // system + developer smart tags
  createdAt: string;
  updatedAt: string;
};

ListTransactionsResponse

type ListTransactionsResponse = {
  transactions: TransactionSummary[];
  count: number;   // number of transactions in this page (≤ limit)
  limit: number;
  offset: number;
  tags: string[];  // normalized tags applied as filters (empty if none)
};

VerifyWebhookInput

type VerifyWebhookInput = {
  payload: string | Uint8Array;
  signature: string;
  secret: string;
};

Shared Subtypes

Customer

type Customer = {
  name: string;
  phoneNumber: string;
  email?: string;
};

phoneNumber accepts any common format (local 0XXXXXXXXX uses the payment currency's dial code, international +256… / +254…, with or without spaces). Automatically normalized to digits with that market's calling code. See Phone Number Format.

Destination

type Destination = {
  accountHolderName: string;
  accountNumber: string;
  bankName?: string;
  phone?: string;
};

phone accepts any common format (local 0XXXXXXXXX uses the payment currency's dial code, international +256… / +254…, with or without spaces). Automatically normalized to digits with that market's calling code. See Phone Number Format.

BankDetails

type BankDetails = {
  accountNumber: string;
  bankName: string;
};

InvoiceItem

type InvoiceItem = {
  name: string;
  quantity: number;
  unitPrice: number;
};

Response Types

Transaction

type Transaction = {
  id: string;
  reference: string;
  amount: number;
  currency: Currency;
  status: TransactionStatus;
  type: TransactionType;
  method: PaymentMethod;
  description: string;
  duplicate?: boolean;
  phone: string;
  email: string | null;
  failureReason: string | null;
  failureCategory: FailureCategory | null;
  failureCode: FailureCode | null;
  statusText?: string;
  delayed?: boolean;
  operatorTid: string | null;
  metadata: Record<string, string>;
  mode: TransactionMode;
  createdAt: string;
  updatedAt: string;
};

Field	Type	Description
`operatorTid`	`string \| null`	ID on the customer's operator or bank receipt. Use it to cross-check a pay claim. `null` until it is reported.

phone is always returned in normalized international format (digits with the market's calling code, for example 256… or 254…). See Phone Number Format.

StatusResponse

type StatusResponse = {
  reference: string;
  status: TransactionStatus;
  amount: number;
  currency: Currency;
  id: string;
  operatorTid: string | null;
  failureReason: string | null;
  failureCategory: FailureCategory | null;
  failureCode: FailureCode | null;
  statusText?: string;
  delayed?: boolean;
  updatedAt: string;
};

PhoneVerification

type PhoneVerification = {
  phoneNumber: string;
  customerName: string;
  verified: boolean;
};

phoneNumber is returned in normalized international format (digits with the market's calling code, for example 256… or 254…). See Phone Number Format.

InvoiceResponse

type InvoiceResponse = {
  id: string;
  invoiceNumber: string | null;
  paymentLink: string;
  url?: string;
  amount: string;
  currency: string;
  status: string;
};

Webhook Types

WebhookEventType

type WebhookEventType =
  | "transaction.successful"
  | "transaction.failed"
  | "transaction.processing"
  | "transaction.cancelled";

WebhookPayload

The signature is delivered in the x-nylon-signature request header, not the body.

type WebhookPayload = {
  delivery_id: string;
  event: WebhookEventType;
  payload: WebhookTransactionSnapshot;
  timestamp: string;
};

WebhookTransactionSnapshot

type WebhookTransactionSnapshot = {
  transactionId: string;
  reference: string;
  amount: string | null;
  currency: string | null;
  status: TransactionStatus;
  previousStatus: TransactionStatus;
  type: TransactionType | null;
  method: PaymentMethod | null;
  mode: TransactionMode | null;
  failureReason: string | null;
  failureCategory: FailureCategory | null;
  failureCode: FailureCode | null;
  legacyType?: "charge";
  operatorTid: string | null;
};

Every key is always present. type, method, and mode are null when no value is stored. amount and currency are null only rarely. transactionId and status are always set, so reconcile with getStatus() if you receive a sparse payload. Collections also send legacyType: "charge". Read type (collection) going forward.

Event Types

PaymentEvent

type PaymentEvent =
  | "processing"
  | "success"
  | "failed"
  | "cancelled"
  | "error";

Global error handler

type SdkErrorHandler = (error: SdkError) => void | Promise<void>;

Pass this handler as onError (on_error in Python) when creating the SDK. Use error.reason === "SERVICES_DOWN" or error.reason === "NETWORK" for Nylon-down and offline handling. See Error Handling.

EventData

type EventData = {
  event: PaymentEvent;
  reference: string;
  transaction?: Transaction;
  error?: string;
  reason?: SdkErrorReason;
  retryable?: boolean;
  timestamp: string;
};

PaymentEventHandler

type PaymentEventHandler = (data: EventData) => void;

Error Type

SdkError

type SdkError = {
  reason: SdkErrorReason;
  message: string;
  retryable?: boolean;
};

SdkErrorReason

type SdkErrorReason =
  | "AUTH"
  | "VALIDATION"
  | "LIMIT"
  | "RATE_LIMIT"
  | "ACCOUNT"
  | "PROVIDER"
  | "DUPLICATE"
  | "NOT_FOUND"
  | "INTERNAL"
  | "NETWORK"
  | "SERVICES_DOWN"
  | "TIMEOUT";

Union Types

TransactionStatus

type TransactionStatus =
  | "pending"
  | "processing"
  | "on_hold"
  | "successful"
  | "failed"
  | "cancelled";

TransactionType

type TransactionType =
  | "collection"
  | "payout"
  | "transfer"
  | "escrow"
  | "refund"
  | "reversal"
  | "charge"
  | "chargeback";

TransactionMode

type TransactionMode = "test" | "live";

PaymentMethod

type PaymentMethod = "mobileMoney" | "bank";

Currency

type Currency = "USD" | "EUR" | "GBP" | "KES" | "UGX" | "TZS" | "RWF" | "CDF";

FailureCategory

type FailureCategory = "provider" | "customer" | "internal" | "validation";

FailureCode

type FailureCode =
  | "provider_rejection"
  | "customer_timeout"
  | "insufficient_balance"
  | "invalid_number"
  | "internal_error"
  | "limit_exceeded"
  | "cancelled";

Result Pattern

All query and resolve methods return a Result type. Check the outcome using these properties.

type Result<T, E> = {
  isOk: boolean;
  value: T | undefined;
  isErr: boolean;
  error: E | undefined;
};

Property	Type	Description
`isOk`	`boolean`	True when the operation succeeded
`value`	`T \| undefined`	The data when `isOk` is true
`isErr`	`boolean`	True when the operation failed
`error`	`E \| undefined`	The error when `isErr` is true

Methods like collectPaymentAndResolve, makePayoutAndResolve, getStatus, getTransaction, verifyPhone, and createInvoice return Promise<Result<T, string>>. Parse the error string with the standalone parseError export to get a structured SdkError.

Types

On this page