Back to index
Developer documentation

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.

Integrating a custom payment gateway requires considerable technical proficiency. Setting up your own payment backend is outside the scope of this document.

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:

    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

FieldComment
descriptionDescription of the product
transaction_idUnique ID of the transaction
amountAmount of the transaction in the lowest denomination of the currency. (For USD and EUR this is cents, for JPY this is yen)
currency_codeThree-letter code of the currency of the transaction. (for example: USD, EUR or JPY)
transaction_checksumIncluded as security measure, it needs to be echoed back when reporting the result
return_urlIf you want to send the user back after a successful transaction, you can forward the browser to here
cancel_urlIf you want to send the user back after a failed transaction, you can forward the browser to here
user_id(If applicable) Unique ID of the user initiating the transaction. Not included for non-logged in users, or purchases by the admin
user_name(If applicable) Name of the user initiating the transaction. Not included for non-logged in users, or purchases by the admin
user_email(If applicable) Email address of the user initiating the transaction. Not included for non-logged in users, or purchases by the admin
quantityIn case the quantity is different from one (e.g. a repeating appointment). The amount contains the total for all appointments
credit_consumed(If applicable) How much credit was used in this purchase. The transaction amount is net of credit, so the total price would be: amount + credit_consumed

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

The following fields need to be included in the call to https://www.supersaas.com/api/ipn. Several of the fields are simply a copy of the fields received via the initial POST request, they need to be sent back for verification purposes.
FieldComment
statusPayment status of the transaction: completed/canceled/refunded/pending
transaction_idUnique ID of the transaction
amountAmount of the transaction in the lowest denomination of the currency
currency_codeThree-letter code of the currency of the transaction. (for example: USD, EUR or JPY)
transaction_checksumIncluded so we can verify the request has not been modified during the checkout flow
api_keyYour API key, unless you are using Basic Auth to authenticate the request
user_id(Only if provided) Unique ID of the user initiating the transaction. Required if provided in the initial POST request