Custom Payment Gateway

We offer automatic integration with a number of payment providers, such as PayPal and Stripe. Here you can find 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.

Note that this 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. 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 in your SuperSaaS dashboard under Payment Setup in the box “Message to show at the top of the shop page”. Here you enter the following code:
    $gateway{custom https://example.com/endpoint https://example.com/test_endpoint Button_text}

    • Endpoint URL

      The user’s browser gets forwarded to this URL. The POST request will include all data required to process the payment.

    • Test Endpoint 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 is the text that appears on the button during checkout. Spaces need to be replaced with underscores. If no text is provided it will show a localized version of the text “Pay now”.

    You may also want to add $gateway{$nopaypal} in that same field to ensure the default payment gateway is disabled.

  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 needed 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.

  4. Report the result

    Once the payment process has completed, your server can issue a call to /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 items available again.
    • refunded means the payment was fully refunded. SuperSaaS will deduct the credits, or cancel the appointment.

    Authentication:

    In order to make this call you will need to authenticate using your API-key. You can learn more about the available authentication methods on the Authentication Page.

    Fields:

    You can supply the required fields for this call either as query parameters or as 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 correctly 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, that needs to be echoed back when reporting the result
success_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 admin accounts
user_name(If applicable) Name of the user initiating the transaction. Not included for non-logged in users, or purchases by admin accounts
user_email(If applicable) Email address of the user initiating the transaction. Not included for non-logged in users, or purchases by admin accounts

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
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_idOnly if provided Unique ID of the user initiating the transaction. Required if provided in the initial POST request