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>;
  testOutcome?: "success" | "fail";  // sandbox only, omit for 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>;
  testOutcome?: "success" | "fail";  // sandbox only, omit for 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";
};

phoneNumber accepts any common format (local 0XXXXXXXXX, international +256XXXXXXXXX, with or without spaces). Automatically normalized to 256XXXXXXXXX. See Phone Number Format.

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, international +256XXXXXXXXX, with or without spaces). Automatically normalized to 256XXXXXXXXX. See Phone Number Format.

Destination

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

phone accepts any common format (local 0XXXXXXXXX, international +256XXXXXXXXX, with or without spaces). Automatically normalized to 256XXXXXXXXX. 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;
  phone: string;
  email: string | null;
  failureReason: string | null;
  operatorTid: string | null;
  metadata: Record<string, string>;
  mode: TransactionMode;
  createdAt: string;
  updatedAt: string;
};

Field	Type	Description
`operatorTid`	`string \| null`	The operator transaction ID from the underlying payment provider (telco or bank). Use this to cross-validate customer payment claims. `null` until the operator reports it.

phone is always returned in normalized international format (256XXXXXXXXX). See Phone Number Format.

StatusResponse

type StatusResponse = {
  reference: string;
  status: TransactionStatus;
  amount: number;
  currency: Currency;
  updatedAt: string;
};

PhoneVerification

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

phoneNumber is returned in normalized international format (256XXXXXXXXX). See Phone Number Format.

InvoiceResponse

type InvoiceResponse = {
  id: string;
  invoiceNumber: string;
  paymentLink: 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;
  operatorTid: string | null;
};

Every key is always present. type, method, and mode are null when the transaction has no value stored for them. amount and currency are null only in the rare case where we could not read the transaction record while dispatching — transactionId and status are always set, so reconcile with getStatus() if you ever receive one.

Event Types

PaymentEvent

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

EventData

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

PaymentEventHandler

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

Error Type

SdkError

type SdkError = {
  category: SdkErrorCategory;
  message: string;
  retryable?: boolean;
};

Union Types

TransactionStatus

type TransactionStatus =
  | "pending"
  | "processing"
  | "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";

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