Nile Pay Docs

Configuration

NilePayConfig

Configuration options for SDK initialization.

Field	Type	Default	Description
`environment`	`'sandbox' \| 'live'`	required	Target environment
`apiKey`	`string`	required	Public API key
`apiSecret`	`string`	required	Secret API key
`baseUrl`	`string`	`undefined`	Custom base URL
`timeoutMs`	`number`	`30000`	Request timeout in milliseconds
`maxRetries`	`number`	`3`	Maximum retry attempts
`maxPollDuration`	`number`	`300000`	Status polling duration in ms
`maxPollAttempts`	`number`	`150`	Maximum poll attempts
`fetch`	`typeof globalThis.fetch`	`undefined`	Custom fetch implementation

interface NilePayConfig {
  environment: 'sandbox' | 'live';
  apiKey: string;
  apiSecret: string;
  baseUrl?: string;
  timeoutMs?: number;
  maxRetries?: number;
  maxPollDuration?: number;
  maxPollAttempts?: number;
  fetch?: typeof globalThis.fetch;
}

Request Types

CreateCollectionRequest

Request to initiate a payment collection.

Field	Type	Required	Description
`amount`	`number`	Yes	Amount in smallest currency unit
`currency`	`string`	No	Currency code (default: UGX)
`method`	`string`	No	Specific payment method
`description`	`string`	No	Payment description
`customer`	`{ phone: string; email?: string; }`	Yes	Customer details
`reference`	`string`	Yes	Unique merchant reference
`invoiceNumber`	`string`	No	Invoice number
`notifyMerchant`	`boolean`	No	Send merchant notification
`metadata`	`Record<string, unknown>`	No	Custom metadata

interface CreateCollectionRequest {
  amount: number;
  currency?: string;
  method?: string;
  description?: string;
  customer: { phone: string; email?: string; };
  reference: string;
  invoiceNumber?: string;
  notifyMerchant?: boolean;
  metadata?: Record<string, unknown>;
}

CreateInvoiceRequest

Request to create a payment link (invoice).

Field	Type	Required	Description
`amount`	`number`	Yes	Invoice amount
`currency`	`string`	No	Currency code (default: UGX)
`description`	`string`	No	Invoice description
`customer`	`{ phone?: string; email?: string; name?: string; }`	No	Customer details
`reference`	`string`	Yes	Unique merchant reference
`dueDate`	`string`	No	ISO 8601 expiration date
`metadata`	`Record<string, unknown>`	No	Custom metadata

interface CreateInvoiceRequest {
  amount: number;
  currency?: string;
  description?: string;
  customer?: { phone?: string; email?: string; name?: string; };
  reference: string;
  dueDate?: string;
  metadata?: Record<string, unknown>;
}

GetStatusRequest

Request to check transaction status.

Field	Type	Required	Description
`reference`	`string`	Yes	Merchant reference to look up

interface GetStatusRequest {
  reference: string;
}

Response Types

CollectionResponse

Response from creating a collection.

Field	Type	Description
`transactionId`	`string`	Nile Pay transaction ID
`reference`	`string`	Merchant reference
`status`	`TransactionStatus`	Current status
`providerReference`	`string`	Provider transaction reference
`createdAt`	`string`	ISO 8601 timestamp
`_responseSignature`	`string`	Response signature

interface CollectionResponse {
  transactionId: string;
  reference: string;
  status: TransactionStatus;
  providerReference?: string;
  createdAt: string;
  _responseSignature?: string;
}

StatusResponse

Response from checking transaction status.

Field	Type	Description
`transactionId`	`string`	Nile Pay transaction ID
`reference`	`string`	Merchant reference
`status`	`TransactionStatus`	Current status
`amount`	`number`	Transaction amount
`currency`	`string`	Currency code
`providerReference`	`string`	Provider reference
`createdAt`	`string`	Creation timestamp
`updatedAt`	`string`	Last update timestamp

interface StatusResponse {
  transactionId: string;
  reference: string;
  status: TransactionStatus;
  amount: number;
  currency: string;
  providerReference?: string;
  createdAt: string;
  updatedAt: string;
}

Enums

TransactionStatus

Possible transaction states.

Value	Description
`'pending'`	Transaction created, awaiting action
`'processing'`	Payment in progress with provider
`'successful'`	Payment completed
`'failed'`	Payment failed
`'cancelled'`	Payment cancelled

type TransactionStatus = 'pending' | 'processing' | 'successful' | 'failed' | 'cancelled';

PaymentEvent

Webhook event types.

Value	Description
`'processing'`	Provider received payment request
`'success'`	Payment succeeded
`'failed'`	Payment failed
`'cancelled'`	Payment cancelled
`'error'`	System error occurred

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

Types

On this page