Create a customer.

Create a customer so you can issue dedicated virtual accounts, invoices and subscriptions to them, and see their payments together. Every field is optional. An email must be unique among your customers in this mode (409 customer_exists).

List customers.

List your customers. Filter by email to find a customer you created earlier.

Retrieve a customer.

Retrieve a customer by id (cus_…).

Update a customer.

Update a customer’s email, name or phone. metadata is merged into the existing metadata. Changing the email to one another customer uses returns 409 customer_exists. Set a metadata key to "" to delete it; the merged metadata may have at most 50 keys (400 metadata_too_large).

Create a bank-transfer payment.

Create a bank-transfer payment. Pletopay opens a dynamic (single-use) virtual account for it and returns the account in bank_transfer: show the account number, bank and amount to your customer.

With amount_rule: exact (the default) transfers of any other amount are rejected. With any, whatever arrives is accepted and amount may be omitted.

The account expires with the payment: expires_in (seconds) or expires_at, between 5 minutes and 3 hours (the limit for one-time accounts; 400 expiry_out_of_range carries details.min_seconds / max_seconds); the default is your organization’s setting (30 minutes unless changed).

The payment becomes succeeded only when the credit is confirmed. Never treat a redirect or client-side callback as proof of payment: listen for payment.succeeded or retrieve the payment.

reference must be unique among your payments in this mode (409 duplicate_reference). Send an Idempotency-Key so a retried request can’t create a second payment.

List payments.

List payments. Filter by status, customer, reference, virtual_account, amount received (amount[gte], amount[lte], in kobo) and creation time. Add expand[]=customer to embed the customer object.

Retrieve (verify) a payment.

Retrieve a payment by id (pay_…). This is the authoritative way to verify a payment server-side before you deliver value: check status is succeeded and amount_received is what you expect.

Retrieve (verify) a payment by your reference.

Retrieve a payment by the reference you gave it. Useful when you stored your order id but not the Pletopay payment id.

Create a virtual account.

Create a virtual account (a real NUBAN that routes into your balance).

Dedicated (type: dedicated, needs customer_id): a permanent account for one customer. Every transfer into it creates a succeeded payment with source: dedicated_virtual_account, whatever the amount. Close it when you no longer want to receive money through it.

Dynamic (type: dynamic, needs amount and reference): a single-use account for one exact amount. This is the same as creating a payment with POST /api/v1/payments; the response is the account, and the payment id is in payment.

List virtual accounts.

List virtual accounts. Filter by type, status, customer or account_number.

Retrieve a virtual account.

Retrieve a virtual account by id (va_…).

Retrieve a dynamic virtual account by your reference.

Retrieve a dynamic virtual account by the reference you gave when creating it (the same reference as its payment). Dedicated accounts have no reference: retrieve them by id, or list them with customer. An unknown reference returns 404 resource_missing.

Close a dedicated virtual account.

Close a dedicated virtual account so it stops receiving money for you. Dynamic accounts can’t be closed this way (400 invalid_operation): they close with their payment. Closing an already closed account returns it unchanged.

Create a subaccount (a seller/vendor on your platform) with a verified payout account.

Create a subaccount: a seller, vendor or branch on your platform with its own balance and payout account. The payout account is verified by name enquiry (400 account_not_resolved if it can’t be resolved). Payments share their net amount with subaccounts through split rules.

In live mode this sends real money or changes where money is paid, and it cannot be undone. Before calling, confirm the exact amount (in kobo) and the destination with the user.

List subaccounts.

List your subaccounts.

Retrieve a subaccount.

Retrieve a subaccount by id (sub_…).

Update a subaccount.

Update a subaccount’s name, email, status or metadata. Changing the payout account (bank_code with account_number) re-runs name enquiry, and the new account is used only after a cooldown (settlement_account.usable_from) to protect against account takeover.

In live mode this sends real money or changes where money is paid, and it cannot be undone. Before calling, confirm the exact amount (in kobo) and the destination with the user.

A subaccount's balances (from the ledger).

A subaccount’s pending, available and settling balances, read from the ledger.

Create a split rule.

Create a split rule that shares each payment’s net amount (after fees) with one or more subaccounts. The rest stays in your balance.

percentage shares are basis points (2500 = 25%); flat shares are kobo, capped at the net amount. Pass the rule id as split when you create a payment, checkout session, payment link, invoice or subscription. The split is frozen on each payment when it is created.

