Step 1: Create Account Holder
POST {{teller_domain}}/api/v1/account_holders
Example request payload:
{
"type": "busines",
"email": "[email protected]",
"first_name": "John",
"last_name": "Smith"
}
The type for pull requests is required to be business.
Example response payload:
{
"data": {
"email": "[email protected]",
"id": 123,
"type": "business"
}
}
The id in this response corresponds to the Account Holder ID which will be required in Step 3 below.
Step 2: Tokenize Customer information
The email used to create the account holder from Step 1 is used to create a token.
POST {{teller_domain}}/api/v1/tokens or {{teller_domain}}/api/v2/tokens
| Field | Type | Required | Details |
| name | string | yes | name of the person or business max 60 characters |
| string | conditional | email of the person or business required for e-transfer email notifications | |
| phone_number | string | conditional | phone number of person or business 10 digits in length do not include dashes or spaces includes area code and phone number required for e-transfer sms notifications |
If notification choice is email, the payload for tokenization looks as follows:
{
"etransfer": {
"name": "John Smith",
"email": "[email protected]"
}
}
Example response payload:
{
"data": {
"customer_name": "John Smith",
"email": "[email protected]",
"phone_number": null,
"token": "ettk_BY-HbLvFocbzF8O23EF4E37121688FE9D",
"type": "etransfer"
}
}
If notification choice is SMS, the payload for tokenization looks as follows:
{
"etransfer": {
"name": "John Smith",
"phone_number": "1234567890"
}
}
Example response payload:
{
"data": {
"customer_name": "John Smith",
"email": null,
"phone_number": 1234567890,
"token": "ettk_BY-HbLvFocbzF8O23EF4E37121688FE9D",
"type": "etransfer"
}
}
The token from the response in this step is used to create a financial account in Step 3 below.
Step 3: Create Financial Account
A financial account must be created with the token from Step 2. As well as the id from Step 1. The id from Step 1 is used as the :id path parameter. This step links together the Account Holder from Step 1 with the Financial Account created from this step.
POST {{teller_domain}}/api/v1/account_holders/:id/financial_accounts
Example request payload:
{
"token": "ettk_BY-HbLvFocbzF8O23EF4E37121688FE9D"
}
Example response payload:
{
"data": {
"account_holder_id": 123,
"customer_name": "John Smith",
"email":"[email protected]",
"id": "etransfer_123_ettk_BY-HbLvFocbzF8O23EF4E37121688FE9D",
"network_type": "etransfer",
"phone_number": null,
"status": "active",
"type": "etransfer"
}
}
The id from this response is used the step below to create a pull transaction.
Step 4: Create pull transaction
A pull request is created by using the id from the response in Step 3. This id is used as the value for financial_account in the request body. A pull request requires an idempotency key to avoid duplicate pull transactions.
POST {{teller_domain}}/api/v1/transactions/pull
| Field | Type | Required | Details |
| amount | number | yes | in cents the amount you wish to send |
| currency | string | yes | currency of the transaction |
| product | string | yes | product of the transaction |
| financial_account | string | yes | financial account to which you wish to send money |
Example request payload:
{
"amount": 2000,
"currency": "CAD",
"product": "disbursements",
"financial_account": "etransfer_123_ettk_BY-HbLvFocbzF8O23EF4E37121688FE9D",
"idempotency_key": "abc123"
}
Example response payload:
{
"data": {
"amount": 2000,
"currency": "CAD",
"financial_account": "etransfer_123_ettk_BY-HbLvFocbzF8O23EF4E37121688FE9D",
"gateway_codes": [
{
"code": "action_code_not_found",
"message": "No action code found"
}
],
"id": "0dsd8048-334f-43d5-8475-79c17cbc4d79",
"status": "awaiting_settlement"
}
}
The id from the response in this step can be used to track the pull transaction and see any related details using the GET Show Transactions endpoint.
Note: Initial status is always “awaiting_settlement” unless an error occurred, which we would catch upon creation.
Webhooks
For information on how to setup Interac E-transfer webhook notifications, please see this documentation.
The id from the response in Step 4 can be used for tracking the pull transaction. This id is used as the id value for the outgoing webhook notifications.
Example outgoing Interac E-transfer webhook payload
{
"id": "0dsd8048-334f-43d5-8475-79c17cbc4d79",
"type": "pull",
"status": "approved",
"processor_status": "successful",
"network": "etransfer",
"currency": "CAD",
"amount": 2000,
"action_message": "No action code found", // not implemented yet - default message
"action_code": "action_code_not_found" // not implemented yet - default code
}
Related pages: