Canopy API documentation

Get summary details for a specific product.

For analytic purposes, retrieve commonly needed summary statistics computed for a specific product.

URL parameters

product_id Required / string(uuid)

Product ID
effective_as_of_date string(date-time)

The Date-Time you would like the system to return the data as of. IE tell me what the product summary information was on 2020-10-20 00:00:00 EST. If empty it defaults to current time.

Responses

• 200 object

Response for a request for summary data for a specific product.
Show response Hide response
- total_account_count number
  
  Total number of accounts under the product.
- total_credit_issued number
  
  Total amount (in cents) of credit issued to accounts under the product.
- utilization number
  
  The percent utilization rate of the product. (i.e. 30 means 30% utilization).
- product_id string(uuid)
  
  The Canopy-generated ID for the product.
- effective_as_of_date string(date-time)
  
  The Date-Time you would like the system to return the data as of. IE tell me what the product information was as if I had asked on 2020-10-20 00:00:00 EST. If empty it defaults to current time.
• 404

Account not found

Definition

GET https://sandbox.canopyservicing.com/products/{product_id}/summaries

cURL example

curl \
 -X GET https://sandbox.canopyservicing.com/products/{product_id}/summaries \
 -H "Content-Type: application/json"

Response example (200)

{
  "total_account_count": "10005",
  "total_credit_issued": "25500000",
  "utilization": "30",
  "product_id": "ca3cf4e9-5048-4461-a763-8f67b46dfd4d",
  "effective_as_of_date": "2017-06-20T09:12:14Z"
}

Response example (404)

No content

Get all available Accounts

Get details for all accounts linked to any of your products. Results are sorted by the date the account was created.

URL parameters

offset number

The zero-indexed starting point for paginated account requests sorted by account created date.
limit number

The maximum number of accounts to be returned. Defaults to 100.

Responses

• 200 object

Array of Accounts
Show response Hide response
- accounts array[object]
  
  An array of information for all accounts within the requested range.
  Show child attributes Hide child attributes
  
  accounts.account_id string(uuid)
  
  This is generated by Canopy. A unique ID for the account.
  
  accounts.account_status string
  
  The Status of the Account. Active upon account creation.
  
  accounts.account_status_subtype string
  
  The subtype of the Status of the Account. Null upon account creation.
  
  accounts.effective_at string(date-time)
  
  The Date-Time that this account became/becomes active.
  
  accounts.created_at string(date-time)
  
  The Date-Time which the account was created in the API.
  
  accounts.product_id string(uuid)
  
  The Product ID of the account.
  
  accounts.external_account_ids array[object]
  
  An Array of External Account IDs. These should be used to connect accounts created in Canopy to Users in your system and any connected external systems.
  
  Show child attributes Hide child attributes
  
  accounts.external_account_ids.name string
  
  Name of the External Party
  
  accounts.external_account_ids.id string
  
  External Account ID
  
  accounts.credit_limit_cents integer
  
  Total Amount (in cents) that this account can borrow.
  
  accounts.rate number
  
  The percentage interest applied to the account (i.e. 6.2 means 6.2%)
- total_account_count number
  
  Total number of accounts
• 404

No accounts found

Definition

GET https://sandbox.canopyservicing.com/accounts

cURL example

curl \
 -X GET https://sandbox.canopyservicing.com/accounts \
 -H "Content-Type: application/json"

Response example (200)

{
  "accounts": [
    {
      "account_id": "5fb3a288-5f6c-440f-b079-b06c828b7768",
      "account_status": "suspended",
      "account_status_subtype": "suspended-bankruptcy",
      "effective_at": "2018-03-20T09:12:28Z",
      "created_at": "2017-06-20T09:12:14Z",
      "product_id": "d119341c-47fd-4a55-bce7-28406dacfa20",
      "external_account_ids": [
        {
          "name": "Umbrella Corporation",
          "id": "22445702-a389-431f-927d-07b8d0750787"
        }
      ],
      "credit_limit_cents": "400000",
      "rate": "6.2"
    }
  ],
  "total_account_count": 42.0
}

Response example (404)

No content

Create a new customer account

An account should be created for each end user of each of your products. Once created, you will be able to add line_items to the account.

