Core concepts

Learning the core concepts can accelerate an integration by giving you the context you need to know where to look and map where things fit into your environment.

Start with a quick view of the resource relationships.

Then, spend some time reading the core resources. The core resources are the most popular resources utilized by our platform integration partners and merchants, like you.

Resource relationships

Here is a big picture overview of the core concepts.

Resource Relationship Resource
Customer 1 to many Payment Instruments
Customer 0 to many Transactions
Payment instrument 0 to many Transactions

Core resources


The Customers resource is at the very core of the most commonly integrated use cases.

A customer may be a person or an organization.

A customer's information may be augmented using custom fields.

A customer may be tracked to lead sources (object). Rebilly keeps track of the original lead source (the introducer), the intermediary lead sources (the influencers), and the most recent lead source (the closer).

Customers may also be tagged, and tags can be useful for various reporting and automation tasks.

A customer may not have any orders or transactions associated, and may therefore simply be a lead.

The customers collection can be filtered by recency, frequency and monetary value for traditional marketing segmentation.

An id is what makes a customer unique. Read more about how to prevent duplicate data and maintain data quality in our article about Preventing Duplicates.

A customer may have a default payment instrument. If it does, it will be used for autopay on subscription renewals, as well as transaction requests where a specific payment instrument is not provided.


The customer does not have its own status within Rebilly.

Rebilly does track the recency (most recent paid transaction), frequency (number of transactions), and total lifetime revenue for each customer.


The customer is often referenced from other resources because many things belong to one and only one customer.

The id within the Customers resource is referenced as the customerId within other resources.

"customerId": "<insert customer's id>"

Payment instruments

What is a payment instrument?

A payment instrument is like a payment card, bank account, PayPal account, or more. It's required for collecting payments electronically.

The payment instruments are not a singular resource, but rather used to refer to the concept, which is made up of specific resources like payment cards and bank accounts.


We recommend creating payment instruments using our FramePay library to help minimize PCI DSS compliance and automate the collection of risk metadata and lead source data.

A payment card has a lifecycle of being inactive or verification-needed. After the first approved transaction, it is marked as active. If it reaches the expiration date, it is marked as expired. At any time, it can be deactivated which effectively removes it from being used.


A customer may have a default payment instrument. Within other API resources, it is often referenced as a paymentInstrument object, like this:

    "method": "payment-card",
    "paymentInstrumentId": "<id generated by API>"
Note: not all payment instruments are suitable for recurring autopay transactions.

Store for future use

Payment instruments may require additional actions before they are used for payments, such as:

  • Post an authorize transaction with the selected payment instrument, particularly for payment cards. You may also need to void the authorizing transaction.
  • Perform strong customer authentication (SCA), particularly for 3DS authorization.

Each payment method and gateway has different setup requirements. To create a uniform setup:

  1. Configure GatewayAccount.setupInstruction , to contain the required action for specified payment method and payment gateway.
  2. Use a transaction with type= setup . This transaction performs the required actions on the specified payment instrument.



There are 8 transactions types:

  • authorize
  • capture
  • sale
  • void
  • refund
  • credit
  • 3ds-authentication
  • setup

An authorized transaction can be captured or voided.

A sale transaction can be refunded.

A refund transaction can be voided (sometimes).

A credit transaction is a special and rare type of transaction that allows payments to be made to customer cards in excess of just a refund. It requires special permissions from your acquiring bank.


The transaction may have one of these results:

  • approved
  • declined
  • abandoned
  • canceled
  • unknown

If the result is unknown, it will likely change as it is processed.

When the result is... You may want to
approved - Present the customer with a "Thank you" page.
- Display the billing descriptor on the "Thank you" page.
declined - Present the customer with a message stating that the transaction was declined.
- Ask your customer to retry the transaction with a different payment method.
- If you detect abuse, you may want to block the customer (Rebilly can automate that for you).
unknown - Check if the status is "waiting-approval". If it is, pop the customer to the approvalUrl found within the "_links" of the response.
canceled - This means the customer was offsite and intentionally canceled the transaction. Present the customer with an option to pick a different payment method.

Offsite vs. Instant

In many cases, there is no end user (customer) interaction involved to complete a transaction.

However, there are more and more circumstances, such as regulations, and payment methods that require the customer to interact directly on a third-party website. We call that the offsite experience.

Extending the core

Custom fields

Custom fields are a way to extend particular of Rebilly's core resources.

Perhaps you must know your customer's date of birth, or favorite song. It's easy to do using custom fields. You can create additional schema to extend our resources.

Then, you may include the data within your API requests and Rebilly will validate, store it, and return it when you retrieve the resources.

    "customFields": {
        "favoriteColor": "Rebilly Blue"

Email notifications

Rebilly can send emails when events happen.

Rebilly uses a liquid template engine to render the email replacing merge tags (placeholders) with actual values related to the event.

Webhook notifications

Read our article about webhooks


An event is emitted when certain objects have state changes that are important to business needs.

The events may be utilized in a few ways:

  • To share data with third-party systems using integrations maintained by Rebilly
  • To automate certain actions using Rebilly's Rules Engine
  • To send email notifications
  • To send webhook notifications

Preventing duplicates

There are different strategies to prevent creating duplicate customers.

Using the PUT request with an ID

If the customer has an identifier within your system prior to the request to create the customer in Rebilly, you may utilize your own identifier as long as it conforms to our basic requirements that it is a url-safe string of 50 characters or less.

In this case, we recommend you utilize a PUT request to create (or on duplicate ID update) the customer record.

Our tutorial uses this PUT technique.

Using GET + PUT or POST

If the customer does not have an identifier in your system, or your system doesn't maintain identifiers, then you may need to try to find if the customer exists first. The best way to do that is to do a GET request on the customers resource and filter by whatever should make that customer unique (such as their email address).

Email address is a popular such item for that, but for some businesses, other keys make more sense, such as name or phone number, or a combination of them.

To do this request, you need to understand how to generate a filter string.

GET customers?filter=primaryAddress.*

Here is an example to filter by name and email:

GET customers?filter=primaryAddress.*;firstName:Bob;lastName:Smith

If there is a matching customer in the response, then utilize that ID for the corresponding PUT request.

If there is not a matching customer, then create one using the POST request.

This technique requires 2 requests to implement the "insert on duplicate email update" type of behavior, where you can substitute email for any combination of values.

The preferred solution is the first option, of the PUT only requests.

Preventing Duplicate Transactions

To prevent a duplicate transaction, generate a unique ID that you pass to the client form. Include that id as the requestId property value with your transaction request.

Only regenerate a different id for the client form after you receive a declined result in the response from Rebilly.