Nylon Pay Docs

Nylon Pay integration skill for AI coding agents (Cursor, Claude Code, and similar). It describes which flow to build and which operation to pick, not language syntax. Load this page first, then the SKILL.md shipped with your SDK for install commands, naming, and runnable examples.

Ready-to-paste tasks: Example prompts.

Two layers

Layer	Where	What it covers
Integration skill	This page	Flows, contracts, operation choice, boundaries, gotchas
SDK skill	`SKILL.md` in each package	Idiomatic setup, imports, and code for that language

Think in feature flows and contracts, not copy-paste from one language into another. The SDK specification is the shared contract every SDK implements.

Security boundary

Server-side only. Never expose apiSecret to browsers or mobile clients.
Keys from environment variables. API key prefix npk_, secret prefix nps_.
Test vs live comes from the key you use, not a config flag. There is no environment option.

Universal contracts

Amounts: integers in the currency's smallest tracked unit (for example 10000).
Currencies: USD, EUR, GBP, KES, UGX, TZS, RWF.
Result: data operations return success or failure. Branch before reading the success payload. Use the SDK's parse-error helper for human messages and retry hints.
Reference: supply a UUID v4 you own for idempotency, or omit it for an auto-generated UUID. Non-UUID values fail validation.

Naming across SDKs

Concept	TypeScript / PHP	Python
Success check	`result.isOk`	`result.is_ok`
Collect (await)	`collectPaymentAndResolve`	`collect_payment_and_resolve`
Invoice link field	`.paymentLink`	`.payment_link`
Customer phone	`phoneNumber`	`phone_number`

TypeScript and PHP share camelCase. Python uses snake_case. Field tables: SDK Reference.

Choosing an operation

Goal	TypeScript / PHP	Python	Return shape
Take money, react to live updates	`collectPayment`	`collect_payment`	Payment instance (events)
Take money, await final state	`collectPaymentAndResolve`	`collect_payment_and_resolve`	Result
Send money, react to live updates	`makePayout`	`make_payout`	Payment instance
Send money, await final state	`makePayoutAndResolve`	`make_payout_and_resolve`	Result
One-shot status	`getStatus`	`get_status`	Result
Full transaction record	`getTransaction`	`get_transaction`	Result (`id` or `reference`)
Pre-validate phone / get name	`verifyPhone`	`verify_phone`	Result
Hosted payment link (cards)	`createInvoice`	`create_invoice`	Result with payment link
Authenticate webhook	`verifyWebhookSignature`	`verify_webhook_signature`	boolean

Prefer *AndResolve / *_and_resolve for simple request/response handlers. Use the event-driven payment instance when you need progressive status updates.

Flow: simple collect or payout

Create the SDK client with keys from the environment.
Call the *AndResolve variant for the direction (collect or payout).
Branch on Result before reading .value.
On failure, parse the error for a human message and whether retry is safe.
On success, persist reference and transaction identifiers your app needs.

Flow: event-driven payment

Call collectPayment / makePayout (without AndResolve).
Subscribe to processing, success, failed, cancelled, and error.
Call wait() for the final transaction or null (failure does not throw).
Fulfill or notify from event handlers; do not assume wait() alone is enough if side effects must run as soon as status changes.

Flow: webhooks

Read the raw, unparsed request body (bytes or string).
Verify the signature from the x-nylon-signature header against your webhook secret before trusting the payload.
Return 401 when verification fails.
Process the event only after verification succeeds.

Re-serializing JSON breaks verification.

Flow: card payments

Card checkout is hosted invoice only. Call createInvoice, then redirect the customer to the payment link on the result (.paymentLink or .payment_link). Do not collect card numbers in your app.

Flow: status and reconciliation

Quick status: getStatus with reference.
Full record: getTransaction with id or reference.
Phone check before pay: verifyPhone to validate format and read the registered name when available.

Gotchas

Webhook verification requires the raw body, not parsed-then-stringified JSON.
Card payments only through hosted invoice.
Supplied reference values must be UUIDs (or omit for auto UUID v4).
Multiple official SDKs exist. Do not assume TypeScript-only APIs when the user's stack is Python or PHP.

SDK skills (implementation)

Load the integration skill (this page) and the SDK skill for your language.

Language	Package	SDK skill
TypeScript	`@nile-squad/nylonpay-ts`	SKILL.md
Python	`nylonpay-py`	SKILL.md
PHP	`nile-squad/nylonpay-php`	SKILL.md

Each SDK skill also links the other languages so agents do not treat one stack as the only option.

How to use in Cursor

Load this integration skill (this page).
Load SKILL.md from your SDK package or its GitHub repo (table above).
Paste a concrete task from Example prompts, or describe your flow in plain language.

What skills are not

Skills do not replace the SDK Reference. Use the reference for full field tables and API detail.
Skills do not change runtime behavior. They only guide the agent.
Never paste live keys into prompts. Keep secrets in environment variables.

Request another language

Go and C# are in pipeline. For other languages, early access, or docs help:

Nylon Pay Integration Skill