Skip to content

Paystack Payment Processor

Overview

The Paystack task takes a payment through the account's Paystack connection. It has two actions:

  • Charge Account — charges the saved card (Paystack authorisation) on the client's billing account in BaseCloud.
  • Create Payment Link — starts a Paystack checkout for the amount and returns its link, to send to the client.

The amount is given in the currency's main unit (500.00) and converted to the smallest unit for Paystack.

Settings → App Connections & Keys with Select App Type open: a search field and a card for each app that can be connected, including Facebook Lead Ads, Facebook Marketing, Google Ads, Google Docs, Google Sheets, Microsoft Email, Paystack, Stripe, WhatsApp Business and Xero, each marked OAuth2 or API Key

Connections live in Settings → App Connections & Keys, not on the task. Connect the app once and every task that needs it can use it. The badge on each tile says how it authenticates — OAuth2 sends you to the provider to sign in, API Key expects a key you paste in.

Prerequisites

  • A Paystack connection in Settings → App Connections & Keys, with the account's secret key.
  • For Charge Account: the client must have an active billing account with a saved Paystack authorisation in BaseCloud. The default one is charged; without one the task fails.

Configuration

Builder fields

The Field column is the label as it appears in the task builder; Key is the name the value is stored under and referenced by.

Field Key Type Default Notes
Paystack Connection app_connection_id app-connection –
Action paystack_action select charge_account Options: Charge Account · Create Payment Link
Client ID o_client_id textarea – Only shown when paystack_action is charge_account
Email email textarea – Only shown when paystack_action is create_payment_link
Amount amount textarea –
Currency currency select ZAR Options: ZAR — South African Rand · USD — US Dollar · NGN — Nigerian Naira · GHS — Ghanaian Cedi · KES — Kenyan Shilling
Metadata metadata_rows dyn-rows – Only shown when paystack_action is charge_account

Charge Account

  • Client ID is the client's o_client_id — the client is looked up by it, and an unknown id fails the task.
  • Amount is read like any accounting amount: 250, $1,250.00 and 1 250,00 all work, and it's rounded to the cent. A blank, zero or unreadable amount stops the run before anything is charged.
  • The saved authorisation is charged at once, to the billing account's email. Metadata rows are sent with the charge; BaseCloud adds owner_id and client_id.
  • Check the result. Paystack answers "Charge attempted" even when the bank declines the card, so the task completes either way. Read data_status — only success means the money was taken — and branch on it with an If before confirming anything to the client.

Charging for an invoice

Put the invoice's number, without its INV, in a Metadata row named invoice_id (for example 1024, or {{task_<ID>_quote_invoice_o_id}} from an Accounting step), and map what it still owes to Amount: {{task_<ID>_quote_invoice_balance_due}}, not its total.

  • The charge is capped at what the invoice still owes. A larger Amount charges the balance, and charge_note says so. That way a client whose credit already paid part of the invoice isn't charged the whole total.
  • Nothing is charged when the invoice owes nothing (paid already, or void): charged is false, and run_text says "Nothing is owed on INV…, so the card was not charged."
  • When the payment comes through, BaseCloud records it on the invoice by itself, and workflows on Payment received and Marked as paid run. You don't need a Mark Quote / Invoice Paid step: see the tip under Mark Quote / Invoice Paid.

Without invoice_id, the amount is charged as given and no invoice is marked paid.

  • Email is required — it is the payer's email on the Paystack checkout.
  • The link is data_authorization_url; send it with an Email or SMS task.

Output Fields

Reference fields as {{task_<ID>_<field>}}. Paystack's own answer is passed through: status and message, and the transaction under data_….

Charge Account output

{
  "task_32001_run": true,
  "task_32001_run_text": "Transaction Successful",
  "task_32001_status": true,
  "task_32001_message": "Charge attempted",
  "task_32001_data_id": 123456789,
  "task_32001_data_domain": "live",
  "task_32001_data_status": "success",
  "task_32001_data_reference": "PAYSTACK-1707397234567-8901",
  "task_32001_data_amount": 50000,
  "task_32001_data_currency": "NGN",
  "task_32001_data_authorization_authorization_code": "AUTH_xxxxx",
  "task_32001_data_authorization_card_type": "visa",
  "task_32001_data_authorization_last4": "4081",
  "task_32001_data_authorization_bank": "TEST BANK",
  "task_32001_data_customer_email": "customer@example.com",
  "task_32001_charged": true,
  "task_32001_amount_charged": "500.00",
  "task_32001_charge_note": ""
}

charged is false and amount_charged is 0.00 when an invoice in the metadata owed nothing. charge_note says when the charge was lowered to what the invoice owed.

{
  "task_32001_run": true,
  "task_32001_run_text": "Authorization URL created",
  "task_32001_status": true,
  "task_32001_message": "Authorization URL created",
  "task_32001_data_authorization_url": "https://checkout.paystack.com/xxxxxxx",
  "task_32001_data_access_code": "xxxxxxx",
  "task_32001_data_reference": "PAYSTACK-1707397234567-8901"
}

Real-World Examples

Form Submission
  └─ Match to Client   look the client up
      └─ Paystack      generate a payment link
          └─ Email     send the link

Charge a saved payment method

Schedule  (monthly)
  └─ Paystack   charge the stored authorisation
      └─ If     data_status is "success"
          └─ SMS    confirm to the customer

Follow up when a payment arrives

Webhook In  (Paystack charge succeeded)
  └─ Match to Client     contact_email from the payload
      └─ Workflow Note   log it against the client

Troubleshooting

Message Cause and fix
No app connection ID provided. / Failed to fetch app connection. Pick a Paystack connection; reconnect it in Settings › App Connections & Keys if it was removed.
Paystack secret key not found in connection Reconnect Paystack with its secret key.
No currency selected. / Amount is not a number. Set the currency; map an amount more than zero.
Nothing is owed on INV…, so the card was not charged. Not an error: the invoice in the metadata was already paid or void.
No client selected. / the client is not found Map the client's o_client_id.
No active billing account found for this client. The client has no saved card — send a payment link instead.
The task completed but data_status is failed The bank declined the charge; Paystack's data_gateway_response says why.
Rate limited — rescheduled for retry. Nothing — the run is retried automatically.
  • Stripe — the same two actions through Stripe
  • Email — send a payment link or a confirmation
  • If Statement — branch on data_status
  • Workflow Note — log the payment against the client

FAQ

Can I refund a payment here? No — refund in the Paystack Dashboard. BaseCloud records the refund by itself, and the invoice owes the money again: see Refunds made in Stripe or Paystack.

Where do saved cards come from? A client saves their card by ticking Save this card for future payments when they pay an invoice online. The payment page itself never charges a saved card.

Can I test without real charges? Yes — connect Paystack with a test secret key (sk_test_…) and use Paystack's test cards.

Which currencies? ZAR, USD, NGN, GHS and KES, as the Currency setting offers — each only if your Paystack account accepts it.