NAV
shell javascript

Introduction

Welcome to the Method API documentation. Method's API enables you to move money between your user's financial accounts including student loans, credit cards, mortgages etc.

This API is organized around REST. Each resource section contains a detailed description of how the resource works. This includes descriptions for each attribute of a resource object, as well as code snippets (on the right) showing how to interface with the resource.

Authentication

curl https://api.methodfi.com/<RESOURCE> \
  -H "Authorization: Bearer <ACCESS_TOKEN>" \
  ...
var method = require('method-client')('<ACCESS_TOKEN>');

In order access any resource relating to your organization, you must include an active ACCESS_TOKEN to your request. This ACCESS_TOKEN serves as an identifier of your organization.

Get an access token

For information on setting up your organization and getting an ACCESS_TOKEN, please contact [email protected]

Merchants

ENDPOINTS

GET /merchants

GET /merchants/:id

The merchants resource provides an interface for listing and retrieving available merchants. A merchant is an entity to which payments for a specific account are sent.

The merchant object

Example Merchant Object

{
  "id": "mch_q3TcyX8G43qms",
  "name": "FedLoan Servicing",
  "type": "Student Loan",
  "street": "P.O. Box 790234",
  "city": "St. Louis",
  "state": "MO",
  "zip_code": "63179-0234"
}
Attribute Type Description
id string A unique identifier for the merchant.
name string Name of the merchant.
type string Type of merchant (e.g; Student Loan, Credit Card, Mortgage).
street string The merchant's street address.
city string The merchant's city.
state string The merchant's state.
zip_code string The merchant's zip code.

List merchants

GET /merchants

curl https://api.methodfi.com/merchants?type=Student%20Loan%20Servicer&limit=5 \
  -H "Authorization: Bearer <ACCESS_TOKEN>"
var method = require('method-client')('<ACCESS_TOKEN>');

method.merchants.list({ type: 'Student Loan', limit: 5 })
  .then((merchants) => {
    // Code for merchants
  })
  .catch((error) => {
    // Log error to service
  });

Response

[
  {
    "id": "mch_q3TcyX8G43qms",
    "name": "FedLoan Servicing",
    "type": "Student Loan",
    "street": "P.O. Box 790234",
    "city": "St. Louis",
    "state": "MO",
    "zip_code": "63179-0234"
  }, {
    "id": "mch_mPfCr7XB499VC",
    "name": "EdFinancial Servicing",
    "type": "Student Loan",
    "street": "120 N Seven Oaks Dr",
    "city": "Knoxville",
    "state": "TN",
    "zip_code": "37922"
  },
  {
    "id": "mch_bDddBpPYJddCU",
    "name": "MOHELA",
    "type": "Student Loan",
    "street": "P.O. Box 1022",
    "city": "Chesterfield",
    "state": "MO",
    "zip_code": "63006-1022"
  },
  ...
]

Returns a list of merchants that satisfy the search query. The resulting merchants are not sorted in any order.

Parameters

Attribute Type Description
name string (optional) A substring used to match a merchant's name.
type string (optional) A filter for the merchant's type.
limit number (optional) The maximum number of merchants to return. Defaults to 10.

Retrieve a merchant

GET /merchants/:id

curl https://api.methodfi.com/merchants/mch_mPfCr7XB499VC \
  -H "Authorization: Bearer <ACCESS_TOKEN>"
var method = require('method-client')('<ACCESS_TOKEN>');

method.merchants.get('mch_mPfCr7XB499VC')
  .then((merchant) => {
    // Code for merchant
  })
  .catch((error) => {
    // Log error to service
  });

Response

{
  "id": "mch_mPfCr7XB499VC",
  "name": "EdFinancial Servicing",
  "type": "Student Loan",
  "street": "120 N Seven Oaks Dr",
  "city": "Knoxville",
  "state": "TN",
  "zip_code": "37922"
}

Returns the merchant associated with the id.

Parameters

Attribute Type Description
id string (required) The merchant's id

Accounts

ENDPOINTS

GET /accounts

GET /accounts/:id

POST /accounts

The accounts resource provides an interface for executing payments between your user's accounts. An account is an entity that is categorized as being either ACH or Liability. This determines its available functions.

The account object

Example Account Object

