Imagine API

Find comprehensive guides and documentation to help you start working with Imagine's API as quickly as possible. Let's jump right in!

Getting Started

This guide helps outline the basic concepts and mechanisms you will use when integrating with Imagine. You can follow along by using our interactive documentation, or you can use the outlined curl calls in this guide.

This guide can be followed by using your merchant sandbox account. Quickly sign up and receive your dev credentials to begin using the merchant API.

There are two basic flows this guide will cover:

  • Using Your Sandbox's Pre-Existing Customers

    1. charge a customer
    2. refund a customer
    3. view your balance
    4. view your balance transactions
  • Create a New Customer Using OAuth2.0

    1. create a new customer by using OAuth2.0 flow

Using Your Sandbox's Pre-Existing Customers

📘

Guide Variables & Hints

To follow along, whenever you see $SOME_TOKEN in a curl request, replace it with the appropriate value.

Each call has the pprint=true query parameter, which will automatically format the output of the JSON response.

When your merchant sandbox was created, it was populated with some pre-existing customers.

List Customers

You may list all your customers with a simple query

curl -H "Authorization: Token $SBOX_TOKEN" "https://api.sandbox.gotimagine.com/merchant/v1/customers?pprint=true"
{
  "customers": [
    {
      "id": "aa57c91e-db22-4d6c-813b-d815540937ba",
      "created_time": "2020-08-20T04:21:59.676841Z",
      "total_charged": {},
      "total_refunded": {},
      "can_charge": true
    },
    {
      "id": "09eb551d-3b2e-4d71-adce-bf38c62dde90",
      "created_time": "2020-08-20T04:21:59.668610Z",
      "total_charged": {},
      "total_refunded": {},
      "can_charge": true
    },
    {
      "id": "f55033eb-3e86-4a97-91d7-0a007c2cae95",
      "created_time": "2020-08-20T04:21:59.659639Z",
      "total_charged": {},
      "total_refunded": {},
      "can_charge": true
    },
    {
      "id": "bfcb8213-1135-4b23-985f-cc412ddff92b",
      "created_time": "2020-08-20T04:21:59.650313Z",
      "total_charged": {},
      "total_refunded": {},
      "can_charge": true
    },
    {
      "id": "2f52fe87-c7ea-43dd-a4ff-1b6d15e43e1e",
      "created_time": "2020-08-20T04:21:59.640795Z",
      "total_charged": {},
      "total_refunded": {},
      "can_charge": true
    }
  ]
}

These customers are generic, and represent a standard Imagine customer object that you can charge, refund, and otherwise manipulate. Each customer has already authorized your sandbox account to charge them. This is indicated by can_charge: true.

If you implement Imagine's payment button to collect payments from customers that are not logged in or otherwise associated with your site, these customers would not be chargeable. Instead, they have pushed funds into your account, and you may view them, but not charge them until they authorize you to do so using our OAuth2.0 flow.

Charge Customer

You may easily charge a customer by invoking our create charge API

📘

uuidgen

uuidgen is a standard program included in most *nix distributions as well as MacOS. It generates a random UUID V4.

It is included in the below curl requests to help you generate random charge and refund ids.

curl -H "Authorization: Token $SBOX_TOKEN" "https://api.sandbox.gotimagine.com/merchant/v1/charges?pprint=true" --data '
{
    "charge_id": "'$(uuidgen)'",
    "customer_id": "$YOUR_CUSTOMER_ID",
    "amount": {
        "currency_code": "USD",
        "units": 1729
    },
    "description": "A test charge in our sandbox account",
  "metadata": {
    "assoc_key":"12345abcde"
  }
}'
< HTTP/2 201 
< content-type: application/json
< content-length: 52
< server: Imagine Financial API v1
< x-if-trace-id: 965666985660028232

{"charge_id":"436ff2ac-c5d9-4b84-ba13-aa4edabd32c7"}

The response after creating a charge is the exact charge_id you provided when creating the charge. Notice that the returned HTTP Code is 201, indicating that the resource was successfully created. If you were to make the exact same call again, you would receive a different response:

< HTTP/2 200
< content-type: application/json
< content-length: 52
< server: Imagine Financial API v1
< x-if-trace-id: 965666985660028232

{"charge_id":"436ff2ac-c5d9-4b84-ba13-aa4edabd32c7"}

Notice that you now receive an HTTP Code 200. This is an example of an immutable resource. In general, all critical financial resources at Imagine are immutable. This means, you cannot accidentally create the same resource more than once. Since you define the charge_id, you an make this request as many times as you'd like without fearing that multiple charge resources will be created.

📘

Metadata: assoc_key

Metadata may be attached to supported resources. This allows you to attach arbitrary values to your request. Some metadata fields may be searched, sorted, and filtered. One example is the assoc_key value. This represents an association key, which allows you to specify your own id for this resource. If you would like to search for charges based on this key, you may do so.