In live mode this sends real money or changes where money is paid, and it cannot be undone. Before calling, confirm the exact amount (in kobo) and the destination with the user.

List split rules.

List your split rules.

Retrieve a split rule.

Retrieve a split rule by id (spl_…).

Activate or deactivate a split rule.

Activate or deactivate a split rule. Deactivated rules can’t be used for new payments; payments already created keep their frozen split.

In live mode this sends real money or changes where money is paid, and it cannot be undone. Before calling, confirm the exact amount (in kobo) and the destination with the user.

Send money from your available balance.

Send money from your available balance to any Nigerian bank account. Idempotency-Key is required: if the request times out, retry with the same key and you will get the original transfer, never a second one.

Resolve the account first with POST /api/v1/transfers/name-enquiry. The amount plus fees (total_debit) is reserved from your available balance immediately (400 insufficient_funds otherwise). The minimum transfer is ₦10.00 (400 amount_below_minimum) and narration is limited to 50 characters.

A transfer whose outcome isn’t known yet stays processing; it is never reported failed until it is confirmed. Listen for transfer.succeeded / transfer.failed. A failed transfer releases the reserved funds.

Money-out can be refused by your risk limits (403 risk_limit_exceeded), an operator hold (403 funds_on_hold), live-mode verification (403 compliance_verification_required) or transfers not being enabled for your account (403 transfers_disabled).

In live mode this sends real money or changes where money is paid, and it cannot be undone. Before calling, confirm the exact amount (in kobo) and the destination with the user.

Choose an idempotency_key and reuse it if you retry this call, so it can never happen twice.

List transfers.

List transfers. Filter by status and creation time.

Retrieve a transfer.

Retrieve a transfer by id (trf_…).

Retrieve a transfer by your reference.

Retrieve a transfer by the reference you gave when sending it. References are unique per mode, so this is a safe way to check a transfer after a timeout when you never received its id. An unknown reference returns 404 resource_missing.

Resolve a bank account name before sending.

Look up the account name for a bank code and account number (NIP name enquiry). Show the name to the person sending money before they confirm. An account that can’t be resolved returns 400 account_not_resolved. In live mode, lookups need an approved business verification and count toward the money-movement rate limit.

List supported banks.

List the banks you can send transfers to, with the code to use as bank_code. The list is cached for an hour.

List settlements (payouts of your available balance to your bank account).

List settlements: payouts of your available balance (or a subaccount’s) to the settlement account you set in the dashboard, on your schedule or on demand. Filter by status or subaccount.

Retrieve a settlement.

Retrieve a settlement by id (stl_…), including its fees and the payout transfer’s status.

Ledger movements covered by a settlement.

Every movement of your available balance up to the settlement’s cutoff that this settlement accounts for. Use it to reconcile a payout against the payments and transfers behind it.

Refund a payment (fully or partially).

Refund a payment, fully or partially, by bank transfer from your available balance. Idempotency-Key is required.

Without amount, the whole refundable amount is refunded. Only succeeded or partially_refunded payments can be refunded (409 payment_not_refundable).

Destination. When the sender’s full account details are known, the refund always goes back to that account: omit destination (a different one returns 400 refund_destination_mismatch). When the sender isn’t known, pass destination (400 refund_destination_required otherwise); it is verified by name enquiry. In live mode a custom destination also needs outbound transfers enabled (403 transfers_disabled).

The payment becomes partially_refunded or refunded only once the refund has actually been paid out (refund.succeeded). Without a reference, one is derived from the Idempotency-Key, so a retried request can’t create a second refund.

In live mode this sends real money or changes where money is paid, and it cannot be undone. Before calling, confirm the exact amount (in kobo) and the destination with the user.

Choose an idempotency_key and reuse it if you retry this call, so it can never happen twice.

List refunds.

List refunds. Filter by payment to see the refunds of one payment.

Retrieve a refund.

Retrieve a refund by id (re_…).

Retrieve a refund by its reference.

Retrieve a refund by its reference (unique per mode). A refund created without one is given a generated reference, returned in its reference field. An unknown reference returns 404 resource_missing.

Create a hosted checkout session.

Create a checkout session, then either redirect your customer to its url (hosted checkout) or hand its token to your front end and open it in the Pletopay popup with the browser SDK and your publishable key. Pletopay’s page shows the bank-transfer details (the payment is created when the customer opens it), waits for the transfer and sends the customer to success_url (hosted) or calls your onSuccess callback (popup). The session expires after expires_in seconds (default 1 hour, at most 3 hours: one-time bank accounts are limited to 3 hours) and completes when its payment succeeds (checkout.session.completed). reference is optional; when given it must be unique per mode (409 duplicate_reference), and the session can then be retrieved with GET /api/v1/checkout/sessions/reference/{reference}. Neither the redirect nor the callback is proof of payment: confirm with the webhook or by retrieving the session.

List checkout sessions.

List checkout sessions. Filter by status or by the payment_link that started them.

Retrieve a checkout session.

Retrieve a checkout session by id (cs_…).

Retrieve a checkout session by your reference.

Retrieve a checkout session by the reference you gave when creating it (unique per mode). An unknown reference returns 404 resource_missing.

Expire an open checkout session.

Expire an open checkout session so the customer can no longer pay through it. A session that is already complete or expired returns 409.

Create a payment link.

Create a reusable payment link: a hosted page you can share anywhere. Each visit starts its own checkout session. Set a fixed amount, or leave it out and set min_amount / max_amount to let the customer choose. max_uses and expires_at stop the link automatically.

List payment links.

List payment links. Filter by status (active / inactive).

Retrieve a payment link.

Retrieve a payment link by id (plink_…).

Update or deactivate a payment link.

Rename a payment link, change its description, or deactivate it (active: false) so it stops accepting payments.

Create a draft invoice.

Create a draft invoice for a customer with line items and optional taxes (basis points, 750 = 7.5%). Totals are computed for you. A draft can be edited; finalize it to make it payable.

List invoices.

List invoices. Filter by status, customer or the subscription that issued them.

Retrieve an invoice.

Retrieve an invoice by id (inv_…).

Update a draft invoice.

Change a draft invoice’s customer, items, taxes, due date, memo or metadata. Only drafts can be changed (409 invoice_not_draft).

Finalize an invoice.

Finalize a draft invoice: it gets its number, the amounts are frozen, and hosted_invoice_url becomes a payable page to send to your customer. A zero total or a past due date can’t be finalized.

Void an invoice.

Void an open or uncollectible invoice so it can no longer be paid. Invoices in any other status return 409 invoice_not_open.

Mark an invoice uncollectible (it can still be paid).

Mark an open invoice uncollectible for your records. The customer can still pay it.

List risk events (blocked and flagged activity).

List risk events: money movements blocked by your risk limits and payments flagged for review (high value, customer velocity, blocked customers). Filter by review_status.

Your effective risk limits (kobo; 0 = no limit).

Your effective risk limits in this mode, in kobo (0 = no limit). Transfers and refunds over a limit are refused with 403 risk_limit_exceeded; received payments over high_value_payment are flagged, never refused.

Set a customer's risk status.

Set a customer’s risk status. blocked customers can’t be issued new payments or accounts (409 customer_blocked); elevated is informational.

Create a plan.

Create a plan: an amount billed every interval_count × interval (for example every 3 months). Subscribe customers to it with POST /api/v1/subscriptions.

List plans.

List your plans.

Retrieve a plan.

Retrieve a plan by id (plan_…).

Update or deactivate a plan.

Rename a plan or deactivate it. Inactive plans take no new subscriptions; existing subscriptions continue.

Subscribe a customer to a plan.

Subscribe a customer to a plan. The first period’s invoice is issued at start_date (default now) and each later one at the end of the period, due after days_until_due days.

Nothing is ever debited automatically; Nigerian bank transfers are push payments. With collection_method: invoice the customer pays each period through its hosted invoice page. With dedicated_account, the customer also gets a dedicated virtual account and an exact transfer into it pays the open invoice.

A customer can have one live subscription per plan (409 subscription_exists).

List subscriptions.

List subscriptions. Filter by status or customer.

Retrieve a subscription.

Retrieve a subscription by id (sbs_…).

Cancel a subscription (now, or at the end of the current period).

Cancel a subscription now, or at the end of the current period with at_period_end: true. Canceling an already canceled subscription returns 409 subscription_canceled.

Generate a CSV report.

Generate a CSV report for a period of up to 366 days (period_end is exclusive). Reports run in the background: poll the report or listen for report.ready, then download it. Amounts in the CSV are exact decimal naira and times are UTC. The file is available until the report’s expires_at. At most two reports generate at once per mode (429 reports_in_progress).

