API Tour
In this tour guide, you’ll learn how OpenPay’s API objects work together to make your payment integration strong and reliable.
OpenPay's APIs are designed to handle real-world payment issues seamlessly. This guide walks you through:
-
The core concepts driving the API
-
How payments works within OpenPay
-
Objects you'll work with and when to use them
With this API tour, you can get patterns down; you're not just following tutorials anymore. You can build stuff that grows with your business and doesn't fall apart when things get complicated.
Concepts of OpenPay’s API
Everything is an Object
Everything in OpenPay is object-based. Whether you're creating a customer or starting a subscription, you're interacting with different API objects:
-
Customer: for storing user details and billing info.
-
Payment Method: to store how users intend to pay.
-
Subscription: manages recurring billing cycles.
-
Payment Route: maps out how and where payments should be routed.
-
Payment Link: for creating quick one-off checkout URLs.
Even actions taken via the dashboard (like adding a customer) create backend objects.
Objects Have Lifecycles
OpenPay treats processes like payments or subscriptions as living things—they evolve through states.
For example:
-
A Subscription starts in a trialing state and moves to
active
,paused
, orcancelled
based on the user’s interaction or the defined logic. -
A Payment Method can be
attached
,authorized
, ordetached
.
This status-driven design gives you control over every step. Need to pause a subscription? You can call PUT /subscriptions/{subscription_id}/pause
.
Payment Orchestration With OpenPay
At the center of most OpenPay payment flows is the Payment Route and Payment Method pairing.
-
Customer Creation
Start by creating a
Customer
object with their billing data. -
Attach a Payment Method
Once tokenized and authorized, you can attach a method to the customer:
POST /payment-methods/{payment_method_id}/attach
-
Set Up a Payment Route
This determines how the payment will be routed, especially important for businesses using custom payment providers.
POST /payment-routes/
-
Initiate the Subscription or One-time Payment
With everything attached, begim the action:
- For subscriptions:
POST /subscriptions/
- For one-time payments: use a Payment Link
-
Track with Events
Every major activity such as payment success, failure, refund, is logged as an
Event
, which you can listen to via webhooks:GET /events/{event_id}
Testing Your Integration
When testing your integration, make sure to use OpenPay’s staging environment. All requests in test mode should be directed to the staging base URL: https://connto.openpaystaging.com/
. It allows you to test customer creation, subscriptions, and payments without going into production mode.
Wrapping Up
By now, you should understand how OpenPay’s API objects and flows work together to make payments seamless, scalable and reliable by providing endpoints to build fast, secure, and scalable payment experiences to your business.
With this API, you are not just calling endpoints, you’re also working with smart and state-aware objects like customers
, payment-methods
, subscriptions
, and payment-routes
.
Whether you're setting up a simple one-time checkout with a Payment Link or building a fully automated billing platform with retry logic and subscription lifecycles, the OpenPay API is designed to support you at every single stage.
Need help?
-
Explore the OpenPay API Reference for detailed endpoints and object schemas.
-
Try out real-world code examples to see OpenPay API in action.
-
Add webhooks to automate your response to key events.
Once you understand the basics, there’s no limit to what you can build with OpenPay.