Custom Payment Gateway

We offer automatic integration with a number of payment providers, such as PayPal and Stripe, see the complete list of payment providers. If you need to integrate with a provider not on that list, or if you want to use your own payment backend, then it’s possible to replace the checkout process with your own. This page documents how you can change the checkout flow to use your own payment backend.

High level overview

1. Set up the gateway. You configure a URL in SuperSaaS where users will be forwarded to during checkout
2. Handle the checkout. During checkout the user is forwarded to that URL with a POST request that includes the data needed for your backend to process the payment
3. Process the payment. You complete the checkout flow on your end and optionally send the user back to SuperSaaS
4. Report the result. Once the transaction completes you report back the status of the payment to SuperSaaS via a server to server call to an IPN (Instant Payment Notification) endpoint

If the user abandons the payment flow then any appointments that are not confirmed by your gateway will be automatically moved to the trash after 15 minutes. They are kept there for a month, so if payment takes a long time to complete and has been moved to the trash then it will be reinstated automatically. (In that case there is a small chance of a scheduling conflict, the administrator will receive an email notification if that happens.)

Detailed Setup

1. Set up the gateway

   You can set up the custom payment gateway on the Payment Setup page in your SuperSaaS dashboard.

   • Live URL: The user’s browser gets forwarded to this URL. The POST request will include all data required to process the payment.
   • Test URL (optional): If test mode is enabled this URL will be called instead. You could simply provide the same URL here, and add a query parameter like ?test_mode=true to indicate the difference.
   • Button text (optional): This text will appear on the payment button during checkout. If no text is provided it will show a localized version of the text “Pay now” (or “Buy now” for credit purchases).

   You may also want to ensure the default payment gateway to PayPal is disabled on that page.

2. Handle the checkout

   During the checkout process the user is forwarded to the URL you provided in the previous step. The POST request will contain all the fields necessary for you to process the payment. You can find a complete list of the fields below.

3. Process the payment

   After handling the transaction you can optionally send the user back to our site. We provide a return_url and a cancel_url where you can send your users depending on whether the payment succeeded. You could also show your own success or failure page, and optionally send the user back to the schedule page from there.

4. Report the result

   Once the payment process has completed, your server can issue a call to https://www.supersaas.com/api/ipn to update the payment status in SuperSaaS. You can also call this endpoint if the payment process has been cancelled or if a previously made purchase is refunded. The status field of the call has to be set accordingly:

   • completed means the payment has successfully completed.
   • canceled means the payment was canceled or has failed. SuperSaaS will make temporarily reserved space available again.
   • refunded means the payment was fully refunded. SuperSaaS will deduct the credits, or cancel the appointment.
   • pending means you need more than 15 minutes to process the payment. Temporarily reserved space will stay occupied until you call this end point again. As administrator, you can also go to the schedule and manually resolve the payment to “completed” or “cancelled”.

   Authentication:

   In order for the request to succeed you will need to authenticate using your API-key. You can learn more about the available authentication methods on the Authentication information page.

   Fields:

   You can supply the required fields for this call either as query parameters or as a JSON body. This call requires you to return some of the fields that are included in the initial POST request. This is for verification purposes on our end.

   Response:

   A properly formed request to this endpoint will always respond with HTTP status code 200. This way you can verify that the request was successfully received. Incorrectly formed requests will respond with the HTTP status code 400, while other errors will respond with status code 200 and carry an error code and message in the response body. By calling /api/ipn.json or /api/ipn.xml, you can get a JSON or XML response respectively.

   Example request:

   Query parameters JSON

   POST /api/ipn?transaction_id=b-12335b-67890&status=completed&amount=2000&currency_code=EUR&transaction_checksum=a1b2bsaf324j32432j4231h4b23&user_id=12345&api_key=YOUR_API_KEY

   POST /api/ipn.json
   Content-Type: 'application/json'
   body: '{
     "transaction_id": "b-12335b-6789",
     "status": "completed",
     "amount": 2000,
     "currency_code": "EUR",
     "transaction_checksum": "a1b2bsaf324j32432j4231h4b23",
     "user_id": "12345",
     "api_key": "YOUR_API_KEY"
   }

Parameter Reference

POST request that sends the user’s browser to your site

POST request that your backend sends to SuperSaaS with the transaction result