Guides · Setup

How to connect Stripe or PlaceToPay to ModusBill

ModusBill takes card payments through a processor the firm connects itself: Stripe, or PlaceToPay for firms in the markets it serves. The money goes to the firm's own processor account, never through ModusBill. Connecting one takes about fifteen minutes and needs a firm administrator in ModusBill and an owner login at the processor. This guide covers both, from finding the credentials to going live.

Before you start

• You are an administrator of the firm in ModusBill. Payment providers are under Admin, Firm Settings, Payment Providers, at https://app.modusbill.com/FirmPaymentSettings.
• You can sign in to the processor's dashboard with a login allowed to see API keys.
• You have a test client and a small test invoice ready. Every setup should end with a real test payment.

Each provider has an Environment setting. Sandbox is for test credentials and charges nothing; Production is for live ones. Start in Sandbox.

Connecting Stripe

ModusBill needs two values from Stripe: a secret API key, and the signing secret of a webhook endpoint that tells ModusBill when an invoice has been paid.

1. Open the Stripe Dashboard and, for a first run, leave the Test mode toggle on.
2. Copy the secret key. Go to Developers, then API keys, and copy the Secret key. In test mode it starts with sk_test_; in live mode with sk_live_. Never share it and never paste it anywhere but the ModusBill settings field.
3. Create the webhook. Go to Developers, then Webhooks, and add an endpoint. The URL is your ModusBill application address followed by /api/paymentwebhook/stripe/confirm, which for the standard deployment is https://app.modusbill.com/api/paymentwebhook/stripe/confirm. Select the events checkout.session.completed and checkout.session.expired.
4. Copy the signing secret. Open the endpoint you just created and reveal its Signing secret, which starts with whsec_. ModusBill uses it to verify that each notification really came from Stripe and rejects anything else.
5. Enter both in ModusBill. In Payment Providers, choose Configure next to Stripe. Keep Environment on Sandbox, and in the settings box set secretKey to the secret key and webhookSecret to the signing secret. Leave currency as usd unless the firm bills in another currency. Check "Set as the firm's active provider" and save.
6. Test it. Open a test invoice, generate a payment link and open it. Pay with Stripe's test card number 4242 4242 4242 4242, any future expiry and any three-digit code. Within a few seconds the invoice in ModusBill should show the payment and change status.
7. Go live. Switch the Stripe Dashboard out of Test mode and repeat steps 2 to 4 to get the live key and a live webhook endpoint with its own signing secret. Edit the provider in ModusBill, replace both values, set Environment to Production and save. Test and live keys are separate pairs and never mix.

Optionally, check "Let clients pay part of an invoice" and set the smallest part payment you accept. The client then sees the full balance on the payment page and can lower it.

Connecting PlaceToPay

PlaceToPay, by Evertec, is a Web Checkout gateway used across Latin America and the Caribbean. ModusBill needs the two credentials PlaceToPay issues for a merchant site.

1. Get a merchant site. Your PlaceToPay account manager provisions a Web Checkout site and gives you, per environment, a login and a secret key (sometimes called the tranKey). Test credentials only work against PlaceToPay's test environment, and production credentials only against production.
2. Enter them in ModusBill. In Payment Providers, choose Configure next to PlaceToPay. Keep Environment on Sandbox for the test pair. In the settings box set merchantId to the login and apiKey to the secret key. Check "Set as the firm's active provider" and save.
3. Nothing to register in a dashboard. ModusBill sends PlaceToPay its notification address with every payment request, so no webhook has to be created by hand. If PlaceToPay asks you to whitelist a notification URL, it is your application address followed by /api/paymentwebhook/placetopay/confirm, which for the standard deployment is https://app.modusbill.com/api/paymentwebhook/placetopay/confirm.
4. Test it. Open a test invoice, generate a payment link and open it. Complete a payment with the test cards PlaceToPay documents for its sandbox. The invoice in ModusBill should show the payment when PlaceToPay confirms it.
5. Go live. Edit the provider, replace the credentials with the production pair, set Environment to Production and save. The client-facing checkout page is presented in Spanish.

What happens after a payment

The processor notifies ModusBill, which records the payment against the invoice, updates its status and marks the payment link as used. If a client abandons a Stripe checkout page, the link stays valid; only a completed payment retires it. Payments made by check, wire or in person are still recorded by hand from the invoice page, so the balance is right whichever way the money arrived.

Trust deposits are different

These two processors are for paying invoices from the firm's operating side. Card deposits into a trust account must settle in full, with the processing fee taken from operating rather than from the client's funds, which needs a trust-aware processor. Online trust deposit requests in ModusBill are being built on LawPay for that reason and are not yet available through Stripe or PlaceToPay. Until then, trust deposits are recorded from checks, wires and cash.

If something does not work

• Payment link cannot be generated: the provider is not active, or a required setting is blank. Open the provider and check both values were saved.
• Client paid but the invoice did not update: for Stripe, the webhook endpoint URL or signing secret is wrong, or the endpoint is missing the events. Stripe's Dashboard shows every delivery attempt and the response ModusBill returned.
• Sandbox credentials in Production, or the reverse: the processor refuses the request. Environment and credentials must be from the same pair.
• Anything else: write to support@modusbill.com with the invoice number and the time of the attempt.