Skip to main content

Integration via API

Getpaid provides a HTTP API built on REST principles, featuring predictable resource-oriented URLs, JSON-encoded request and response bodies, standard HTTP response codes, and robust API authentication.

To interact with the Getpaid API, you can use the HTTP REST endpoints. See the API reference for the full API specification.

Environments​

Getpaid provides two environments with different API base URLs:

tip

When testing your integration you should connect to the sandbox environment and specify the appropriate audience when obtaining an access token as described in the authentication section. See the testing section for more details about how to test your integration.

Resources​

Getpaid API is built following REST principles and is organized around resources. Understanding how resources and sub-resources work is helpful to integrating with our API.

A resource is an entity in the Getpaid solution that you can interact with via API endpoints. Each resource has:

  • A unique identifier id to unequivocally reference the resource. For example, acc_44678r08jtm8zbt227tzhc4nw5.
  • Properties that describe its state. It may include:
    • A reference field with your identifier to easily correlate the Getpaid resource with your solution entity.
    • A status field when it changes over time and, optionally to explain the status, a reason block.
    • A version field with a reference in the resource to a specific status snapshot when it is relevant.
  • Endpoints for CRUD (Create, Read, Update, Delete) and additional operations

Resources are accessed through URL paths that represent them hierarchically. For example:

  • /payments/{id}: a specific payment resource
  • /payments/{id}/refunds: refunds belonging to a payment

Sub-resources​

Sub-resources are resources that exist within the context of a parent resource. They represent a relationship between two entities. Sub-resources are always accessed through their parent's identifier.

Resources relationships​

Understanding these relationships helps you construct correct API calls and navigate the data model effectively.

  • Parent-child (sub-resources):
    • Accessed hierarchically through the parent's identifier
    • Sub-resource exists within the context of the parent
    • Example: refunds belong to a payment and they cannot be accessed independently
  • Sibling resources
    • Resources at the same level that reference each other implicitly or during the creation or operation of one of the resources linked
    • Both resources have independent endpoints but are logically connected
    • Example: accounts and checkouts are both top-level resources. A checkout has a reference to all the accounts involved in the funds flow in the checkout splits.
  • Resource chains
    • Resources can be created or derived from operations on other resources at the same level
    • The created resource offers independent endpoints and can be operated later using its own endpoints
    • Example: a payment is created as part of a checkout payment attempt. A checkout references all the payment attempts but they are at the same hierarchical level. You can later operate on the payment using its own endpoints.