{
  "id": "acc_8hNf895JxY6XX",
  "name": "John Doe",
  "type": "liability",
  "liability": {
    "merchant_id": "mch_q3TcyX8G43qms",
    "account_number": "7781132940"
  },
  "ach": null,
  "created_at": "2020-04-10T19:46:43.439Z",
  "updated_at": "2020-04-10T19:46:43.439Z"
}
Attribute Type Description
id string A unique identifier for the account.
name string Name of the account holder.
type string The type of account (ach or liability).
liability Object, nullable An object containing properties of a Liability account.
liability.merchant_id string The id of the merchant associated to the account.
liability.account_number string The account number to which payments should be made.
ach Object, nullable An object containing properties of an ACH account.
ach.account_number string The account number to which payments are received or sent from.
ach.routing_number string The routing number corresponding to this ACH account.
created_at string A timestamp of when the account was created.
updated_at string A timestamp of when the account was last updated.

List accounts

GET /accounts

curl https://api.methodfi.com/accounts?name=John%20Doe&limit=5 \
  -H "Authorization: Bearer <ACCESS_TOKEN>"
var method = require('method-client')('<ACCESS_TOKEN>');

method.accounts.list({ name: 'John Doe', limit: 10 })
  .then((accounts) => {
    // Code for accounts
  })
  .catch((error) => {
    // Log error to service
  });

Response

[
  {
    "id": "acc_8hNf895JxY6XX",
    "name": "John Doe",
    "type": "liability",
    "liability": {
        "merchant_id": "mch_q3TcyX8G43qms",
        "account_number": "7781132940"
    },
    "ach": null,
    "created_at": "2020-04-10T19:46:43.439Z",
    "updated_at": "2020-04-10T19:46:43.439Z"
  }, {
    "id": "acc_7tHz5JD9MVdLp",
    "name": "John Doe",
    "type": "ach",
    "liability": null,
    "ach": {
        "account_number": "7793251962",
        "routing_number": "111000614"    
    },
    "created_at": "2020-04-10T19:46:43.439Z",
    "updated_at": "2020-04-10T19:46:43.439Z"
  },
  ...
]

Returns a list of accounts that satisfy the search query. The resulting accounts are sorted by their creation date (created_at).

Parameters

Attribute Type Description
name string (optional) A substring used to match an account's name.
limit number (optional) The maximum number of accounts to return. Defaults to 10.

Retrieve an account

GET /accounts/:id

curl https://api.methodfi.com/accounts/acc_8hNf895JxY6XX \
  -H "Authorization: Bearer <ACCESS_TOKEN>"
var method = require('method-client')('<ACCESS_TOKEN>');

method.accounts.get('acc_8hNf895JxY6XX')
  .then((account) => {
    // Code for account
  })
  .catch((error) => {
    // Log error to service
  });

Response

{
    "id": "acc_8hNf895JxY6XX",
    "name": "John Doe",
    "type": "liability",
    "liability": {
        "merchant_id": "mch_q3TcyX8G43qms",
        "account_number": "7781132940"
    },
    "ach": null,
    "created_at": "2020-04-10T19:46:43.439Z",
    "updated_at": "2020-04-10T19:46:43.439Z"
}

Returns the account associated with the id.

Parameters

Attribute Type Description
id string (required) The account's id

Create an account

POST /accounts

curl https://api.methodfi.com/accounts \
  -X POST \
  -H "Authorization: Bearer <ACCESS_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{ "name": "John Doe", "type": "liability", "merchant_id": "mch_q3TcyX8G43qms", "account_number": "7781132940" }'
var method = require('method-client')('<ACCESS_TOKEN>');

method.accounts
  .create({
    name: 'John Doe',
    type: 'liability',
    merchant_id: 'mch_q3TcyX8G43qms',
    account_number: '7781132940',
  })
  .then((account) => {
    // Code for account
  })
  .catch((error) => {
    // Log error to service
  });

Response

{
    "id": "acc_8hNf895JxY6XX",
    "name": "John Doe",
    "type": "liability",
    "liability": {
        "merchant_id": "mch_q3TcyX8G43qms",
        "account_number": "7781132940"
    },
    "ach": null,
    "created_at": "2020-04-10T19:46:43.439Z",
    "updated_at": "2020-04-10T19:46:43.439Z"
}

Returns the newly created account.

Parameters

