Originate a Canadian EFT payment

How to originate a Canadian EFT payment

Overview

Let's assume you want to send $10 using a Canadian EFT payment. This could be paying a vendor, paying an employee salary, moving funds between corporate accounts, etc. To do so, we will need to create a Payment Order with a Counterparty.

Before making requests, you will need your API Key and Organization ID. To find these, you can follow this guide: Retrieve your API Key

1. Retrieve your Internal Account ID

📘

Internal Accounts

Modern Treasury uses the term Internal Account to refer to your bank accounts. Your customer, vendors, and employee's bank accounts are called External Accounts.

When you create a payment order, you must specify which account you want the transaction to originate from. If you are sending someone money, this is the account that the money will be taken out of.

To get an Internal Account ID, you can pick one from your accounts page. Any of the IDs will work for testing, although you can refer to Internal Accounts to see the differences in how the test banks process payments.

If you want to get all the internal accounts using the API , you can issue the following request:

curl --request GET \
  -u ORGANIZATION_ID:API_KEY \
  --url https://app.moderntreasury.com/api/internal_accounts
[
  {
    "id": "0f8e3719-3dfd-4613-9bbf-c0333781b59f",
    "object": "internal_account",
    "account_type": null,
    "party_name": "Modern Treasury",
    "party_type": null,
    "party_address": null,
    "account_details": [
      {
        "id": "aaf74f7e-d697-4a73-95a3-05bede2edce6",
        "object": "account_details",
        "account_number_safe": "2971",
        "account_number_type": null,
        "created_at": "2019-11-09T00:11:07Z",
        "updated_at": "2019-11-09T00:11:07Z"
      }
    ],
    "routing_details": [
      {
        "id": "a3649136-f8d2-46e8-8b41-327bd7da3110",
        "object": "routing_details",
        "payment_type": null,
        "routing_number": "021000021",
        "routing_number_type": "aba",
        "created_at": "2019-11-09T00:11:07Z",
        "updated_at": "2019-11-09T00:11:07Z"
      }
    ],
    "connection": {
      "id": "05487db0-e234-4ae8-914a-c627f76c987f",
      "object": "connection",
      "vendor_id": "example1",
      "vendor_name": "Gringotts Wizarding Bank",
      "created_at": "2019-11-09T00:11:07Z",
      "updated_at": "2019-11-09T00:11:07Z"
    },
    "created_at": "2019-11-09T00:11:07Z",
    "updated_at": "2019-11-09T00:11:07Z"
  }
]

You will receive an array of all your internal accounts. For this example, we'll just use one of the account IDs to originate the payment order from. In this response, we'll use the first one, 0f8e3719-3dfd-4613-9bbf-c0333781b59f.

📘

Sandbox Setup

For more information on how we've set up your accounts, visit our Sandbox Details guide.

2. Create a Counterparty

Counterparties need different information depending on how you want to use them. In the case we want to send them money using a Canadian EFT payment, we need to ensure the customer has both an account_number and a routing_number.

curl --request POST \
  -u ORGANIZATION_ID:API_KEY \
  --url https://app.moderntreasury.com/api/counterparties \
  -H 'Content-Type: application/json' \
  -d '{
        "name": "John Smith",
        "accounts": [
          {
            "account_type": "checking",
            "party_type": "individual",
            "routing_details": [
              {
                "routing_number_type": "ca_cpa",
                "routing_number": "001000562"
              }
            ],
            "account_details": [
              {
                "account_number": "0001007"
              }
            ]
          }
        ]
      }'
{
  "id":"37ba4454-dd33-4aa0-8906-0e2e4103e45c",
  "object": "counterparty",
  "name":"Kenner, Bach and Ledeen",
  "email":null,
  "metadata":{},
  "accounts": [
    {
      "id":"5acec2ef-987b-4260-aa97-b719eeb0a8d5",
      "object": "external_account",
      "account_type":"checking",
      "party_name":"Kenner, Bach and Ledeen",
      "party_type":null,
      "party_address":null,
      "account_details": [
        {
          "id":"81a7cd32-39f5-4f0c-873f-4d9137ec9cd9",
          "object": "account_detail",
          "account_number_safe":"1007",
          "account_number_type":"other",
          "created_at": "2019-11-09T00:11:07Z",
          "updated_at": "2019-11-09T00:11:07Z"
        }
      ],
      "routing_details": [
        {
          "id":"5ceb251f-0235-48a2-81cb-0c668f5ee81b",
          "object": "routing_detail",
          "payment_type":null,
          "routing_number":"001000562",
          "routing_number_type":"ca_cpa",
          "created_at": "2019-11-09T00:11:07Z",
          "updated_at": "2019-11-09T00:11:07Z"
        }
      ],
      "created_at": "2019-11-09T00:11:07Z",
      "updated_at": "2019-11-09T00:11:07Z"
    }
  ],
  "created_at": "2019-11-09T00:11:07Z",
  "updated_at": "2019-11-09T00:11:07Z"
}

