Payment gateways

A payment gateway lets customers pay an invoice online. Tidemark ships with two, Stripe and PayPal, both as plugins. This article covers how gateways are switched on, then the setup steps for each.

How gateways work#

1. Open Plugins and enable the gateway plugin (Stripe or PayPal). Only administrators can do this.
2. Open Settings → Payments. Each enabled gateway has its own block.
3. Fill in its credentials, switch it on and press Save payment settings.
4. Copy the Webhook URL to add in the provider (shown in the block, with a Copy button) into the provider's dashboard.

If no gateway plugin is enabled, the tab says No payment gateways installed and links to Plugins.

Each block has these controls:

A gateway is offered on an invoice only if it supports that invoice's currency. If no gateway is available, you can still record a bank transfer or other payment by hand on the invoice, and print bank details on unpaid invoice PDFs with Settings → Billing → Payment instructions.

Both plugins talk to the provider's API directly, so your server needs to reach the internet over HTTPS, and the provider needs to reach your webhook URL, so the site must be on a public address.

Stripe#

The Stripe plugin sends customers to Stripe Checkout, a page hosted by Stripe, to pay an invoice. Tidemark records the payment when the customer comes back, and again when the webhook arrives. A payment is matched by its Stripe reference, so it is only counted once.

Set up#

1. Enable the plugin under Plugins, then open Settings → Payments.

2. Paste your Secret key (in Stripe, under Developers → API keys). It starts with sk_live_ or sk_test_. Use a test key while you are trying things out.

3. In Stripe, add a webhook endpoint that points to the Webhook URL shown in the block. It looks like this:

   https://billing.example.com/webhooks/gateways/stripe
   

4. Subscribe the endpoint to these events:

   • checkout.session.completed
   • checkout.session.async_payment_succeeded
   • charge.refunded
   • for saved cards and automatic payments: payment_intent.succeeded, payment_method.detached, payment_method.updated, payment_method.automatically_updated and setup_intent.setup_failed

5. Paste the endpoint's Webhook signing secret (it starts with whsec_).

6. Optionally set a Statement descriptor suffix (up to 22 characters, shown on card statements).

7. Switch Accept payments with Stripe on and save.

Webhooks that fail signature verification, or arrive more than five minutes after they were signed, are rejected.

What it supports#

• Paying an invoice by card or wallet through Stripe Checkout, for the invoice's remaining balance.
• Refunds from Tidemark, sent to Stripe against the original payment. Refunds made in the Stripe dashboard are recorded in Tidemark when the charge.refunded event arrives.
• Saved cards: customers save a card under Payment methods in the client area (Stripe creates one customer record per client). Saved cards can be charged automatically by the schedule in Settings → Billing → Automatic payments. If the card issuer asks for authentication, the customer is emailed to pay manually.

For testing, use a test secret key and Stripe's published test card 4242 4242 4242 4242.

PayPal#

The PayPal plugin sends customers to PayPal to approve the payment, then captures it when they return to your site.

Set up#

1. Enable the plugin under Plugins, then open Settings → Payments.

2. In the PayPal developer dashboard, create a REST app. Choose Sandbox or Live in the Mode field. The default is Sandbox (testing).

3. Paste the app's Client ID and Client secret.

4. In PayPal, add a webhook for the app that points to the Webhook URL shown in the block:

   https://billing.example.com/webhooks/gateways/paypal
   

5. Subscribe it to PAYMENT.CAPTURE.COMPLETED and PAYMENT.CAPTURE.REFUNDED. For saved PayPal accounts, also subscribe to VAULT.PAYMENT-TOKEN.DELETED.

6. Paste the webhook's Webhook ID.

7. Switch Accept payments with PayPal on and save. When you are ready to take real payments, set Mode to Live and replace the credentials with the live ones.

Tidemark checks each incoming webhook by asking PayPal to verify its signature against your Webhook ID, and rejects it if that fails.

What it supports#

• Paying an invoice through PayPal, in the currencies PayPal supports: AUD, BRL, CAD, CNY, CZK, DKK, EUR, HKD, HUF, ILS, JPY, MYR, MXN, TWD, NZD, NOK, PHP, PLN, GBP, SGD, SEK, CHF, THB and USD. Invoices in any other currency do not offer PayPal.
• Refunds from Tidemark, and refunds made in PayPal are recorded when PAYMENT.CAPTURE.REFUNDED arrives.
• Saved PayPal accounts (wallet only) for automatic payments. Your PayPal app must have the feature for saving payment methods (the Vault) enabled. Saving cards through PayPal is not offered.
• The PayPal fee, when PayPal reports one, is stored on the payment.

Other ways to get paid#

Any invoice can have a payment recorded by hand, so you do not need a gateway to take bank transfers. See Payments and refunds. Other gateways can be added as plugins; see Plugins.

Related#

• Payments and refunds
• Recurring billing
• Taxes and currencies
• Plugins