List reports.

List reports. Filter by type or status.

Retrieve a report.

Retrieve a report by id (rpt_…).

Download a finished report (CSV).

Download a finished report as CSV. The X-Content-SHA256 response header carries the file’s hash (it matches the report’s sha256). A report still generating returns 409 report_not_ready; an expired file returns 409 report_expired.

Balance statement: opening, credits, debits, closing per balance.

Opening balance, credits, debits and closing balance for each of your balances over a period, computed from the ledger.

Register a webhook endpoint. The signing secret is returned only in this response.

Register a publicly reachable endpoint to receive events (https is required for live mode; private network addresses are refused). Subscribe to specific enabled_events or * for all. The signing secret (whsec_…) is returned only in this response: store it to verify X-PletoPay-Signature. You can have up to 16 endpoints per mode (400 webhook_endpoint_limit_reached).

List webhook endpoints.

List your webhook endpoints with their delivery health.

Retrieve a webhook endpoint.

Retrieve a webhook endpoint by id (we_…).

Update a webhook endpoint (re-enabling resets its health).

Change an endpoint’s URL, events or description, or disable and re-enable it. Re-enabling an endpoint that was auto-disabled after repeated failures resets its health.

Delete a webhook endpoint (deliveries stop; history is kept).

Delete a webhook endpoint. Deliveries to it stop; its delivery history is kept.

Rotate the signing secret.

Replace the endpoint’s signing secret. The new secret is returned only in this response, and deliveries are signed with it from now on.

Send a signed webhook.test event to this endpoint only.

Send a signed webhook.test event to this endpoint only, to check your signature verification and connectivity. The endpoint must be enabled (409 endpoint_disabled). Test sends are limited per business (429 rate_limited, see Retry-After).

Deliveries to this endpoint.

Delivery attempts to this endpoint, with response status, error and timing. Filter by status.

List events.

List events, the same objects delivered to your webhooks. Filter by type or by resource_id (e.g. a payment id) to see everything that happened to one object. Use it to catch up after downtime.

Retrieve an event.

Retrieve an event by id (evt_…).

Delivery history for an event.

Every delivery of this event to your endpoints.

Re-deliver an event.

Deliver an event again, to every endpoint subscribed to it or to one endpoint. The payload and X-PletoPay-Event-ID are unchanged, so your de-duplication still applies. Replays are limited per business (429 rate_limited, see Retry-After).

Retrieve your balances.

Your balances in this mode, computed from the double-entry ledger:

• available: can be sent as transfers, refunds or settlements.

• pending: received but not yet available.

• held: on hold.

• unapplied: received money under review.

• settling: reserved by an open settlement.

• total: the sum of the above. settled_total: the lifetime amount paid out by completed settlements.

List ledger transactions.

Every ledger journal that moved your balances, with its signed effect per balance (credits to you are positive) and the object that caused it. Filter by journal type or by source. Use it for reconciliation.

Simulate a customer bank transfer (test mode only).

Test mode only (403 test_mode_only with a live key). Simulate a transfer into one of your test virtual accounts, as a customer would make it.

The transfer then flows through the same pipeline as live money: the payment moves to succeeded and webhooks are sent. A wrong amount into an exact-amount account is refused (400 simulation_rejected), as a real transfer would be. An account that is not active (for example a one-time account that already received its payment) is refused before anything is sent (409 virtual_account_not_active). A 202 only means the simulation was accepted; watch the payment or its events for the outcome.

Test mode only: needs an sk_test_ key.

List the sandbox test values (test mode only).

Test mode only (403 test_mode_only with a live key). Recipient account numbers that give a payout (or a refund) a fixed outcome in test mode, so you can test failures on purpose: declined, processing then succeeded, processing then failed, a timeout confirmed by a status check, and an account that is not found.

Use them as the recipient of a payout, or as sender_account_number when you simulate a transfer, to test what happens to a refund. Any other number succeeds.

Test mode only: needs an sk_test_ key.

Search the Pletopay guides (payments, virtual accounts, transfers, refunds, checkout, webhooks, errors, testing, going live). Returns the best-matching sections with a link and a snippet; read a whole page with get_doc.

Returns one Pletopay guide as markdown, by its slug (from search_docs, or one of the listed slugs).