Using a custom payment provider

Work in progress

This functionality is still under active development. We're excited to hear your feedback!

Connect by default uses Gigs Payments, which securely collects payments via credit card or wallet payment and sets up recurring payments.
Connect can also be configured to use a custom payment method, which allows you to integrate any way to confirm a purchase that a user made via Connect. This requires some additional implementation effort on your side to handle and confirm a user's checkout.

Prerequisites

Choosing this configuration will allow you to implement your own, custom payment strategy:

  • Ask the user for their payment method details only if necessary
  • Collect the payment from the user and mark it as paid under your conditions
  • Handle recurring payments

This means that you will need to write your own logic to handle payment collection and follow up processing, which requires an API key.
This also means that you have to guarantee that the user has a valid payment method on file or let them create one.

Connect uses the Billing API to integrate with you own payment processing. You can find more information about using the Billing API in the Billing API reference.

Differences to using Gigs Payments

Connect will guide the user through their checkout by collecting required information, optionally create a number porting, and shows a summary to the user to confirm their checkout. Once the user confirms the
purchase of their new phone plan, Connect will redirect the user to a custom URL that you can configure to handle payments.

With Gigs Payments, Connect will also ask a user for their credit card during the checkout, displays a successful payment confirmation to the user, and will handle potential payment failures to retry payments with a different credit card. Using a configuration without Gigs Payments, you will need to take care of these parts inside your own payment handling.

Limitations

While still under development, there are some Limitations in Connect without Gigs Payments. You can read more about those Limitations below.

Implementation

1. Connect redirects to your payment URL

When a user confirms their checkout, Connect will create an unpaid Invoice in status finalized, and a Subscription in status pending. Connect will then redirect the user to a URL that you can configure, together with the invoice_id as query parameter.

https://your-app.com/handle-payment?invoice_id=inv_1234567890

2. Mark the invoice as paid

To complete the purchase, use the Invoice ID to Pay the Invoice. Once you mark the invoice as paid, the subscription will start to activate, so the user can install and use their new SIM.

3. Continue after a successful payment

After the invoice was paid, you can either continue with the user on your own site, or you can Create a Connect Session to redirect the user back into Connect, for example with the intents to view the subscription, complete the porting or show our eSIM Installation Instructions.

Complete flow

sequenceDiagram actor User participant Connect participant Gigs API participant Customer activate Connect activate Gigs API activate Customer Customer ->> Connect: Create Connect Session Connect ->> User: Start checkout flow User ->> Connect: Finish checkout flow Connect ->> User: Show Plan price excl. Taxes User ->> Connect: Confirm subscription Connect ->> Gigs API: Create pending subscription Gigs API ->> Connect: Return Subscription Connect ->> Gigs API: Get Invoice Connect -->> User: Redirect to Customer deactivate Gigs API deactivate Connect Customer -->> User: Show due amount incl. Taxes from Invoice User ->> Customer: Confirm Payment Customer ->> Gigs API: Process Payment Customer ->> Gigs API: Mark Invoice as paid activate Gigs API Gigs API ->> Gigs API: Activate subscription Gigs API ->> Customer: Return active subscription deactivate Gigs API Customer -->> User: Redirect to Connect deactivate Customer activate Connect User ->> Connect: Go through installation process deactivate Connect

Authentication not provided

Please ensure that the user that is authenticated in your app is the same user that is associated with the subscription.

Use cases

Using Connect with your own payment processing works great for the following use cases:

  • You already have a payment processing solution in place and want to use it
  • You yourself are the payment processor
  • You want to allow your users to pay with alternative means of payments (i.e. credits, bonus points)
  • You want to offer free subscriptions to your users

Limitations

This part of Connect is under active development and at release time will not provide the same features as the default configuration using Gigs Payments. We are working to remove these limitations so that you can benefit from the same functionality as the standard Gigs Payments integration.

  • No Top-ups: Currently, we do not support top-ups in this flow
  • No auto-renewal reminders: Currently, Connect will not notify users about upcoming auto-renewals for you. You need to ensure that Invoices sent for renewals are paid by listening to the invoice.finalized event with a matching reason
  • No taxes displayed in Connect: Currently, taxes are not displayed in Connect. However, on your side you will have this information available on the invoice and can display the total amount due.
  • Only works with Connect Sessions: You can only use a Connect Checkout with your custom payment method by Creating a Connect Session with the checkoutNewSubscription intent. Connect cannot be used to browse or select a plan.
  • No voucher management in Connect: Currently, we do not support managing vouchers for custom payment methods in Connect.
  • Invoice format: A user can view their Invoices in Connect, but they can't download an Invoice as a PDF.

Early Access

We want to make custom payment methods available as early as possible to conduct feedback and improve the flow. If you are interested in using this flow and want to get early access, please reach out to you customer success manager.