Note that the response returns a new Counterparty object with 1 attached external account. You will need the ID of the external account (5acec2ef-987b-4260-aa97-b719eeb0a8d5) for the next step.

3. Create a Payment Order

To create a payment order, you will use your Internal Account ID (0f8e3719-3dfd-4613-9bbf-c0333781b59f) as the originating_account_id and the counterparty's Account ID (5acec2ef-987b-4260-aa97-b719eeb0a8d5) as the receiving_account_id.

You must also supply a value in the purpose field, which is a 3 digit [CPA code](https://www.tdcommercialbanking.com/wbb/help/English/wbwEFTCPACodes.html. In this example, I've used the code 200.

curl --request POST \
  -u ORGANIZATION_ID:API_KEY \
  --url https://app.moderntreasury.com/api/payment_orders \
  -H 'Content-Type: application/json' \
  -d '{
    "type": "eft",
    "amount": 1000,
    "direction": "credit",
    "currency": "CAD",
    "purpose": "200",
    "originating_account_id": "0f8e3719-3dfd-4613-9bbf-c0333781b59f",
    "receiving_account_id": "5acec2ef-987b-4260-aa97-b719eeb0a8d5"
  }'
{
  "id": "c5f4009c-bdd6-4cc1-84b2-17974ac9e77a",
  "object": "payment_order",
  "type": "eft",
  "amount": 1000,
  "direction": "credit",
  "originating_account_id": "0f8e3719-3dfd-4613-9bbf-c0333781b59f",
  "receiving_account": {
    "id": "5acec2ef-987b-4260-aa97-b719eeb0a8d5",
    "object": "external_account",
    "account_type": "checking",
    "party_name": "Kenner, Bach & Ledeen",
    "party_type": null,
    "party_address": null,
    "account_details": [
      {
        "id": "81a7cd32-39f5-4f0c-873f-4d9137ec9cd9",
        "object": "account_detail",
        "account_number_safe": "1007",
        "account_number_type": "other",
        "created_at": "2019-11-09T00:11:07Z",
        "updated_at": "2019-11-09T00:11:07Z"
      }
    ],
    "routing_details": [
      {
        "id": "5ceb251f-0235-48a2-81cb-0c668f5ee81b",
        "object": "routing_detail",
        "payment_type": null,
        "routing_number": "001000562",
        "routing_number_type": "ca_cpa",
        "created_at": "2019-11-09T00:11:07Z",
        "updated_at": "2019-11-09T00:11:07Z"
      }
    ],
    "created_at": "2019-11-09T00:11:07Z",
    "updated_at": "2019-11-09T00:11:07Z"
  },
  "receiving_account_id": "5acec2ef-987b-4260-aa97-b719eeb0a8d5",
  "receiving_account_type": "external_account",
  "accounting_category_id": null,
  "currency": "CAD",
  "effective_date": "2018-11-19",
  "priority": "normal",
  "description": null,
  "statement_descriptor": null,
  "remittance_information": null,
  "metadata": {},
  "status": "approved",
  "counterparty_id": "37ba4454-dd33-4aa0-8906-0e2e4103e45c",
  "transaction_ids": [],
  "charge_bearer": null,
  "foreign_exchange_indicator": null,
  "foreign_exchange_contract": null,
  "purpose": "200",
  "created_at": "2019-11-09T00:11:07Z",
  "updated_at": "2019-11-09T00:11:07Z"
}

This is the response you will see. It contains the ID of the payment order, c5f4009c-bdd6-4cc1-84b2-17974ac9e77a, as well as additional details about it.

Optional: Handle post-creation events

Modern Treasury sends a number of useful events once your Payment Order is created. Use the Dashboard, Webhooks, or a third party solution to receive these events and perform actions like notifying the counterparty of the transfer, knowing when the purchase order is complete, or determining when and why a return occurred.