Attribute Type Description
name string (required) Name of the account holder.
type string (required) The type of account (ach or liability).
account_number string (required) The account number to which payments are received or sent from.
routing_number string (required for ach) The routing number corresponding to this account.
merchant_id string (required for liability) The id of the merchant associated to the account.

Payments

ENDPOINTS

GET /payments

GET /payments/:id

POST /payments

PUT /payments/:id

The payments resource provides an interface for executing payments to accounts created using the Method API. A payment represents an amount of money (in cents) to be sent from a source account (ACH only) to a destination account (ACH or Liability).

The payment object

Example Payment Object

{
  "id": "pmt_Mk66zmg6jxRA2",
  "type": "standard",
  "status": "pending",
  "amount": 5500,
  "source": "acc_7tHz5JD9MVdLp",
  "destination": "acc_8hNf895JxY6XX",
  "error": null,
  "created_at": "2020-04-10T19:46:43.439Z",
  "sent_at": null,
  "updated_at": "2020-04-10T19:46:43.439Z"
}
Attribute Type Description
id string A unique identifier for the payment.
type string The type of payment (standard or sameday). Payments of type standard take 2-3 business days to post to a destination account, while sameday payments are posted on the same day.
status string The current status of the payment. (e.g; pending)
amount string The amount of the payment in cents.
source string The id of an ACH account from which the payment amount will be retrieved.
destination string The id of an ACH or Liability account to which the payment amount will be sent.
error string, nullable An error message explaining why a payment failed to be sent.
created_at string A timestamp of when the payment was created.
sent_at string, nullable A timestamp of when the payment was sent.
updated_at string A timestamp of when the payment was last updated.

Payment statuses

This is a list of all possible statuses that a payment can transition into.

Status Description
pending The initial status of a successfully created payment.
in_progress The payment is in the process of being sent.
sent The payment has been sent. And the payment has been updated to contain a sent_at timestamp.
canceled The payment has been canceled.
error An error occurred while processing the payment.

List payments

GET /payments

curl https://api.methodfi.com/payments?status=sent&limit=5 \
  -H "Authorization: Bearer <ACCESS_TOKEN>"
var method = require('method-client')('<ACCESS_TOKEN>');

method.payments.list({ status: 'sent', limit: 5 })
  .then((payments) => {
    // Code for payments
  })
  .catch((error) => {
    // Log error to service
  });

Response

[
  {
    "id": "pmt_Mk66zmg6jxRA2",
    "type": "standard",
    "status": "sent",
    "amount": 5500,
    "source": "acc_7tHz5JD9MVdLp",
    "destination": "acc_8hNf895JxY6XX",
    "error": null,
    "created_at": "2020-04-10T19:46:43.439Z",
    "sent_at": "2020-04-11T19:46:43.439Z",
    "updated_at": "2020-04-11T19:46:43.439Z"
  }, {
    "id": "pmt_qCpypdAtZKLGh",
    "type": "sameday",
    "status": "sent",
    "amount": 10500,
    "source": "acc_7tHz5JD9MVdLp",
    "destination": "acc_8hNf895JxY6XX",
    "error": null,
    "created_at": "2020-04-10T19:46:43.439Z",
    "sent_at": "2020-04-11T19:46:43.439Z",
    "updated_at": "2020-04-11T19:46:43.439Z"
  },
  ...
]

Returns a list of payments that satisfy the search query. The resulting payments are sorted by their creation date (created_at).

Parameters

Attribute Type Description
type string (optional) A filter for the payment's type.
status string (optional) A filter for the payment's current status.
source string (optional) The id of an ACH account from which a payment was made.
destination string (optional) The id of an ACH or Liability account to which a payment was made.
limit number (optional) The maximum number of payments to return. Defaults to 10.

Retrieve a payment

GET /payments/:id

curl https://api.methodfi.com/payments/pmt_qCpypdAtZKLGh \
  -H "Authorization: Bearer <ACCESS_TOKEN>"
var method = require('method-client')('<ACCESS_TOKEN>');

method.payments.get('pmt_qCpypdAtZKLGh')
  .then((payment) => {
    // Code for payment
  })
  .catch((error) => {
    // Log error to service
  });

Response

