Mattering Automations Paystack integration
Connect Paystack to Mattering Automations: checkout and saved-card charges, plans and subscriptions, transfers and payout recipients, refunds, disputes, splits, payment requests, settlements and the balance ledger as workflow steps, authorized with one secret key.
The Mattering Automations Paystack integration puts every operation in Paystack's own published API description on your automation canvas: start a checkout, charge a saved card, run plans and subscriptions, pay suppliers and contractors by bank transfer or mobile money, issue and chase invoices, handle refunds and chargebacks, split revenue across subaccounts, and reconcile the balance ledger against what Paystack settled into your bank account. 163 nodes in total, 73 that read and 90 that act, with one node per operation and no generic call-any-endpoint node.
Read the money warning before the setup steps. Seventeen of those nodes move real funds on a live key and nothing in this integration can undo them, because Paystack's API has no recall endpoint. They are all classed destructive, they all say so on themselves, and they are listed in full below. The related fact that catches people out is retries: there is no Idempotency-Key header anywhere on the Paystack API, so a retried Paystack: Charge Authorization can charge a customer twice. Transfers are the one exception and only when the retry sends the same reference.
The credential is a single secret key you copy from your Paystack Dashboard, so setup is short. Two Paystack facts are worth knowing before you start rather than after. Merchant signup is limited to businesses registered in Nigeria, Ghana, South Africa and Kenya, with a private beta in Cote d'Ivoire and Egypt. And test mode is a full free sandbox that needs no verification, while going live needs your compliance documents approved by Paystack, so build everything on an sk_test_ key first. This guide covers the credential, the connect steps, a safe read-only verify path, how to work with money and retries, and the complete node reference.
Before you start
- A Paystack account. Paystack states that its services are available only to businesses registered in Nigeria, Ghana, South Africa and Kenya, and it runs a private beta in Cote d'Ivoire and Egypt. If your business is registered elsewhere you may be unable to complete signup and so unable to obtain even a test key. This is a Paystack boundary, not a configuration problem.
- A Paystack secret key from Settings > API Keys and Webhooks in the Paystack Dashboard. Use the secret key, not the public key: a public key starts with pk_ and is meant for a checkout page in a browser. Start with the test secret key, which begins with sk_test_.
- An understanding of which mode you are in. A new Paystack account starts in test mode, which Paystack describes as a safe sandbox where you can use Paystack without using real money. The Dashboard switches to live mode once your compliance documents have been submitted and approved. Test and live share one host and one set of paths, so the key prefix is the only difference between a sandbox call and a real payment.
- An awareness that this integration moves money. Seventeen nodes debit a card or bank account, or send funds out of your balance, and none can be undone through this API. Decide before you build which of them a workflow is allowed to reach unattended and which belong behind a human approval step.
- Knowledge of which Paystack features your business has enabled. Transfers, Dedicated Virtual Accounts, Terminal, Virtual Terminal and Storefront are enabled per business and several are country-limited, so a valid key can still answer 403 on a whole resource. That is a feature that is switched off rather than a broken node.
- A Mattering workspace with access to the Automations app.
Get your Paystack secret key
Paystack authenticates with a single secret key sent as a bearer token. There is no OAuth flow, no app to register and no second field to fill in, so this step is short. The decision that carries weight is which key you copy, because the same key that runs a harmless sandbox call runs a real payout when it starts with sk_live_ instead of sk_test_.
Connect Paystack to Mattering
Verify it works
Open any automation canvas and check the palette: a Paystack section should list the read and action nodes. Drop Paystack: Fetch Balance onto the canvas and run a test step. It is the natural probe because it takes no parameters and returns one row per currency, and it is the number every payout run should read before it sends anything. Note that the figure comes back in minor units, so an NGN balance of 500000 is NGN 5,000.00. If this is the only thing you check, check that.
Now run Paystack: List Transactions without changing anything. On a fresh sandbox this legitimately returns an empty list, which is why the connection test uses the balance instead. What you are looking at is the envelope: Paystack answers with a status field, a message and a data array, and status is a boolean saying whether the operation succeeded rather than the HTTP status code. This integration reads both, so a node is reported as failed when either one says so.
Open a picker to confirm the option sources work. On Paystack: Create Transfer Recipient, open the Bank Code field and confirm it populates with bank and mobile money provider names, which are read from Paystack: List Banks. A Paystack bank code is not a SWIFT or sort code and the codes differ per country, so the picker is doing real work here rather than saving typing. Everything in this verify path is read-only and cannot reach any node that moves money, so it is safe to re-run whenever you want to check the connection.
Node reference
163 nodes, generated from the connector itself so this reference always matches what ships.
Read and query nodes 73
Paystack: Balance Ledger
paystack_balance_ledger
List every movement in and out of the balance, with the running balance after each. This is the reconciliation view: each row carries a difference, which is the amount that moved, and a balance, which is the total afterwards. Both are in minor units and they behave completely differently when aggregated, which the incremental declaration on this node states.
Paystack: Check Pending Charge
paystack_check_charge
Check whether a pending charge has settled into a final state. Paystack's own instruction is to wait at least 10 seconds before the first check and not to poll in a tight loop. Use this after a charge returned pending, or after any Charge call failed and the outcome is unknown. Reading is always the safe move on this API; retrying the charge is not.
Paystack: Check Slug Availability
paystack_check_page_slug_availability
Check whether a payment page slug is free before creating the page. Slugs are global across Paystack, not per integration, so an obvious one is usually taken.
Paystack: Fetch Balance
paystack_fetch_balance
Get the available balance on the integration, one row per currency, in minor units. Read this before a payout run: a bulk transfer larger than the balance fails partway through rather than being rejected up front. It takes no parameters.
Paystack: Fetch Bank Providers
paystack_list_dedicated_account_providers
List the banks that can issue a dedicated virtual account for this business. The list is per business rather than global, so read it instead of hardcoding a provider slug. It takes no parameters at all. This is the source for the provider pickers on the dedicated account nodes.
Paystack: Fetch Bulk Charge Batch
paystack_fetch_bulk_charge_batch
Get one bulk charge batch and its progress. total_charges and pending_charges together tell you how far through the batch Paystack is, which is the cheapest way to decide whether a workflow should keep waiting.
Paystack: Fetch Customer
paystack_fetch_customer
Get one customer by their CUSTOMER CODE or email address, with their saved authorizations, subscriptions and transaction history. Note that this endpoint takes the code while the direct debit endpoints on the same resource take the numeric id.
Paystack: Fetch Dedicated Account
paystack_fetch_dedicated_account
Get one dedicated virtual account with its bank, its number and the customer it is assigned to.
Paystack: Fetch Dispute
paystack_fetch_dispute
Get one dispute with the full transaction behind it, the message history and the deadline. Read this before answering a chargeback: the category and the customer's own messages say what the bank actually wants evidence of.
Paystack: Fetch Dispute Upload URL
paystack_fetch_dispute_upload_url
Get a signed URL for uploading evidence on a dispute, plus the fileName to quote afterwards. The signed URL grants upload rights to whoever holds it, so it is deliberately not redacted (that would break the only way to attach evidence) and should be treated as sensitive: use it in the next step of the workflow rather than logging or forwarding it. Upload the file with an HTTP node, then call Paystack: Update Dispute with the fileName.
Paystack: Fetch Mandate Authorizations
paystack_list_customer_mandate_authorizations
List one customer's direct debit mandates and their states. Read this before charging a mandate: a revoked or pending mandate cannot be debited, and the numeric authorization id here is what the activation charge node wants. Takes the customer's numeric id and offers no paging parameters.
Paystack: Fetch Order
paystack_fetch_order
Get one order by its numeric id, with its items, its buyer and its shipping details.
Paystack: Fetch Page
paystack_fetch_page
Get one hosted payment page by its numeric id, including its slug, its custom fields and any products attached to it.
Paystack: Fetch Payment Request
paystack_fetch_payment_request
Get one invoice by its numeric id, with its line items, its customer and whether it has been paid.
Paystack: Fetch Payment Session Timeout
paystack_fetch_payment_session_timeout
Read how long a customer has to complete a payment before the checkout session expires, in seconds. This is an integration wide setting and takes no parameters.
Paystack: Fetch Plan
paystack_fetch_plan
Get one plan by its code, with its amount, interval and the subscriptions attached to it.
Paystack: Fetch Product
paystack_fetch_product
Get one product by its numeric id, including its price, stock and whether it is still in stock.
Paystack: Fetch Product Orders
paystack_list_product_orders
List every order that includes a given product. This endpoint takes no paging parameters at all, so it returns whatever Paystack decides to return for that product.
Paystack: Fetch Refund
paystack_fetch_refund
Get one refund by its numeric id, with its status, the amount and the transaction it belongs to.
Paystack: Fetch Settlement Transactions
paystack_list_settlement_transactions
List the transactions that made up one settlement, which is how a single payout into the bank account is reconciled back to the individual payments behind it. Takes no paging parameters.
Paystack: Fetch Split
paystack_fetch_split
Get one split configuration with its member subaccounts and their shares. Takes the split's NUMERIC id, not the SPL_ code, which is a difference worth watching: the code is what goes on a transaction and the id is what addresses the split itself.
Paystack: Fetch Storefront
paystack_fetch_storefront
Get one storefront by its numeric id, with its slug, status and public URL.
Paystack: Fetch Storefront Orders
paystack_list_storefront_orders
List the orders placed through one storefront. This endpoint takes no paging parameters at all, so a busy shop returns whatever Paystack decides to return in one response.
Paystack: Fetch Subaccount
paystack_fetch_subaccount
Get one subaccount by its code, including the settlement bank and whether Paystack has verified the account.
Paystack: Fetch Subscription
paystack_fetch_subscription
Get one subscription with its plan, its customer, its next payment date and its invoice history.
Paystack: Fetch Terminal
paystack_fetch_terminal
Get one Terminal by its id, with its serial number, name, address and status.
Paystack: Fetch Terminal Event Status
paystack_fetch_terminal_event_status
Check whether an event you sent to a Terminal was delivered and acted on. Use it after Paystack: Send Terminal Event, since sending only queues the instruction.
Paystack: Fetch Terminal Status
paystack_fetch_terminal_status
Check whether a Terminal is online and available before sending it an event. Online means Paystack can reach it; available means it is not mid transaction.
Paystack: Fetch Transaction
paystack_fetch_transaction
Get one transaction by its NUMERIC id. If what you hold is your own reference string rather than an id, use Paystack: Verify Transaction instead. This endpoint returns the same record with the customer, the authorization and the fee breakdown attached.
Paystack: Fetch Transaction Timeline
paystack_fetch_transaction_timeline
Get the step by step log of one transaction, from the moment the customer opened the checkout to the final outcome: which channel was chosen, how long each step took, which attempts failed and what the gateway said. This is the node to reach for when a customer says the payment did not work and the transaction record alone does not explain why.
Paystack: Fetch Transfer
paystack_fetch_transfer
Get one transfer by its TRANSFER CODE, with the recipient, the fee charged and the current status. Note the pairing across this resource: fetch takes the code while verify takes your own reference, and they are different values.
Paystack: Fetch Transfer Recipient
paystack_fetch_transfer_recipient
Get one payout destination by its recipient code, including the account number and the name the bank returned. Worth reading before a large transfer, to confirm the destination is still what you think it is.
Paystack: Fetch Virtual Terminal
paystack_fetch_virtual_terminal
Get one Virtual Terminal by its code, with its destinations and whether it is still active.
Paystack: Generate Subscription Update Link
paystack_generate_subscription_update_link
Get a link the customer can open to change the card their subscription bills. The link is sensitive: anyone holding it can manage that subscription's payment method, so send it to the customer rather than logging it or posting it into a shared channel.
Paystack: List Apple Pay Domains
paystack_list_apple_pay_domains
List the domains registered for Apple Pay on this integration. An empty array means none have been added, which is a normal answer rather than an error. This endpoint offers cursor paging only: there is no page number and no page size parameter at all.
Paystack: List Banks
paystack_list_banks
List the banks and mobile money providers Paystack supports, with the CODE each one is addressed by. Bank codes differ per country and are not SWIFT codes, so filter by country and read the codes rather than assuming them. This is the source for every bank code picker in this connector.
Paystack: List Bulk Charge Batches
paystack_list_bulk_charge_batches
List the bulk charge batches on the integration, each with its batch code and its progress counters. Use the batch code to read the individual charges or to pause the run.
Paystack: List Charges in a Batch
paystack_list_bulk_charge_batch_charges
List the individual charges inside one bulk batch, with the outcome of each. Filter by status to pull just the failures, which is the usual reason to call this: a batch reports complete whether every charge succeeded or every one of them failed.
Paystack: List Countries
paystack_list_countries
List the countries Paystack supports, with their currencies and the integration types available in each. Worth reading rather than assuming: merchant signup is limited to Nigeria, Ghana, South Africa and Kenya, with more in beta, and this endpoint is the live answer. It takes no parameters and is the source for the country pickers in this connector.
Paystack: List Customers
paystack_list_customers
List the customers on the integration. This is the source for every customer picker in this connector. Two oddities worth knowing: it uses the camelCase page size while offering cursor paging as well, and Paystack's spec types both paging parameters as STRINGS here while typing them as integers elsewhere. The connector sends whatever you set. Rows carry real names, emails and phone numbers.
Paystack: List Dedicated Accounts
paystack_list_dedicated_accounts
List the dedicated virtual accounts on the integration and who each is assigned to. Account numbers are real bank details belonging to your customers, so treat the output accordingly.
Paystack: List Disputes
paystack_list_disputes
List the chargebacks customers have filed, with the disputed transaction and the deadline for each. Filter on awaiting-merchant-feedback to find the ones that need an answer: the dueAt field is a real deadline, and a dispute that passes it without evidence is normally decided against the merchant.
Paystack: List Mandate Authorizations
paystack_list_mandate_authorizations
List every direct debit mandate on the integration, filtered by state. This endpoint has a pagination shape of its own, used nowhere else in the API: a bare cursor string plus per_page, with no page number and no use cursor flag. Follow the cursor returned in meta to walk it.
Paystack: List Orders
paystack_list_orders
List the orders created on the integration, with their buyers and statuses.
Paystack: List Pages
paystack_list_pages
List the hosted payment pages on the integration, with their slugs and whether each is active.
Paystack: List Payment Requests
paystack_list_payment_requests
List the invoices issued on the integration, filtered by customer, status, currency or date. Archived requests are not returned, which is what archiving is for. This is the source for the payment request pickers in this connector.
Paystack: List Plans
paystack_list_plans
List the recurring plans on the integration. This is the source for every plan picker in this connector.
Paystack: List Products
paystack_list_products
List the products on the integration, with stock levels and how many of each have sold. This is the source for the product pickers in this connector.
Paystack: List Refunds
paystack_list_refunds
List the refunds issued on the integration, with the transaction behind each and its current status. Watch for the needs-attention status, which means the refund could not be delivered and needs bank details through Paystack: Retry Refund.
Paystack: List Settlements
paystack_list_settlements
List the payouts Paystack has made to your own settlement bank account. Worth knowing before building a report on this: the OpenAPI specification declares only page and perPage on this endpoint, with no date range at all, so unlike transactions and transfers it cannot be windowed by date through the documented parameters. Use the escape hatch below if Paystack accepts date filters it has not documented, and page back through the list otherwise.
Paystack: List Splits
paystack_list_splits
List the transaction splits on the integration. Note the paging spelling: this is one of the six endpoints using per_page with an underscore, and the connector maps it for you.
Paystack: List States (AVS)
paystack_list_avs_states
List the states Paystack accepts for address verification in a country. Use it to fill the state field on Paystack: Submit Address, because a state name Paystack does not recognise fails the verification step rather than being approximated.
Paystack: List Storefront Products
paystack_list_storefront_products
List the products currently in one storefront. No paging parameters are offered on this endpoint.
Paystack: List Storefronts
paystack_list_storefronts
List the storefronts on the integration. This is the source for the storefront pickers in this connector.
Paystack: List Subaccounts
paystack_list_subaccounts
List the subaccounts on the integration, with their settlement bank details and percentage share. This is the source for every subaccount picker in this connector.
Paystack: List Subscriptions
paystack_list_subscriptions
List subscriptions, optionally filtered to one plan or one customer. Each row carries the subscription code and the email token, which are the two values the disable and enable nodes need together.
Paystack: List Terminals
paystack_list_terminals
List the physical Terminals linked to the integration. This list is CURSOR ONLY: it offers next and previous and per_page and has no page parameter at all, unlike almost every other list on this API, so walk it by following the next cursor. It is the source for the Terminal pickers in this connector.
Paystack: List Transaction Disputes
paystack_list_transaction_disputes
List every dispute filed against one transaction. Use it when a customer queries a payment and you need to know whether a chargeback is already running before issuing a refund, since doing both means paying twice.
Paystack: List Transactions
paystack_list_transactions
List the transactions on the integration, filtered by date, status, channel, terminal, customer, subaccount or split. This is the main reporting list and the source for the transaction pickers in this connector. Two things to know about paging here. It spells the page size per_page with an underscore, unlike most Paystack lists, and the connector maps that for you. And it is one of the six endpoints offering cursor paging: for a full sweep, turn cursor paging on and follow the next cursor, because an offset walk over a list that is still growing skips and repeats rows.
Paystack: List Transfer Recipients
paystack_list_transfer_recipients
List the payout destinations registered on the integration, with the bank account behind each. This is the source for every recipient picker in this connector. It is one of the six endpoints spelling the page size per_page with an underscore, and one of the six offering cursor paging. Rows carry real bank account numbers, so keep the output out of shared logs.
Paystack: List Transfers
paystack_list_transfers
List the transfers made from the integration, filtered by date, recipient or status. Like the transaction list, this endpoint spells the page size per_page with an underscore and offers cursor paging, both of which the connector handles for you. Check for the reversed and failed statuses when reconciling: a transfer that left the balance is not the same as one that arrived.
Paystack: List Virtual Terminals
paystack_list_virtual_terminals
List the Virtual Terminals on the integration with their codes and destinations. This is the source for the Virtual Terminal pickers in this connector.
Paystack: Payment Request Totals
paystack_payment_request_totals
Get the totals of pending and successful invoices, by currency. It takes no parameters at all, so it always describes the whole integration rather than a window. Amounts are in minor units.
Paystack: Requery Dedicated Account
paystack_requery_dedicated_account
Ask Paystack to re-check a dedicated account for transfers it may not have picked up yet. Use this when a customer says they sent money and no transaction appeared. The response only confirms the requery was accepted; the transaction itself arrives by webhook if there is one to find.
Paystack: Resolve Account Number
paystack_resolve_account_number
Look up the name on a bank account before sending money to it. Run this before creating a transfer recipient or retrying a refund, and check the name that comes back is the person you mean: this is the last cheap moment to catch a mistyped account number, because a completed transfer cannot be recalled through this API.
Paystack: Resolve Card BIN
paystack_resolve_card_bin
Look up what a card's first six digits say about it: the issuing bank, the country, the brand and whether it is a debit or credit card. Used for routing decisions and for showing the right card art. The first six digits are not sensitive on their own, but they come from a card number that is.
Paystack: Transaction Totals
paystack_transaction_totals
Get the total transaction count and volume for a date window, broken down by currency, plus the pending transfer totals. One aggregate for the whole window rather than a row per day, so it answers how much came in without paging the transaction list. Volumes are in minor units.
Paystack: Validate Order
paystack_validate_order
Validate a pay for me order, where one person creates the order and another pays for it. Note that this endpoint takes the order CODE while its siblings take the numeric id, which is the same inconsistency that runs through this API.
Paystack: Verify Authorization
paystack_verify_customer_authorization
Check whether the customer completed an authorization request. This is the node that tells you a mandate is actually usable, rather than the redirect.
Paystack: Verify Payment Request
paystack_verify_payment_request
Check whether an invoice has been paid. An archived request cannot be verified, which is one reason to archive only what is genuinely finished.
Paystack: Verify Storefront Slug
paystack_verify_storefront_slug
Check whether a storefront slug is available before creating the shop. Slugs are global, so check before building anything around a name.
Paystack: Verify Transaction
paystack_verify_transaction
Confirm what actually happened to a transaction, by your own reference. This is the node that decides whether to fulfil an order. Check TWO things in the response and not just one: data.status must be the string success, AND data.amount and data.currency must match what you expected to charge. Amounts are in minor units. Verifying is also the correct way to resolve a charge whose outcome you do not know after a timeout, because retrying the charge is not safe.
Paystack: Verify Transfer
paystack_verify_transfer
Check the outcome of a transfer using YOUR OWN reference. This is the node to run when a transfer call timed out and you do not know whether the money went: read the outcome here before deciding anything, and if you do retry, retry with the same reference.
Action nodes 90
Paystack: Add Dispute Evidence
paystack_add_dispute_evidence
Submit the written evidence for a dispute: who the customer was, what they bought and where it was delivered. This is what the bank reads when deciding a chargeback. It contains a real person's contact details and address, so send it once and do not copy it into logs or datatables.
Paystack: Add Products to Page
paystack_add_page_products
Attach products to a payment page so buyers can pick from them. This only works on a page created with the product type; adding products to any other kind of page is rejected.
Paystack: Add Products to Storefront
paystack_add_storefront_products
Put existing products into a storefront so buyers can see them. Create the products first with Paystack: Create Product.
Paystack: Add Split Code to Virtual Terminal
paystack_add_virtual_terminal_split_code
Attach a split to a Virtual Terminal so every payment it takes is divided between the main account and the split's subaccounts. This changes where future money goes, so check the split's members before attaching it.
Paystack: Add Subaccount to Split
paystack_add_split_subaccount
Add a subaccount to a split, or change the share of one already in it. This same node does both: sending a subaccount that is already a member updates its share rather than failing. Future transactions using this split code are divided the new way.
Paystack: Archive Payment Request
paystack_archive_payment_request
Archive an invoice so it stops appearing in listings. This is filed as destructive because the API offers no unarchive endpoint: an archived request cannot be verified and is no longer returned by Paystack: List Payment Requests, so from the connector's point of view it is gone. Reversing it means the Paystack dashboard.
Paystack: Assign Dedicated Account
paystack_assign_dedicated_account
Create the customer, validate them and issue a dedicated account in one call, which is the shortcut for onboarding someone who does not exist on the integration yet. It takes identity documents: a BVN in Nigeria plus a bank account to match it against. Those are sensitive personal identifiers, so pass them straight through and do not persist them in workflow variables, logs or datatables.
Paystack: Assign Destination to Virtual Terminal
paystack_assign_virtual_terminal_destination
Add WhatsApp numbers that get notified when this Virtual Terminal takes a payment. Adding a number means a real person starts receiving payment notifications, so confirm the number belongs to whoever should see them.
Paystack: Bulk Create Transfer Recipients
paystack_bulk_create_transfer_recipients
Register many payout destinations at once. The response separates successes from errors, so read both halves rather than assuming the whole batch landed. Duplicate account numbers return the existing recipients instead of creating new ones. Verify the account numbers before sending: a bad one here becomes a recipient code that later gets paid.
Paystack: Charge Authorization
paystack_charge_authorization
Charge a card or account the customer has already authorized, with no further action from them. This is how recurring billing, saved card checkout and top ups work. MOVES REAL MONEY on a live key (sk_live_). This cannot be undone through this connector. A test key (sk_test_) runs the same call against Paystack's sandbox and touches no real funds. NOT SAFELY RETRYABLE. Paystack has no Idempotency-Key header, and this endpoint documents no idempotency mechanism, so a retry after a timeout can charge twice. If a call times out, read the outcome back (verify by reference, or list and match) before retrying. Only an authorization whose reusable flag is true can be charged this way, and the email must be the one the authorization was created for.
Paystack: Commission Terminal
paystack_commission_terminal
Link a physical device to this integration by its serial number, so payments taken on it land here. Reversible with Paystack: Decommission Terminal.
Paystack: Create Charge
paystack_create_charge
Charge a customer directly on a channel you choose, without the hosted checkout: card, bank account, USSD, mobile money or EFT. MOVES REAL MONEY on a live key (sk_live_). This cannot be undone through this connector. A test key (sk_test_) runs the same call against Paystack's sandbox and touches no real funds. NOT SAFELY RETRYABLE. Paystack has no Idempotency-Key header, and this endpoint documents no idempotency mechanism, so a retry after a timeout can charge twice. If a call times out, read the outcome back (verify by reference, or list and match) before retrying. Expect this call to return a PENDING state rather than a final one: banks routinely demand a PIN, an OTP, a phone number, a birthday or an address next, and the response status tells you which of the Paystack Submit nodes to call with the same reference. Building this flow means handling every one of those branches; if that is more than the workflow needs, use Initialize Transaction and let Paystack's own checkout page handle them.
Paystack: Create Customer
paystack_create_customer
Create a customer record and get back a customer code. Email is the key: a transaction for an unknown email creates the customer anyway, so this node mostly exists to attach a name and phone before the first payment. Creating one with an email that already exists returns the existing record rather than making a duplicate.
Paystack: Create Dedicated Account
paystack_create_dedicated_account
Issue a permanent bank account number to an existing customer, so anything they transfer into it lands on your integration already matched to them. The customer must exist first and, in Nigeria, must be validated before an account can be issued. Dedicated accounts are a Paystack feature that has to be enabled on the business, and availability is limited to Nigeria and Ghana.
Paystack: Create Order
paystack_create_order
Create an order for a set of products, with the buyer's details and a shipping address. Creating the order does not take payment; it produces an order the buyer then pays for. Item amounts are in minor units.
Paystack: Create Page
paystack_create_page
Create a hosted payment page with its own public URL, so money can be collected without any website of your own. Set the type to decide what the page sells: a one off payment, a subscription to a plan, a product, or a plan signup. Check the slug is free first with Paystack: Check Slug Availability, because the slug is the public URL.
Paystack: Create Payment Request
paystack_create_payment_request
Issue an invoice to a customer and get back a request code they can pay. This takes no money by itself, but with send notification on it emails a real customer, so a workflow that fires twice sends two invoices. Create it as a draft first if anything needs checking before the customer sees it.
Paystack: Create Plan
paystack_create_plan
Define a recurring billing plan: an amount, an interval and a name. Creating a plan charges nobody. Money starts moving when a customer is subscribed to it, either through Paystack: Create Subscription or by passing the plan code into a checkout.
Paystack: Create Product
paystack_create_product
Create a product that can be sold through a payment page or a storefront. The price is in minor units like every other amount on this API, which is the mistake to watch for here because a price reads like a normal number in a product catalogue.
Paystack: Create Refund
paystack_create_refund
Return money to a customer for a completed transaction. MOVES REAL MONEY on a live key (sk_live_). This cannot be undone through this connector. A test key (sk_test_) runs the same call against Paystack's sandbox and touches no real funds. A refund cannot be cancelled or reversed through this API once Paystack has accepted it. NOT SAFELY RETRYABLE. Paystack has no Idempotency-Key header, and this endpoint documents no idempotency mechanism, so a retry after a timeout can charge twice. If a call times out, read the outcome back (verify by reference, or list and match) before retrying. Two important details. Leaving the amount blank refunds the FULL transaction, so a workflow that forgets to set it refunds everything. And check for an open dispute on the transaction first with Paystack: List Transaction Disputes, because refunding a payment that is also being charged back pays the customer twice.
Paystack: Create Split
paystack_create_split
Define how one payment is divided between the main account and one or more subaccounts, and get back a split code to attach to transactions. Creating a split moves no money; it decides where money goes on every transaction that later carries the code, so an error here is quiet and repeated.
Paystack: Create Storefront
paystack_create_storefront
Create a hosted digital shop with its own URL, holding products and taking orders. The storefront is created unpublished; Paystack: Publish Storefront is the separate step that makes it publicly reachable. Check the slug is free first.
Paystack: Create Subaccount
paystack_create_subaccount
Register a vendor, partner or seller who should receive a share of payments. A subaccount is a real bank account Paystack will settle money into, so the account number and bank code have to be right: Paystack: Resolve Account Number confirms the name on an account before you create the subaccount around it. Creating one moves no money by itself, but every transaction routed to it afterwards does.
Paystack: Create Subscription
paystack_create_subscription
Put a customer on a recurring plan. MOVES REAL MONEY on a live key (sk_live_). This cannot be undone through this connector. A test key (sk_test_) runs the same call against Paystack's sandbox and touches no real funds. This is filed as a money moving action because it starts a schedule of charges against the customer's saved authorization, and every one of those charges is real. Paystack bills the first one immediately unless a start date is set. NOT SAFELY RETRYABLE. Paystack has no Idempotency-Key header, and this endpoint documents no idempotency mechanism, so a retry after a timeout can charge twice. If a call times out, read the outcome back (verify by reference, or list and match) before retrying. Creating the same subscription twice bills the customer twice per period, so check for an existing active subscription before creating one.
Paystack: Create Transfer Recipient
paystack_create_transfer_recipient
Register a bank account or mobile money wallet that money can be sent to, and get back a recipient code. No money moves here, but this is where a mistake becomes permanent: every later transfer names only the recipient code, so a wrong account number is invisible from that point on. Run Paystack: Resolve Account Number first and check the name that comes back is the person you mean. Sending a duplicate account number returns the EXISTING recipient rather than creating a second one.
Paystack: Create Virtual Terminal
paystack_create_virtual_terminal
Create a Virtual Terminal, which lets a merchant take bank transfer payments in person by showing a code, with the confirmation arriving on a WhatsApp number. Destinations are those notification numbers and at least one is required. Note that this is one of the few endpoints in the API whose spec declares a JSON request body rather than form encoding.
Paystack: Deactivate Authorization
paystack_deactivate_customer_authorization
Revoke a saved authorization so it can no longer be charged. This is filed as destructive because there is no reactivate endpoint: the customer has to authorize again from scratch. Any subscription relying on this authorization stops billing, so check what depends on it before revoking. Doing this when a customer asks to stop paying is the correct use.
Paystack: Deactivate Dedicated Account
paystack_deactivate_dedicated_account
Release a dedicated virtual account from its customer. The account number stops accepting transfers, and a customer who has saved it as a payee will find their next transfer fails. There is no reactivate endpoint on this API, so this is one way from the connector: the customer would need a new account issued, with a different number.
Paystack: Deactivate Virtual Terminal
paystack_deactivate_virtual_terminal
Switch off a Virtual Terminal so it stops accepting payments. The API offers no matching reactivate endpoint, so treat this as one way from the connector's point of view: reversing it means the Paystack dashboard or a new terminal.
Paystack: Decommission Terminal
paystack_decommission_terminal
Unlink a physical device from this integration. The device stops taking payments into this account immediately, so a shop with one terminal stops trading the moment this runs. It can be commissioned again, but not by accident and not without the serial number.
Paystack: Delete Product
paystack_delete_product
Delete a product. There is no undelete endpoint on this API, so this cannot be reversed through the connector. Pages and storefronts that list the product lose it. If the intent is to stop selling something rather than to erase it, set the quantity to zero with Paystack: Update Product instead.
Paystack: Delete Storefront
paystack_delete_storefront
Delete a storefront permanently. There is no undelete endpoint, so this cannot be reversed through the connector, and the public URL stops working immediately for anyone holding a link. To take a shop offline without erasing it, update it rather than deleting it.
Paystack: Delete Transfer Recipient
paystack_delete_transfer_recipient
Deactivate a payout destination so it can no longer be paid. Paystack's own wording is that this sets the recipient to inactive rather than erasing it, and past transfers are untouched, but there is no reactivate endpoint on this API: bringing it back means creating the recipient again. A scheduled payout naming this code starts failing from the moment it runs.
Paystack: Direct Debit Activation Charge
paystack_direct_debit_activation_charge
Trigger the small activation charge that brings an inactive direct debit mandate to life for one customer. MOVES REAL MONEY on a live key (sk_live_). This cannot be undone through this connector. A test key (sk_test_) runs the same call against Paystack's sandbox and touches no real funds. It is a real debit against the customer's bank account, small but real, and it cannot be undone through this connector. NOT SAFELY RETRYABLE. Paystack has no Idempotency-Key header, and this endpoint documents no idempotency mechanism, so a retry after a timeout can charge twice. If a call times out, read the outcome back (verify by reference, or list and match) before retrying.
Paystack: Disable Subscription
paystack_disable_subscription
Stop a subscription from billing again. It is reversible with Paystack: Enable Subscription and it does not refund anything already charged. This endpoint needs BOTH the subscription code and the email token, which is the trap: the token is a separate field on the subscription record, and sending the code alone fails.
Paystack: Disable Transfer OTP
paystack_disable_transfer_otp
Begin turning off the one time password requirement on transfers, for the WHOLE integration. This is filed as destructive because it removes a security control rather than because it moves money: with it off, anything holding the secret key can send money out of the balance with no second factor at all, which is exactly the exposure that matters if a key ever leaks. Paystack sends a confirming password to the account owner, and Paystack: Finalize Disabling Transfer OTP completes it. Bulk transfers require this to be off, which is the usual reason people run it.
Paystack: Duplicate Storefront
paystack_duplicate_storefront
Copy a storefront into a new one, which is the quick way to start a seasonal shop from last season's. The copy gets its own id and slug and starts unpublished.
Paystack: Enable Subscription
paystack_enable_subscription
Restart a disabled subscription. Billing resumes, so this returns the customer to a schedule of real charges on a live key. Like disable, it needs BOTH the subscription code and the email token.
Paystack: Enable Transfer OTP
paystack_enable_transfer_otp
Turn the one time password requirement back on for transfers, so every payout needs a second factor again. This is the restoring half of the pair and takes no parameters. Run it as soon as a bulk payout run is finished.
Paystack: Export Disputes
paystack_export_disputes
Build a CSV of disputes for a window and return a short lived download link. Fetch the link promptly with a following HTTP node; the response carries its own expiry.
Paystack: Export Transactions
paystack_export_transactions
Ask Paystack to build a CSV of transactions for a window and return a download link. The response carries a path and an expiresAt, so the link is short lived and must be fetched promptly by a following HTTP node or worker. Use this instead of paging the transaction list when the window is large and the destination is a spreadsheet rather than a workflow.
Paystack: Export Transfers
paystack_export_transfers
Build a CSV of transfers for a window and return a download link. Useful for reconciling a payout run against your own records without paging the transfer list.
Paystack: Finalize Disabling Transfer OTP
paystack_finalize_disable_transfer_otp
Complete turning off the transfer one time password requirement, using the password Paystack sent the account owner. After this runs, every transfer from this integration goes out on the API key alone. Turn it back on with Paystack: Enable Transfer OTP as soon as the batch that needed it is done.
Paystack: Finalize Payment Request
paystack_finalize_payment_request
Turn a draft invoice into a live one the customer can pay. This is the step that makes a draft real, and Paystack notifies the customer as part of it, so finalize only what is ready to be seen.
Paystack: Finalize Transfer
paystack_finalize_transfer
Release a transfer that is waiting on a one time password. MOVES REAL MONEY on a live key (sk_live_). This cannot be undone through this connector. A test key (sk_test_) runs the same call against Paystack's sandbox and touches no real funds. This is the step that actually sends the money for an integration with the transfer OTP requirement switched on, and it cannot be recalled afterwards.
Paystack: Initialize Authorization
paystack_initialize_customer_authorization
Start the process of getting a reusable authorization from a customer, so you can charge them later without them being present. The documented channel is direct_debit. This node creates the request and returns a URL for the customer to approve it; nothing is charged until they do and you call a charge node.
Paystack: Initialize Direct Debit
paystack_initialize_direct_debit
Start linking a customer's bank account for direct debit, so future charges can be taken from it. This endpoint takes the customer's NUMERIC id, while fetch and update on the same resource take the CUS_ code. The account and address objects carry personal banking data and should be passed through without being stored.
Paystack: Initialize Transaction
paystack_initialize_transaction
Start a checkout and get back a Paystack hosted payment URL for the customer to open. This node itself moves no money: it creates a pending transaction and returns authorization_url, access_code and reference. The customer pays on that page, and you learn the outcome from the charge.success webhook or from Paystack: Verify Transaction. Never treat the browser redirect back to your callback URL as proof of payment; it can be replayed and it can simply fail to happen.
Paystack: Initiate Bulk Charge
paystack_initiate_bulk_charge
Charge many saved authorizations in one batch. Paystack queues the batch and works through it, so the response is a batch code rather than a set of outcomes, and the results arrive by webhook or through Paystack: List Charges in a Batch. MOVES REAL MONEY on a live key (sk_live_). This cannot be undone through this connector. A test key (sk_test_) runs the same call against Paystack's sandbox and touches no real funds. It debits every authorization in the list, so a mistake here is multiplied by the size of the batch. NOT SAFELY RETRYABLE. Paystack has no Idempotency-Key header, and this endpoint documents no idempotency mechanism, so a retry after a timeout can charge twice. If a call times out, read the outcome back (verify by reference, or list and match) before retrying. Re-sending a batch charges everyone in it again.
Paystack: Initiate Bulk Transfer
paystack_initiate_bulk_transfer
Send money to many recipients in one request, which is how payroll and vendor payout runs are done. MOVES REAL MONEY on a live key (sk_live_). This cannot be undone through this connector. A test key (sk_test_) runs the same call against Paystack's sandbox and touches no real funds. It pays everyone in the list, so an error here is multiplied by the size of the batch and none of it can be recalled. Paystack requires the transfer OTP requirement to be DISABLED before this endpoint works at all, which means the account has already given up its second factor on payouts. Give every entry its own stable reference so a retry cannot pay anyone twice.
Paystack: Initiate Transfer
paystack_initiate_transfer
Send money out of the Paystack balance to a transfer recipient's bank account or mobile money wallet. MOVES REAL MONEY on a live key (sk_live_). This cannot be undone through this connector. A test key (sk_test_) runs the same call against Paystack's sandbox and touches no real funds. Once a transfer completes there is no recall endpoint on this API: getting it back means asking the person who received it. Transfers are the ONE place Paystack documents idempotency, through the reference below, and that only works if a retry sends the SAME reference. If the account requires a one time password, the transfer is held at status otp until Paystack: Finalize Transfer releases it.
Paystack: Partial Debit
paystack_partial_debit
Take what you can from a saved authorization when the full amount may not be there. Paystack debits up to the amount and settles for whatever the account holds, subject to the minimum you set. Built for partial recovery on a failed recurring charge. MOVES REAL MONEY on a live key (sk_live_). This cannot be undone through this connector. A test key (sk_test_) runs the same call against Paystack's sandbox and touches no real funds. NOT SAFELY RETRYABLE. Paystack has no Idempotency-Key header, and this endpoint documents no idempotency mechanism, so a retry after a timeout can charge twice. If a call times out, read the outcome back (verify by reference, or list and match) before retrying.
Paystack: Pause Bulk Charge Batch
paystack_pause_bulk_charge_batch
Stop Paystack working through a bulk charge batch. Charges already processed are not undone; only the remaining ones are held. Resume with Paystack: Resume Bulk Charge Batch. Note that Paystack implements this as a GET request even though it changes state, so it is not a safe read despite the method.
Paystack: Publish Storefront
paystack_publish_storefront
Make a storefront publicly reachable at its URL. Anyone with the link can then see the products and buy them, so publish when the shop is actually ready rather than as part of setup.
Paystack: Register Apple Pay Domain
paystack_register_apple_pay_domain
Register one domain or subdomain so Apple Pay can be offered on it. Paystack accepts exactly one domain per call, so a workflow registering several needs a loop. The domain has to serve Apple's verification file before registration succeeds.
Paystack: Remove Split Code from Virtual Terminal
paystack_remove_virtual_terminal_split_code
Detach a split from a Virtual Terminal, so its payments stop being divided and settle wholly to the main account. This is one of two endpoints on this API that send a DELETE request WITH a body, which many HTTP clients quietly refuse to do. This connector sends it.
Paystack: Remove Split from Dedicated Account
paystack_remove_dedicated_account_split
Stop dividing payments into a dedicated account, so they settle wholly to the main account again. This is the second of the two endpoints on this API that send a DELETE request WITH a body; the connector sends it.
Paystack: Remove Subaccount from Split
paystack_remove_split_subaccount
Take a subaccount out of a split. The subaccount itself is not deleted and past transactions are untouched, but every future transaction using this split stops paying that vendor, so check the split membership afterwards rather than assuming.
Paystack: Resend Transfer OTP
paystack_resend_transfer_otp
Send the account owner a new one time password for a transfer that is waiting on one. It sends a real message to a real person, so it is not a safe read, but it moves no money by itself.
Paystack: Resolve Dispute
paystack_resolve_dispute
Close a dispute with a decision. MOVES REAL MONEY on a live key (sk_live_). This cannot be undone through this connector. A test key (sk_test_) runs the same call against Paystack's sandbox and touches no real funds. Accepting a chargeback returns the disputed amount to the customer, and the decision cannot be reopened through this API. Read the dispute and its evidence first, and be certain the refund amount in minor units is the figure you mean.
Paystack: Resume Bulk Charge Batch
paystack_resume_bulk_charge_batch
Restart a paused bulk charge batch. Paystack picks up the remaining charges and debits them, so this resumes real money movement on a live key. Like pause, Paystack implements it as a GET request that changes state.
Paystack: Retry Refund
paystack_retry_refund
Retry a refund that came back needing attention, by supplying the customer's bank account. MOVES REAL MONEY on a live key (sk_live_). This cannot be undone through this connector. A test key (sk_test_) runs the same call against Paystack's sandbox and touches no real funds. This sends the refund to whatever account you provide, so a wrong account number here pays a stranger and there is no recall on this API. Confirm the account with Paystack: Resolve Account Number first, and confirm the name it returns is the customer's.
Paystack: Send Payment Request Notification
paystack_notify_payment_request
Email the customer a reminder about an unpaid invoice. This sends a real email to a real person every time it runs, so a reminder loop with no guard is how a customer gets nine emails in a morning. Check the status first and stop when it is paid.
Paystack: Send Subscription Update Link
paystack_send_subscription_update_link
Have Paystack email the customer a link for updating their subscription card. This sends a real email to a real person, so it is not a safe read even though it changes no data. Use it when a recurring charge failed because the card expired.
Paystack: Send Terminal Event
paystack_send_terminal_event
Push an instruction to a physical Paystack Terminal: show an invoice, process a transaction or print a receipt. The device has to be online, so check with Paystack: Fetch Terminal Status first rather than sending into the dark. Sending a transaction event asks the device to collect a payment, which then happens in the real world with a real card.
Paystack: Set Customer Risk Action
paystack_set_customer_risk_action
Allow or deny a customer. Setting deny BLOCKS them from transacting on the integration at all, which is a real consequence for a real person and should not be automated on a thin signal. It is reversible by setting the action back to allow or default, so it is a write rather than a destructive action, but treat an automated blocklist as something a human should be able to see and undo.
Paystack: Split Dedicated Account Transaction
paystack_add_dedicated_account_split
Make every payment into a dedicated account divide between accounts, either through a stored split or straight to one subaccount. This changes where future money settles, so confirm the split membership first.
Paystack: Submit Address
paystack_submit_address
Continue a charge that came back asking for address verification. All four address fields plus the reference are required. The state value must be one Paystack recognises for the country, which Paystack: List States (AVS) returns.
Paystack: Submit Birthday
paystack_submit_birthday
Continue a charge that came back asking for the customer's date of birth, which some banks use as a verification step. Send it with the same reference. Personal data: this value belongs to the customer's bank verification and should not be stored in the workflow.
Paystack: Submit OTP
paystack_submit_otp
Continue a charge that came back asking for a one time password. Send the OTP the customer received, with the same reference. This step commonly completes the debit, so it moves real money on a live key. One time passwords expire quickly, so a workflow that parks this step in a queue will fail on arrival.
Paystack: Submit PIN
paystack_submit_pin
Continue a charge that came back asking for the card PIN. Send the PIN with the same reference the charge returned. This step can complete the debit, so it moves real money on a live key. The PIN is customer secret material and must not be logged, stored or carried in a variable beyond this step.
Paystack: Submit Phone
paystack_submit_phone
Continue a charge that came back asking for the customer's phone number. Send it with the same reference. This step usually advances the charge to a one time password step rather than completing it, so it is filed as a write rather than a money movement, but it is part of a live payment flow.
Paystack: Trigger Activation Charge
paystack_trigger_direct_debit_activation_charge
Trigger activation charges for MANY customers at once. MOVES REAL MONEY on a live key (sk_live_). This cannot be undone through this connector. A test key (sk_test_) runs the same call against Paystack's sandbox and touches no real funds. Every customer id in the list gets a real debit against their bank account, so the blast radius is the length of the array. NOT SAFELY RETRYABLE. Paystack has no Idempotency-Key header, and this endpoint documents no idempotency mechanism, so a retry after a timeout can charge twice. If a call times out, read the outcome back (verify by reference, or list and match) before retrying. This is one of the few endpoints in the API whose spec declares a JSON body rather than form encoding.
Paystack: Unassign Destination from Virtual Terminal
paystack_unassign_virtual_terminal_destination
Stop notifying one or more numbers when this Virtual Terminal takes a payment. Note that the field is called targets here while the assign node calls it destinations, which is Paystack's naming rather than ours.
Paystack: Unregister Apple Pay Domain
paystack_unregister_apple_pay_domain
Remove a domain from Apple Pay. Apple Pay stops being offered on that domain immediately, so a live checkout loses a payment method the moment this runs. Re-registering is possible but needs the verification file in place again. This is a DELETE request carrying a body, which some HTTP clients refuse; the connector sends it.
Paystack: Update Customer
paystack_update_customer
Change a customer's name, phone or metadata. The email address cannot be changed here, because it is the key Paystack identifies the customer by.
Paystack: Update Dispute
paystack_update_dispute
Set the amount you are willing to refund on a dispute, and attach the evidence file you uploaded. This records a position and does not itself move money; Paystack: Resolve Dispute is the step that does. The amount is in minor units.
Paystack: Update Page
paystack_update_page
Change a payment page's name, description or amount, or switch it off. Setting active to false stops the public URL accepting payments, which is the safe way to retire a page rather than leaving a live link collecting money.
Paystack: Update Payment Request
paystack_update_payment_request
Change an invoice: its amount, its line items, its due date or who it is addressed to. Changing an invoice the customer has already seen changes what they are being asked to pay, so send a notification or tell them another way.
Paystack: Update Payment Session Timeout
paystack_update_payment_session_timeout
Change how long a checkout session stays open, for the WHOLE integration and every customer on it. A short timeout abandons payments that were nearly finished; a long one holds inventory and stock counts open. Read the current value first, because this is a single global setting with no per transaction override. This is one of the few endpoints whose spec declares a JSON body.
Paystack: Update Plan
paystack_update_plan
Change a plan's name, amount or interval. Read this before changing an amount: existing subscriptions on the plan bill at the new figure from their next charge onward, so a mistyped amount here silently changes what every current subscriber pays. Check who is on the plan first with Paystack: List Subscriptions.
Paystack: Update Product
paystack_update_product
Change a product's name, description, price or stock. A new price applies to future purchases only and is in minor units.
Paystack: Update Split
paystack_update_split
Rename a split, activate or deactivate it, or change who pays the Paystack fee. To change the member subaccounts or their shares, use the Add Subaccount and Remove Subaccount nodes instead. Note that the spec types this endpoint's id as a string while the other three split endpoints type it as an integer; the same value works for both.
Paystack: Update Storefront
paystack_update_storefront
Change a storefront's name, slug or description. Changing the slug changes the public URL, so any link already shared stops working.
Paystack: Update Subaccount
paystack_update_subaccount
Change a subaccount's details or its share of transactions. Changing the settlement bank or account number redirects where that vendor's money lands, so treat it with the same care as creating one, and re-verify the account number first. Setting active to false stops future settlements to it.
Paystack: Update Terminal
paystack_update_terminal
Rename a Terminal or change the address recorded against it. Useful for keeping reporting readable when devices move between branches.
Paystack: Update Transfer Recipient
paystack_update_transfer_recipient
Change the name or email on a payout destination. Note what this endpoint does NOT accept: the account number and bank code cannot be changed here, so correcting a wrong account means creating a new recipient and using that code instead.
Paystack: Update Virtual Terminal
paystack_update_virtual_terminal
Rename a Virtual Terminal. The name is the only field this endpoint accepts; destinations and split codes have their own nodes.
Paystack: Validate Bank Account
paystack_validate_account_number
Confirm that a bank account belongs to the person or business you think it does, by matching it against an identity document. This is the stronger check that South African payouts use, where Resolve Account Number is the lighter name lookup. It sends identity document numbers, which are sensitive personal data: pass them through and do not store them.
Paystack: Validate Customer
paystack_validate_customer
Verify a customer's identity against their bank records, which Nigeria requires before a dedicated virtual account can be issued. This sends government identity numbers and bank details to Paystack: handle them as sensitive personal data, pass them straight through, and do not store them in workflow variables, datatables or logs. Validation is asynchronous and its result arrives by webhook, not in this response.
Using the integration
The seventeen nodes that move real money, and what a retry does
This is the section to read twice. Seventeen nodes here debit a real card or bank account, or push funds out of your balance to a real person, and there is no recall endpoint on the Paystack API: Paystack: Charge Authorization, Paystack: Partial Debit, Paystack: Create Charge, Paystack: Submit PIN, Paystack: Submit OTP, Paystack: Initiate Bulk Charge, Paystack: Resume Bulk Charge Batch, Paystack: Create Subscription, Paystack: Enable Subscription, Paystack: Create Refund, Paystack: Retry Refund, Paystack: Resolve Dispute, Paystack: Initiate Transfer, Paystack: Initiate Bulk Transfer, Paystack: Finalize Transfer, Paystack: Direct Debit Activation Charge and Paystack: Trigger Activation Charge. All seventeen carry a money-moving flag, all seventeen are classed destructive, and each says on itself that the funds are real on a live key. Now the part that is easy to miss. There is no Idempotency-Key header anywhere on the Paystack API. Searching the whole published specification for idempotency returns exactly one hit, the reference field on a transfer, documented as a lowercase alphanumeric string of at least 16 characters with hyphens and underscores allowed. So transfers are safely retryable, but only when the retry sends the SAME reference, and a retry that mints a fresh one pays the person twice. Charges, partial debits, bulk charges and refunds are not safely retryable at all, because a transaction reference is a uniqueness constraint rather than a documented idempotency key: a duplicate is rejected instead of returning the original result. When a call times out and the outcome is unknown, resolve it by reading with Paystack: Verify Transaction, Paystack: Check Pending Charge or Paystack: Verify Transfer before retrying anything. This integration validates a transfer reference against Paystack's rule before the request leaves, and it deliberately does not generate one when the field is blank, because a generated reference is fresh on every retry and that turns one payout into two. A workflow that can fire twice, such as a form submission or an overlapping schedule, needs deduplication on your side.
Minor units, everywhere, in both directions
Paystack takes and returns every amount in the smallest unit of the currency. Its own wording is kobo for NGN, pesewas for GHS and cents for ZAR, and KES and USD are cents too. NGN 5,000.00 is 500000 and GHS 25.50 is 2550. Every amount field in this integration repeats the rule in its own help text rather than assuming you read it once, because the node config panel is the only place a workflow author will see it and this API has no confirmation step to catch a factor-of-100 slip. Three places deserve extra attention. Prices on products, pages and plans look like ordinary catalogue numbers and are not. The share field on a split means 20 percent on a percentage split and 20 kobo on a flat one, from the identical number, so the split type changes what the figure means. And responses are minor units too, including every measure this integration declares summable, so a total built from Paystack: List Transactions needs converting before a person reads it. The currencies Paystack's specification lists are GHS, KES, NGN, ZAR and USD, and the fields accept free text so a code Paystack adds later still works.
The envelope, where status is a boolean rather than the HTTP code
Every Paystack response carries a status field, a message and a data object, and status is a JSON boolean saying whether the operation succeeded. It is not the HTTP status code and the two disagree in both directions: an ordinary HTTP 200 can carry a false status with the real reason in the message. An integration that only checks the HTTP code reports a failed charge as a success and lets it propagate down a workflow. This one computes a node's success from both signals and marks the node failed when either says it failed, attaching Paystack's own message so you can read what actually happened. That is why a node here can show as failed on what looks like a clean 200, and it is deliberate. List responses add a meta object beside data with the total, the page size and the page count, or the next and previous cursors on the cursor-paged endpoints, and it is passed through untouched for a following step to use.
Paging, and why every list node looks the same here
Paystack's API paginates in five different shapes, which is not a detail you should have to carry. Most lists take perPage in camel case with page. Six take per_page with an underscore, and they include the two most important lists on the API, Paystack: List Transactions and Paystack: List Transfers. Sending the wrong spelling does not error: it is ignored, the endpoint falls back to its default page size, and a workflow that asked for 200 rows silently gets the default. Six endpoints offer opt-in cursor paging through a use-cursor flag with next and previous cursors, Paystack: List Terminals is cursor-only with no page parameter at all, and the mandate authorizations list takes a bare cursor with a page size and no page number at all. Every list node in this integration exposes the same four fields, per page, page, from date and to date, and each node translates them to that endpoint's real spelling on the wire, so you never have to know which camel a given endpoint speaks. Twelve lists have no paging parameters whatsoever and each of those nodes says so, because a missing page field otherwise reads as a defect. For a full sweep of a list that is still growing, such as transactions, turn cursor paging on and follow the cursor: an offset walk over a growing list skips and repeats rows.
Which identifier a field wants, and why a 404 is usually the wrong one
Paystack is inconsistent about identifiers, and the inconsistency is inside a single resource rather than between resources. Customer is the sharpest example: Paystack: Fetch Customer and Paystack: Update Customer take the CUS_ code, while the direct debit endpoints on the same customer take the numeric id. Paystack: Fetch Transfer takes the TRF_ code while Paystack: Verify Transfer takes your own reference, and they sit next to each other. The transaction list filters by a customer code while the transaction export filters by a numeric customer id, in the same product. Two things in this integration deal with it. Every path field says in its own help text exactly which identifier it wants and where that identifier comes from, and 142 fields across the catalog have pickers fed by the corresponding list node, so an id is usually chosen rather than pasted. And when a 404 does come back, the integration attaches a hint saying that a 404 on this API is very often the wrong KIND of identifier rather than a missing record, and pointing at the node's field help. It can also mean the record belongs to the other ledger, since test and live data are entirely separate.
Transfers, the one time password gate, and payout runs
A payout run is the workflow this integration is best at, and it has a sequence worth following. Paystack: Resolve Account Number checks an account number against the bank and returns the account holder's name, which is the last point at which a typo is visible to a human. Paystack: Create Transfer Recipient registers the destination and returns a recipient code, and every later transfer names only that code, so a wrong account number becomes invisible from that moment on. A duplicate account number returns the existing recipient rather than creating a second one. Paystack: Fetch Balance runs before anything leaves, because a batch larger than the balance fails partway through rather than being rejected up front. Then Paystack: Initiate Transfer pays, with a reference your workflow computes deterministically from the row and the period so a rerun is the same transfer rather than a second one. Where your integration requires a transfer one time password, the transfer is held at status otp until Paystack: Finalize Transfer releases it, and Paystack: Resend Transfer OTP sends a new code. Paystack: Initiate Bulk Transfer pays everyone in one request, but Paystack requires the one time password requirement to be disabled before that endpoint works at all. That is what Paystack: Disable Transfer OTP and Paystack: Finalize Disabling Transfer OTP do, and it is why they are classed destructive even though they move no money: with the gate off, anything holding the secret key can send funds with no second factor. Paystack: Enable Transfer OTP turns it back on and belongs at the end of the same workflow rather than on somebody's to-do list.
Reporting, reconciliation, and what sums and what does not
Seventeen of the reporting nodes declare how their data can be rolled up over time, so a scheduled refresh can extend a report rather than rebuilding it. The one worth understanding is Paystack: Balance Ledger, because it is the only place on this API where a flow and a gauge sit in the same row. Each entry carries a difference, the amount that moved, and a balance, the running total afterwards. Amounts sum across a window and balances do not: summing thirty daily closing balances gives a number thirty times too large, so the balance is declared as a last value rather than a total. The same distinction is why the entity lists deliberately declare no summable measures at all. A plan's amount and a page's amount are prices rather than revenue, a subscription's amount is contracted value rather than money received, a product's quantity sold is a lifetime total sitting on the product row, and an order total may never have been paid. For money that actually arrived, read transactions. Paystack: Transaction Totals answers a whole window in one call instead of paging the list, Paystack: List Settlements shows what Paystack paid into your own bank account and Paystack: Fetch Settlement Transactions breaks one settlement into the transactions behind it, and the three export nodes return a short-lived CSV link when the destination is a spreadsheet. One honest gap: the settlements list declares only page and page-size parameters in Paystack's specification, with no date range at all, so unlike transactions and transfers it cannot be windowed by date through the documented parameters. That node says so on itself and offers an extra-query escape hatch rather than pretending otherwise.
On the automation canvas
Paystack nodes chain with every other node in Mattering. A form submission can run Paystack: Create Payment Request and have a real invoice in front of a customer, created as a draft first when something needs checking, because the send-notification option emails a real person and a workflow that fires twice sends two invoices. A closed deal in Mattering Sales can create the customer and the subscription. A weekly schedule can build a payout run from a datatable, pause on a Mattering Productivity task for approval, and only then reach the transfer nodes. A daily sweep of Paystack: List Disputes filtered to awaiting merchant feedback can post the ones with a deadline into a Mattering Comms channel, which is a completely read-only way to get value here. Reconciliation figures can land in Mattering Analytics. The one structural thing to design around is that this integration has no trigger nodes, because Paystack's API has no webhook management endpoints at all: webhooks are a Paystack feature configured in the dashboard rather than something an integration can create. So either point your dashboard webhook URL at Mattering's generic webhook trigger and run the workflow from there, or run on a schedule and read. Either way, confirm a payment with Paystack: Verify Transaction before acting on it, checking that the status is success AND that the amount and currency match what you meant to charge, rather than trusting a browser redirect that can be replayed.
From AI assistants over MCP
Every node speaks MCP, the open protocol for connecting AI assistants to tools, so Claude, ChatGPT, and Matter, the assistant built into the platform, can drive the same 163 operations. Paystack also publishes an official MCP server of its own, the @paystack/mcp-server package on npm, maintained from Paystack addresses. It is a generic bridge over the same API description this integration was built from: two tools, one that looks up an operation and one that makes a request, marked public preview, and it validates at startup that the key is a test key and rejects live keys. It is a sensible way to explore the API from an assistant. The difference here is what a typed catalog gives an agent: 163 named nodes to choose between rather than a path string to compose, per-field help that says minor units and which identifier a path wants, pickers on 142 fields, money-moving and destructive flags a canvas can display, transfer reference validation, and the boolean-status reconciliation described above, which a generic passthrough cannot do because it does not know the vendor's envelope. Whichever you use, the split worth keeping is the same one: give an assistant the 73 read nodes, point it at a test key, and keep the seventeen that move money behind a condition or a human approval step.
Troubleshooting
Test Connection fails with a 401
A node fails with a 403 while other nodes work fine
The node reports a failure but the HTTP status was 200
A charge or a refund ran twice
A transfer was rejected and the error does not say why
Bulk transfer fails outright on an account where single transfers work
An amount came out one hundred times too large or too small
A list node ignored the page size, or a sweep skipped rows
A fetch returns 404 for a record you can see in the Paystack Dashboard
Requests start failing with a 429
A settlements report cannot be filtered by date
A picker on a node stays empty
Related
The Paystack MCP
What connecting Paystack unlocks for AI agents and automations, with common uses and FAQs.
More guides
All Automations documentation
Every integration guide, plus how connectors, credentials, and workflows fit together.
Paystack is a trademark of its respective owner. Mattering uses platform names to identify the services these integrations connect to; no endorsement or affiliation is implied.