This guide helps you integrate Lago with a custom payment provider. Build your own integration by following the steps below.
BaseService
call
CheckoutComSubscription
in app/models/payment_provider_subscriptions/checkout_com_subscription.rb
.
A few notes about providers:
settings_accessors
instead of adding database columns;secret_accessors
to securely store sensitive data (e.g., API keys); andorganization_id
and the provider code
:
PaymentProviders::Stripe::RegisterWebhookService
for more details.
To process webhook messages:
app/controllers/webhooks_controller.rb
;IncomingWebhook
and dispatch a job to process it; andHandleEvent
job arguments, so your services can be simpler.
File | Purpose |
---|---|
app/models/payment_provider_customers/checkout_com_customer.rb | Define Checkout.com-specific customer model (inherits from BaseCustomer). |
app/models/payment_providers/checkout_com_provider.rb | Define Checkout.com provider model (inherits from BaseProvider). |
app/models/customer.rb | Add PAYMENT_PROVIDERS enum value + has_one relation to Checkout.com customer. |
app/models/organization.rb | Add has_many relation. |
app/serializers/v1/customer_serializer.rb | Map Checkout.com customer settings for API responses. |
File | Purpose |
---|---|
app/graphql/types/payment_providers/checkout_com_input.rb | Define GraphQL input type for Checkout.com settings. |
app/graphql/types/payment_providers/checkout_com.rb | Define GraphQL object type for Checkout.com provider. |
app/graphql/mutations/payment_providers/checkout_com/base.rb | Abstract base mutation class for Checkout.com (inherit common logic). |
app/graphql/mutations/payment_providers/checkout_com/create.rb | Mutation to create a Checkout.com provider instance. |
app/graphql/mutations/payment_providers/checkout_com/update.rb | Mutation to update a Checkout.com provider instance. |
app/graphql/resolvers/payment_providers_resolver.rb | Add provider_type . |
app/graphql/types/customers/object.rb | Add provider_customer . |
app/graphql/types/mutation_type.rb | Define mutations. |
app/graphql/types/payment_providers/object.rb | Define resolve_type . |
File | Purpose |
---|---|
app/services/payment_providers/checkout_com_service.rb | Entry service for handling Checkout.com logic. |
app/services/payment_providers/checkout_com/base_service.rb | Shared methods for Checkout.com-related services. |
File | Purpose |
---|---|
app/services/payment_provider_customers/checkout_com_service.rb | Handle customer-related logic (create, sync). |
app/jobs/payment_provider_customers/checkout_com_create_job.rb | Background job to create a customer in Checkout.com. |
app/services/payment_providers/checkout_com/customers/create_service.rb | Actual service to create customers. |
app/services/payment_providers/create_customer_factory.rb | Add service mapping. |
app/services/payment_provider_customers/factory.rb | Add service mapping. |
File | Purpose |
---|---|
Edit app/services/payment_providers/create_payment_factory.rb | Add service mapping. |
File | Purpose |
---|---|
app/jobs/invoices/payments/checkout_com_create_job.rb | Background job to process invoice payments via Checkout.com. |
app/services/invoices/payments/checkout_com_service.rb | Service handling payment flow at invoice level. |
app/services/payment_providers/checkout_com/payments/create_service.rb | Create actual payment via Checkout.com. |
app/services/invoices/payments/payment_providers/factory.rb | Add service mapping. |
File | Purpose |
---|---|
app/jobs/payment_requests/payments/checkout_com_create_job.rb | Handle ad-hoc payment requests. |
app/services/payment_requests/payments/checkout_com_service.rb | Handle service logic for payment requests. |
app/services/payment_requests/payments/payment_providers/factory.rb | Add service mapping. |
File | Purpose |
---|---|
app/jobs/payment_provider_customers/checkout_com_checkout_url_job.rb | Generate hosted checkout URL for payments. |
File | Purpose |
---|---|
app/controllers/webhooks_controller.rb | Add a new action for Checkout.com webhooks. |
config/routes.rb | Add route for /webhooks/checkout_com . |
app/services/payment_providers/checkout_com/handle_incoming_webhook_service.rb | Handle incoming webhook events from Checkout.com. |
app/services/payment_providers/checkout_com/validate_incoming_webhook_service.rb | Validate webhook payloads and signatures. |
app/jobs/payment_providers/checkout_com/handle_event_job.rb | Async processing of webhook events. |
app/services/inbound_webhooks/process_service.rb | Add service mapping. |
app/services/inbound_webhooks/validate_payload_service.rb | Add service mapping. |
/specs/*.rb
codegen
script to get the new graph.
src/pages/settings/Integrations.tsx
Then, new routes and components need to be created for the PSP connection lists, details, edition and deletion.
To start, have a look at these files in the app:
PaymentProvidersAccordion
component. It needs to be updated to handle the selection of this new PSP option.
src/components/PaymentProviderChip.tsx
(displays the PSP chip in multiple places)src/pages/PaymentDetails.tsx
(if you wish to have clickable payment url links)