Body

product_id Required / string(uuid)

the Product ID of the account
external_ids array[object]

An array of static references to ID fields in a third party system.
Show child attributes Hide child attributes
- external_ids.name string
  
  Name of the External Party
- external_ids.id string
  
  External Account ID
credit_limit_cents integer

Total Amount (in cents) that this account can borrow.
rate number

The percentage interest applied to the account (i.e. 6.2%)

Responses

• 201 object

New Account Created
Show response Hide response
- account_id string(uuid)
  
  This is generated by Canopy. A unique ID for the account.
- account_status string
  
  The Status of the Account. Active upon account creation.
- account_status_subtype string
  
  The subtype of the Status of the Account. Null upon account creation.
- effective_at string(date-time)
  
  The Date-Time that this account became/becomes active.
- created_at string(date-time)
  
  The Date-Time which the account was created in the API.
- product_id string(uuid)
  
  The Product ID of the account.
- external_account_ids array[object]
  
  An Array of External Account IDs. These should be used to connect accounts created in Canopy to Users in your system and any connected external systems.
  Show child attributes Hide child attributes
  
  external_account_ids.name string
  
  Name of the External Party
  
  external_account_ids.id string
  
  External Account ID
- credit_limit_cents integer
  
  Total Amount (in cents) that this account can borrow.
- rate number
  
  The percentage interest applied to the account (i.e. 6.2 means 6.2%)
• 405

Invalid input

Definition

POST https://sandbox.canopyservicing.com/accounts

cURL example

curl \
 -X POST https://sandbox.canopyservicing.com/accounts \
 -H "Content-Type: application/json" \
 -d '{"product_id":"d119341c-47fd-4a55-bce7-28406dacfa20","external_ids":[{"name":"Globex Corporation","id":"22445702-a389-431f-927d-07b8d0750787"}],"credit_limit_cents":"400000","rate":"6.2"}'

Request payload example

{
  "product_id": "d119341c-47fd-4a55-bce7-28406dacfa20",
  "external_ids": [
    {
      "name": "Globex Corporation",
      "id": "22445702-a389-431f-927d-07b8d0750787"
    }
  ],
  "credit_limit_cents": "400000",
  "rate": "6.2"
}

Response example (201)

{
  "account_id": "5fb3a288-5f6c-440f-b079-b06c828b7768",
  "account_status": "suspended",
  "account_status_subtype": "suspended-bankruptcy",
  "effective_at": "2018-03-20T09:12:28Z",
  "created_at": "2017-06-20T09:12:14Z",
  "product_id": "d119341c-47fd-4a55-bce7-28406dacfa20",
  "external_account_ids": [
    {
      "name": "Umbrella Corporation",
      "id": "22445702-a389-431f-927d-07b8d0750787"
    }
  ],
  "credit_limit_cents": "400000",
  "rate": "6.2"
}

Response example (405)

No content

Get a specific Account

URL parameters

account_id Required / string(uuid)

Account ID

Responses

• 200 object

Successful query of information for a specific account
Show response Hide response
- account_id string(uuid)
  
  This is generated by Canopy. A unique ID for the account.
- account_status string
  
  The Status of the Account. Active upon account creation.
- account_status_subtype string
  
  The subtype of the Status of the Account. Null upon account creation.
- effective_at string(date-time)
  
  The Date-Time that this account became/becomes active.
- created_at string(date-time)
  
  The Date-Time which the account was created in the API.
- product_id string(uuid)
  
  The Product ID of the account.
- external_account_ids array[object]
  
  An Array of External Account IDs. These should be used to connect accounts created in Canopy to Users in your system and any connected external systems.
  Show child attributes Hide child attributes
  
  external_account_ids.name string
  
  Name of the External Party
  
  external_account_ids.id string
  
  External Account ID
- credit_limit_cents integer
  
  Total Amount (in cents) that this account can borrow.
- rate number
  
  The percentage interest applied to the account (i.e. 6.2 means 6.2%)
• 404

Account not found

Definition

GET https://sandbox.canopyservicing.com/accounts/{account_id}

cURL example

