Nylon Pay Docs

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>;
};

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>;
};

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;
  amount: 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;
  currency: string;
  status: TransactionStatus;
  previousStatus: TransactionStatus;
  type: TransactionType;
  method: PaymentMethod;
  mode: TransactionMode;
  failureReason: string | null;
  operatorTid: string | null;
};

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