If you were to provide the same request again, but you were to alter the body of the charge resource, you would receive an error. For example, if you altered the amount above, you would receive the following response:

< HTTP/2 409
< content-type: application/json
< content-length: 52
< server: Imagine Financial API v1
< x-if-trace-id: 965666985660028232

{
  "errors": [
    {
      "code": {
        "type": "INVALID_REQUEST",
        "description": "The client provided an invalid request and may retry after examining and fixing the request",
        "doc": "https://docs.gotimagine.com/docs/errors#invalid-request"
      },
      "sub_code": {
        "type": "PARAMETER_INVALID_VALUE",
        "description": "The request contains an invalid parameter. The parameter in question is provided in detail.parameter",
        "doc": "https://docs.gotimagine.com/docs/errors#parameter-invalid-value"
      },
      "detail": {
        "message": "The provided id references a resource which already exists but the provided body does not match the existing resource. If you intended to create a new resource, provide a new id",
        "parameter": "charge_id"
      }
    }
  ]
}

The error is self-explanatory, but see here for more details on Imagine error messages.

❗️

Mutable References

Immutability is a nice property, and it allows you to use the Imagine API safely, without the fear of accidentally double-charging or otherwise manipulating resources in unintended ways. However, it can get in the way sometimes.

Some properties of immutable objects are allowed to be mutated. They are properties which are not critical to the underlying nature of the resource. These objects are explicitly labeled mutable in our API.

For example, the charge resource has a mutable property called metadata. This allows you to attach arbitrary data to any charge. This may be mutated by calling an explicit mutation endpoint.

Some read-only properties are also mutable for your benefit. For instance, if a non-chargeable customer becomes chargeable, then the charge resource will update accordingly. These properties are also accordingly labeled mutable.

View Your Balance

You can view your balance at any time by calling the balances endpoint

curl -vH "Authorization: Token $SBOX_TOKEN" "https://api.sandbox.gotimagine.com/merchant/v1/balances?pprint=true"
{
    "available": [{
        "amount": {
            "currency_code": "USD",
            "units": 87539319
        },
        "last_modified_time": "2020-08-20T01:03:19.193251Z"
    }],
    "pending": [{
        "amount": {
            "currency_code": "USD",
            "units": 1729
        },
        "last_modified_time": "2020-08-20T05:00:12.436174Z"
    }]
}

Your balance has a pending amount, which indicates funds that are not yet available to be settled. It also has an available amount, which indicates the funds are available and will be settled automatically, unless otherwise specified.

Refund Your Customer

You can easily refund a customer as many times as you would like. However you must refund a specific charge, and you may not refund an amount greater than the difference of the original charge amount and the sum of all previous refunds made against that charge.

curl -v -H "Authorization: Token $SBOX_TOKEN" https://api.sandbox.gotimagine.com/merchant/v1/refunds --data '
{
    "refund_id": "'$(uuidgen)'",
    "charge_id": "$YOUR_CHARGE_ID",
    "amount": {
        "currency_code": "USD",
        "units": 1729
    }
}'
< HTTP/2 201 
< content-type: application/json
< content-length: 52
< server: Imagine Financial API v1
< x-if-trace-id: 7308818088934783242

{"refund_id":"5153c753-a8ed-4320-8c0c-55b2773ab17b"}

Notice, that refund is also an immutable resource, and the same rules apply as described above with the charge resource.

Balance Transactions

If you were following along, we created a charge for $17.29 USD While your pending balance may now be zero, you still have a series of balance transactions, which shows the entire history of funds currently in your Imagine account.

curl -H "Authorization: Token $SBOX_TOKEN" "https://api.sandbox.gotimagine.com/merchant/v1/balance-transactions?pprint=true"
{
    "balance_transactions": [{
            "id": "fb19b13f-0da0-48c7-a573-23e95021eb72",
            "source_id": "5153c753-a8ed-4320-8c0c-55b2773ab17b",
            "source_type": "refund",
            "amount": {
                "currency_code": "USD",
                "units": 1729
            },
            "created_time": "2020-08-20T05:08:56.746908Z"
        },
        {
            "id": "b570c250-1c07-4450-a120-d44840faa72b",
            "source_id": "c149bbac-baf1-42da-890a-4a053e615a92",
            "source_type": "charge",
            "description": "A test charge in our sandbox account",
            "amount": {
                "currency_code": "USD",
                "units": 1729
            },
            "created_time": "2020-08-20T05:00:12.436174Z"
        },
        ...
    ]
}

Create a New Customer Using OAuth2.0

A quickstart example is coming soon. Please see OAuth2.0 flow for immediate integration.

Updated 22 days ago

Getting Started


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.