curl \
 -X GET https://sandbox.canopyservicing.com/accounts/a361c813-92e5-4765-82ea-9df368a81a89 \
 -H "Content-Type: application/json"

Response example (200)

{
  "account_id": "5fb3a288-5f6c-440f-b079-b06c828b7768",
  "account_status": "suspended",
  "account_status_subtype": "suspended-bankruptcy",
  "effective_at": "2018-03-20T09:12:28Z",
  "created_at": "2017-06-20T09:12:14Z",
  "product_id": "d119341c-47fd-4a55-bce7-28406dacfa20",
  "external_account_ids": [
    {
      "name": "Umbrella Corporation",
      "id": "22445702-a389-431f-927d-07b8d0750787"
    }
  ],
  "credit_limit_cents": "400000",
  "rate": "6.2"
}

Response example (404)

No content

Update a customer account

Update rate and/or credit_limit_cents for an individual account.

URL parameters

account_id Required / string(uuid)

Account ID

Body

rate number

The percentage default rate for accounts created under this interest policy (i.e. 5.2 indicates a 5.2% interest rate). You may customize rates for each account by overriding this default rate at the time of account creation or updating the rate for a given account.
credit_limit_cents integer

The default total oustanding amout of money (in cents) that an account created under this product could borrow. You may customize rates for each account by overriding this default rate at the time of account creation or updating the rate for a given account.

Responses

• 201

New Account Created
• 405

Invalid input

Definition

PUT https://sandbox.canopyservicing.com/accounts/{account_id}

cURL example

curl \
 -X PUT https://sandbox.canopyservicing.com/accounts/a361c813-92e5-4765-82ea-9df368a81a89 \
 -H "Content-Type: application/json" \
 -d '{"rate":"5.2","credit_limit_cents":"700000"}'

Request payload example

{
  "rate": "5.2",
  "credit_limit_cents": "700000"
}

Response example (201)

No content

Response example (405)

No content

Delete a specific Account

Deleting an account also deletes all of its associated line items.

URL parameters

account_id Required / string(uuid)

Account ID

Responses

• 204

Account Deleted
• 404

Account not found

Definition

DELETE https://sandbox.canopyservicing.com/accounts/{account_id}

cURL example

curl \
 -X DELETE https://sandbox.canopyservicing.com/accounts/{account_id} \
 -H "Content-Type: application/json"

Response example (204)

No content

Response example (404)

No content

Get line items for a specific account.

Line Items for an Account consist of charges to the account and payments by the account holder. Results are paginated and sorted by line item effective date.

URL parameters

account_id Required / string(uuid)

Account ID
effective_as_of_date string(date-time)

The Date-Time you would like the system to return the data as of. IE tell me what the line items were on 2020-10-20 00:00:00 EST. If empty it defaults to current time.
line_item_type string

The type of line items you would like to view. Options are charges and payments. If not provided, no filters will be applied.
offset number

The zero-indexed starting point for paginated line item requests sorted by line item effective date.
limit number

The maximum number of line items to be returned. Defaults to 100.

Responses

• 200 array[object]

Array of Line Items and their corresponding balances at their effective dates and times.
Show response Hide response
- account_id string(uuid)
  
  The account associated with the line item
- line_item_id string(uuid)
- line_item_status string
  
  the corresponding Status for a line item
  
  Values are posted, valid, invalid, declined, authorized, void, pending, successful, and unsuccessful.
- type string
  
  The Line Item Type. Either charge or payment.
  
  Values are charge and payment.
- originating_amount_cents number
  
  The originating amount of money (in cents) relating to this line item.
- balance_amount_cents number
  
  The current balance of the line item, which accounts for interest accrued per the product's interest policy and the account's interest rate attribute.
- merchant_data object
  Show child attributes Hide child attributes
  
  merchant_data.name string
  
  merchant_data.id string
  
  merchant_data.mcc_code number
  
  merchant_data.phone_number string(phonenumber)
- effective_at string(date-time)
  
  The Date-Time that this account became/becomes active
- created_at string(date-time)
  
  The Date-Time which the account was created in the API
- product_id string(uuid)
  
  the Product ID of the account
- description string
  
  A description of this particular line item if any. More common for adjustments.