{
  "id": "pmt_qCpypdAtZKLGh",
  "type": "sameday",
  "status": "sent",
  "amount": 10500,
  "source": "acc_7tHz5JD9MVdLp",
  "destination": "acc_8hNf895JxY6XX",
  "error": null,
  "created_at": "2020-04-10T19:46:43.439Z",
  "sent_at": "2020-04-11T19:46:43.439Z",
  "updated_at": "2020-04-11T19:46:43.439Z"
}

Returns the payment associated with the id.

Parameters

Attribute Type Description
id string (required) The payment's id

Create a payment

POST /payments

curl https://api.methodfi.com/payments \
  -X POST \
  -H "Authorization: Bearer <ACCESS_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{ "amount": 10500, "type": "sameday", "source": "acc_7tHz5JD9MVdLp", "destination": "acc_8hNf895JxY6XX" }'
var method = require('method-client')('<ACCESS_TOKEN>');

method.payments
  .create({
    amount: 10500,
    type: 'sameday',
    source: 'acc_7tHz5JD9MVdLp',
    destination: 'acc_8hNf895JxY6XX',
  })
  .then((payment) => {
    // Code for new payment
  })
  .catch((error) => {
    // Log error to service
  });

Response

{
  "id": "pmt_qCpypdAtZKLGh",
  "type": "sameday",
  "status": "pending",
  "amount": 10500,
  "source": "acc_7tHz5JD9MVdLp",
  "destination": "acc_8hNf895JxY6XX",
  "error": null,
  "created_at": "2020-04-10T19:46:43.439Z",
  "sent_at": null,
  "updated_at": "2020-04-10T19:46:43.439Z"
}

This endpoint allows you to create a payment to a specified account. Payments are transmitted electronically from a source account and are posted to a destination account within 2-3 business days for standard payments or on the same day for sameday payments.

Parameters

Attribute Type Description
amount string (required) The amount of the payment in cents.
type string (optional) The type of payment (standard or sameday). Defaults to standard.
source string (required) The id of an ACH account from which the payment amount will be retrieved.
destination string (required) The id of an ACH or Liability account to which the payment amount will be sent.

Cancel a payment

PUT /payments/:id

curl https://api.methodfi.com/payments/pmt_qCpypdAtZKLGh \
  -X PUT \
  -H "Authorization: Bearer <ACCESS_TOKEN>" \
  -d '{ "status": "canceled" }'
var method = require('method-client')('<ACCESS_TOKEN>');

method.payments.cancel('pmt_qCpypdAtZKLGh')
  .then((payment) => {
    // Code for canceled payment
  })
  .catch((error) => {
    // Log error to service
  });

Response

{
  "id": "pmt_qCpypdAtZKLGh",
  "type": "sameday",
  "status": "canceled",
  "amount": 10500,
  "source": "acc_7tHz5JD9MVdLp",
  "destination": "acc_8hNf895JxY6XX",
  "error": null,
  "created_at": "2020-04-10T19:46:43.439Z",
  "sent_at": null,
  "updated_at": "2020-04-10T19:46:43.439Z"
}

Returns the canceled payment. Payments can only be canceled during the pending status.

Parameters

Attribute Type Description
id string (required) The payment's id

Webhooks

ENDPOINTS

GET /webhooks

GET /webhooks/:id

POST /webhooks

DELETE /webhooks/:id

Webhooks are used to receive notifications on events relating to changes that occur in any of your organization's collections. Use this resource to register for specific notifications you would like to receive.

The webhook object

Example Webhook Object

{
  "id": "wbh_iXZePASe8kM4P",
  "event": "payment.update",
  "url": "https://webhook.example.com/payments",
  "created_at": "2020-04-10T19:46:43.439Z",
  "updated_at": "2020-04-10T19:46:43.439Z"
}
Attribute Type Description
id string A unique identifier for the webhook.
event string An event for which the webhook will be triggered. Refer to the list of possible webhook events.
url string URL to which a POST request will be sent everytime the event occurs.
created_at string A timestamp of when the webhook was created.
updated_at string A timestamp of when the webhook was last updated.

Webhook events

This is a list of all possible webhook events that you can listen for.

Accounts

Payments

The webhook payload

Example Webhook Payload

{
  "id": "wbh_iXZePASe8kM4P",
  "event": "payment.update",
  "url": "https://webhook.example.com/payments",
  "data": {
    "id": "pmt_Mk66zmg6jxRA2",
    "status": "sent"
  }
}

