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:

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, or cancelled based on the user’s interaction or the defined logic.

  • A Payment Method can be attached, authorized, or detached.

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.

  1. Customer Creation

    Start by creating a Customer object with their billing data.

  2. Attach a Payment Method

    Once tokenized and authorized, you can attach a method to the customer:

    POST /payment-methods/{payment_method_id}/attach

  3. Set Up a Payment Route

    This determines how the payment will be routed, especially important for businesses using custom payment providers.

    POST /payment-routes/

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

  5. 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?

Once you understand the basics, there’s no limit to what you can build with OpenPay.