- reference_id string
  
  User ID in your system to associate with the payment for the account defined in Canopy.
- dispute_id string(uuid)
  
  The ID for a dispute if present for this line item.
- external_ids array[object]
  
  An array of static references to ID fields in a third party system.
  Show child attributes Hide child attributes
  
  external_ids.name string
  
  Name of the External Party
  
  external_ids.id string
  
  External Account ID
- line_item_count string
  
  Total number of line items for the account.
• 404

Account not found

Definition

GET https://sandbox.canopyservicing.com/accounts/{account_id}/line_items

cURL example

curl \
 -X GET https://sandbox.canopyservicing.com/accounts/{account_id}/line_items \
 -H "Content-Type: application/json"

Response example (200)

[
  {
    "account_id": "2911ff2a-bebe-4c85-8d19-e6001015a8e3",
    "line_item_id": "ce9ed376-f151-435f-a59c-9e3cc183bbea",
    "line_item_status": "posted",
    "type": "charge",
    "originating_amount_cents": 42.0,
    "balance_amount_cents": 42.0,
    "merchant_data": {
      "name": "string",
      "id": "string",
      "mcc_code": 42.0,
      "phone_number": "string"
    },
    "effective_at": "2018-07-20T09:12:30Z",
    "created_at": "2018-06-20T09:12:30Z",
    "product_id": "158cd7a1-d813-42d2-90a3-9a91c43f18f8",
    "description": "Refund for invalid purchase",
    "reference_id": "e39c6b0d-5793-49c5-bee7-a2dbf8808f3a",
    "dispute_id": "string",
    "external_ids": [
      {
        "name": "Globex Card Processing",
        "id": "22445702-a389-431f-927d-07b8d0750787"
      }
    ],
    "line_item_count": "string"
  }
]

Response example (404)

No content

Create a dispute for a specific account's line item

URL parameters

account_id Required / string(uuid)

Account ID
line_item_id Required / string(uuid)

Line Item ID

Responses

• 204 object

Response upon successful creation of a dispute
Show response Hide response
- account_id string(uuid)
- line_item_id string(uuid)
- dispute_id string(uuid)
• 404

Account not found

Definition

POST https://sandbox.canopyservicing.com/accounts/{account_id}/line_items/{line_item_id}/disputes

cURL example

curl \
 -X POST https://sandbox.canopyservicing.com/accounts/{account_id}/line_items/{line_item_id}/disputes \
 -H "Content-Type: application/json"

Response example (204)

{
  "account_id": "string",
  "line_item_id": "string",
  "dispute_id": "string"
}

Response example (404)

No content

Get a specific account's summary details.

URL parameters

account_id Required / string(uuid)

Account ID
effective_as_of_date string(date-time)

The Date-Time you would like the system to return the data as of. IE tell me what the account information was on 2020-10-20 00:00:00 EST. If empty it defaults to current time.

Responses

• 200 object
Show response Hide response
- available_credit_balance number
  
  The total available credit balance (in cents) for the account.
- total_balance number
  
  The total balance (in cents) associated with the account.
- account_id string(uuid)
  
  The Canopy-generated ID for the account
- effective_as_of_date string(date-time)
  
  The Date-Time you would like the system to return the data as of. IE tell me what the account information was as if I had asked on 2020-10-20 00:00:00 EST. If empty it defaults to current time.
• 404

Account not found

Definition

GET https://sandbox.canopyservicing.com/accounts/{account_id}/summaries

cURL example

curl \
 -X GET https://sandbox.canopyservicing.com/accounts/{account_id}/summaries \
 -H "Content-Type: application/json"

Response example (200)

{
  "available_credit_balance": "600000",
  "total_balance": "400000",
  "account_id": "111eff36-cbec-4119-b188-b76200e804d8",
  "effective_as_of_date": "2018-07-20T09:10:14Z"
}

Response example (404)

No content

Get a list of all statements for a specific account

List of statements for the account. To view line items for a specific statement, use the /accounts/{account_id}/statements route

URL parameters

account_id Required / string(uuid)

Account ID
effective_as_of_date string(date-time)

The Date-Time you would like the system to return the data as of. IE tell me what the account information was on 2020-10-20 00:00:00 EST. If empty it defaults to current time.