When one of your webhooks is triggered by an event, the API will send a POST request to the specified URL on the webhook with data relating to the changes that occurred.

List webhooks

GET /webhooks

curl https://api.methodfi.com/webhooks?limit=5 \
  -H "Authorization: Bearer <ACCESS_TOKEN>"
var method = require('method-client')('<ACCESS_TOKEN>');

method.webhooks.list({ limit: 5 })
  .then((webhooks) => {
    // Code for webhooks
  })
  .catch((error) => {
    // Log error to service
  });

Response

[
  {
    "id": "wbh_iXZePASe8kM4P",
    "event": "payment.update",
    "url": "https://webhook.example.com/payments",
    "created_at": "2020-04-10T19:46:43.439Z",
    "updated_at": "2020-04-10T19:46:43.439Z"
  }, {
    "id": "wbh_aQMgWmrwnaVn6",
    "event": "account.create",
    "url": "https://webhook.example.com/accounts",
    "created_at": "2020-04-10T19:46:43.439Z",
    "updated_at": "2020-04-10T19:46:43.439Z"
  },
  ...
]

Returns a list of webhooks. The resulting webhooks are sorted by their creation date (created_at).

Parameters

Attribute Type Description
limit number (optional) The maximum number of webhooks to return. Defaults to 10.

Retrieve a webhook

GET /webhooks/:id

curl https://api.methodfi.com/webhooks/wbh_iXZePASe8kM4P \
  -H "Authorization: Bearer <ACCESS_TOKEN>"
var method = require('method-client')('<ACCESS_TOKEN>');

method.webhooks.get('wbh_iXZePASe8kM4P')
  .then((webhook) => {
    // Code for webhook
  })
  .catch((error) => {
    // Log error to service
  });

Response

{
  "id": "wbh_iXZePASe8kM4P",
  "event": "payment.update",
  "url": "https://webhook.example.com/payments",
  "created_at": "2020-04-10T19:46:43.439Z",
  "updated_at": "2020-04-10T19:46:43.439Z"
}

Returns the webhook associated with the id.

Parameters

Attribute Type Description
id string (required) The webhook's id

Create a webhook

POST /webhooks

curl https://api.methodfi.com/webhooks \
  -X POST \
  -H "Authorization: Bearer <ACCESS_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{ "event": "account.create", "url": "https://webhook.example.com/accounts" }'
var method = require('method-client')('<ACCESS_TOKEN>');

method.webhooks.create({ event: 'account.create', url: 'https://webhook.example.com/accounts' })
  .then((webhook) => {
    // Code for new webhook
  })
  .catch((error) => {
    // Log error to service
  });

Response

{
  "id": "wbh_g7VNAprsh2c49",
  "event": "account.create",
  "url": "https://webhook.example.com/accounts",
  "created_at": "2020-04-10T19:46:43.439Z",
  "updated_at": "2020-04-10T19:46:43.439Z"
}

Returns the newly created webhook.

Parameters

Attribute Type Description
event string (required) An event for which the webhook will be triggered. Refer to the list of possible webhook events.
url string (required) URL to which a POST request will be sent everytime the event occurs.

Delete a webhook

DELETE /webhooks/:id

curl https://api.methodfi.com/webhooks/wbh_g7VNAprsh2c49 \
  -X DELETE \
  -H "Authorization: Bearer <ACCESS_TOKEN>"
var method = require('method-client')('<ACCESS_TOKEN>');

method.webhooks.delete('wbh_g7VNAprsh2c49')
  .then((webhook) => {
    // Code for deleted webhook
  })
  .catch((error) => {
    // Log error to service
  });

Response

{
  "id": "wbh_g7VNAprsh2c49",
  "event": "account.create",
  "url": "https://webhook.example.com/accounts",
  "created_at": "2020-04-10T19:46:43.439Z",
  "updated_at": "2020-04-10T19:46:43.439Z"
}

Returns the deleted webhook.

Parameters

Attribute Type Description
id string (required) The webhook's id

Errors

The Method API uses the following error codes for all its resources:

Code Description
400 Bad Request — Your request to a resource is incomplete or invalid.
401 Unauthorized - Your request did not include an active ACCESS_TOKEN.
403 Forbidden - You were forbidden from access a specific resource.
404 Not Found - The specified resource was not found.
429 Too Many Requests - You are allowed 1000 requests per 300 seconds.