Responses

• 200 object
Show response Hide response
- account_id string(uuid)
  
  The Canopy-generated ID for the account
- effective_as_of_date string(date-time)
  
  The Date-Time you would like the system to return the data as of. IE tell me what the account information was as if I had asked on 2020-10-20 00:00:00 EST. If empty it defaults to current time.
- statements_list array[object]
  
  An array of statements included in the billing cycle.
  Show child attributes Hide child attributes
  
  statements_list.statement_id string(uuid)
  
  A Canopy-generated ID for the statement
  
  statements_list.available_credit_balance number
  
  The total available credit balance (in cents) for the account.
  
  statements_list.total_balance number
  
  The total balance (in cents) associated with the account.
  
  statements_list.min_pay_due_date string(date-time)
  
  The Date-Time at which the minimum payment is due.
  
  statements_list.min_pay_amount_cents number
  
  The minimum amount (in cents) due for this statement.
  
  statements_list.billing_cycle_start_date string(date-time)
  
  The inclusive starting Date-Time that defines which transations are part of this statement.
  
  statements_list.billing_cycle_end_date string(date-time)
  
  The inclusive ending Date-Time that defines which transations are part of this statement.

Definition

GET https://sandbox.canopyservicing.com/accounts/{account_id}/statements_list

cURL example

curl \
 -X GET https://sandbox.canopyservicing.com/accounts/{account_id}/statements_list \
 -H "Content-Type: application/json"

Response example (200)

{
  "account_id": "111eff36-cbec-4119-b188-b76200e804d8",
  "effective_as_of_date": "2018-07-20T09:10:14Z",
  "statements_list": [
    {
      "statement_id": "string",
      "available_credit_balance": "600000",
      "total_balance": "400000",
      "min_pay_due_date": "2021-05-04T09:42:00+00:00",
      "min_pay_amount_cents": 42.0,
      "billing_cycle_start_date": "2021-05-04T09:42:00+00:00",
      "billing_cycle_end_date": "2021-05-04T09:42:00+00:00"
    }
  ]
}

Get a statement for a given date for a specific account.

This will return the most recent Statement information based on the effective_as_of_date. Relevant dates for an account's historical statements can be obtained from the accounts/{account_id}/statements_list route.

URL parameters

account_id Required / string(uuid)

Account ID
effective_as_of_date string(date-time)

The Date-Time you would like the system to return the data as of. IE tell me what the account information was on 2020-10-20 00:00:00 EST. If empty it defaults to current time.

Responses

• 200 object
Show response Hide response
- available_credit_balance number
  
  The total available credit balance (in cents) for the account.
- total_balance number
  
  The total balance (in cents) associated with the account.
- account_id string(uuid)
  
  The Canopy-generated ID for the account
- effective_as_of_date string(date-time)
  
  The Date-Time you would like the system to return the data as of. IE tell me what the account information was as if I had asked on 2020-10-20 00:00:00 EST. If empty it defaults to current time.
- min_pay_due_date string(date-time)
  
  The Date-Time at which the minimum payment is due.
- min_pay_amount_cents number
  
  The minimum amount (in cents) due for this statement.
- billing_cycle_start_date string(date-time)
  
  The inclusive starting Date-Time that defines which transations are part of this statement.
- billing_cycle_end_date string(date-time)
  
  The inclusive ending Date-Time that defines which transations are part of this statement.
- line_items array[object]
  
  An array of line items included in the billing cycle.
  Show child attributes Hide child attributes
  
  line_items.account_id Required / string(uuid)
  
  The account associated with the line item
  
  line_items.line_item_id Required / string(uuid)
  
  line_items.line_item_status Required / string
  
  the corresponding Status for a line item
  
  Values are posted, valid, invalid, declined, authorized, void, pending, successful, and unsuccessful.
  
  line_items.type Required / string
  
  The Line Item Type. Either charge or payment.
  
  Values are charge and payment.
  
  line_items.originating_amount_cents number
  
  The originating amount of money (in cents) relating to this line item.
  
  line_items.balance_amount_cents number
  
  The current balance of the line item, which accounts for interest accrued per the product's interest policy and the account's interest rate attribute.
  
  line_items.rate number
  
  The percentage rate applied to this line item (i.e. 15.5 means 15.5%). If it was not set at the time of charge creation, its default value is the default rate of the account.
  
  line_items.merchant_data object
  
  Show child attributes Hide child attributes
  
  line_items.merchant_data.name string
  
  line_items.merchant_data.id string
  
  line_items.merchant_data.mcc_code number
  
  line_items.merchant_data.phone_number string(phonenumber)
  
  line_items.effective_at Required / string(date-time)
  
  The Date-Time that this line item became/becomes active
  
  line_items.created_at Required / string(date-time)
  
  The Date-Time which the line item was created in the API
  
  line_items.product_id Required / string(uuid)
  
  the Product ID of the account
  
  line_items.description string
  
  A description of this particular line item if any. More common for adjustments.
  
  line_items.reference_id Required / string
  
  User ID in your system to associate with the payment for the account defined in Canopy.
  
  line_items.dispute_id string(uuid)
  
  The ID for a dispute if present for this line item.
  
  line_items.external_ids array[object]
  
  An array of static references to ID fields in a third party system.
  
  Show child attributes Hide child attributes
  
  line_items.external_ids.name string
  
  Name of the External Party
  
  line_items.external_ids.id string
  
  External Account ID
• 404

Account not found

Definition

GET https://sandbox.canopyservicing.com/accounts/{account_id}/statements

cURL example

curl \
 -X GET https://sandbox.canopyservicing.com/accounts/{account_id}/statements \
 -H "Content-Type: application/json"

Response example (200)

{
  "available_credit_balance": "600000",
  "total_balance": "400000",
  "account_id": "111eff36-cbec-4119-b188-b76200e804d8",
  "effective_as_of_date": "2018-07-20T09:10:14Z",
  "min_pay_due_date": "2021-05-04T09:42:00+00:00",
  "min_pay_amount_cents": 42.0,
  "billing_cycle_start_date": "2021-05-04T09:42:00+00:00",
  "billing_cycle_end_date": "2021-05-04T09:42:00+00:00",
  "line_items": [
    {
      "account_id": "2911ff2a-bebe-4c85-8d19-e6001015a8e3",
      "line_item_id": "ce9ed376-f151-435f-a59c-9e3cc183bbea",
      "line_item_status": "posted",
      "type": "charge",
      "originating_amount_cents": 42.0,
      "balance_amount_cents": 42.0,
      "rate": "15.5%",
      "merchant_data": {
        "name": "string",
        "id": "string",
        "mcc_code": 42.0,
        "phone_number": "string"
      },
      "effective_at": "2018-07-20T09:12:30Z",
      "created_at": "2018-06-20T09:12:30Z",
      "product_id": "158cd7a1-d813-42d2-90a3-9a91c43f18f8",
      "description": "Refund for invalid purchase",
      "reference_id": "e39c6b0d-5793-49c5-bee7-a2dbf8808f3a",
      "dispute_id": "string",
      "external_ids": [
        {
          "name": "Globex Card Processing",
          "id": "22445702-a389-431f-927d-07b8d0750787"
        }
      ]
    }
  ]
}

Response example (404)

No content

Canopy Servicing Core API

Products

Get all available products

URL parameters

Responses

Create a new product

Body

Responses

Get info on a particular product

URL parameters

Responses

Update an existing product

URL parameters

Body

Responses

Delete an existing product

URL parameters

Responses

Accounts

Get summary details for a specific product.

URL parameters

Responses

Get all available Accounts

URL parameters

Responses

Create a new customer account

Body

Responses

Get a specific Account

URL parameters

Responses

Update a customer account

URL parameters

Body

Responses

Delete a specific Account

URL parameters

Responses

Get line items for a specific account.

URL parameters

Responses

Create a dispute for a specific account's line item

URL parameters

Responses

Get a specific account's summary details.

URL parameters

Responses

Get a list of all statements for a specific account

URL parameters

Responses

Get a statement for a given date for a specific account.

URL parameters

Responses

Line items

Create a charge for a specific account

URL parameters

Body

Responses

Create a payment for a specific account

URL parameters

Body

Responses