CA Remittance Integration Guide

How do I send cross-border remittances from Canadian customers using Cybrid-integrated payouts?

CA Remittance lets Canadian individuals send cross-border remittances using Cybrid-integrated payouts. Your customer funds a Canadian dollar balance from their own bank, and a remittance plan converts it and delivers the funds to a recipient abroad in the local currency — all through a single API integration.

Every money movement in this guide is a plan and an execution. A deposit plan funds the customer's CAD fiat account over Interac e-Transfer from the customer's own e-Transfer account. A remittance plan then trades CAD to USDC_SOL or USDT_TRX, depending on the payout corridor, and pays out to the recipient's foreign bank account over the local rail. Senders are onboarded as individuals with KYC, and recipients are tracked as verified counterparties.

India (INR over IFSC) is the example corridor used throughout. Other corridors are available and follow the same flow with corridor-specific fields.

At a high level, you will:

  1. Onboard and verify the customer with KYC.
  2. Create the CAD fiat account, the trading account for your corridor (USDC_SOL or USDT_TRX), and the customer's deposit bank account.
  3. Add the customer's Interac e-Transfer account as an external bank account.
  4. Fund the CAD account with a deposit plan.
  5. Create and verify the recipient counterparty and their foreign bank account.
  6. Create and execute the remittance plan to pay out.
  7. Optionally, return CAD to the customer with a withdrawal plan.
⚠️

Plans and executions are required in Canada

Canadian money movement must use plans and executions to adhere to newly approved regulatory flows. If your integration uses quotes, transfers, and trades for these steps, see Migrate to Plans and Executions.

✅

Ready for production?

Once you have built and tested this integration in sandbox, the Production Access Checklist covers what it takes to qualify for production access and go live.


Flow of funds

Figure: CA remittance flow of funds.

Funds move left to right across the Cybrid boundary. A deposit plan moves funds from the customer's Interac e-Transfer external bank account into their CAD fiat account inside Cybrid, where KYC and the deposit bank account are held. A remittance plan then runs two stages: a trade stage settles the CAD into the customer's USDC_SOL or USDT_TRX trading account, and a payout stage pays out to the recipient's foreign external bank account. The recipient is tracked as a verified individual counterparty.

Flow of funds diagram: a deposit plan funds a CAD account via Interac e-Transfer, then a remittance plan trades CAD to USDC_SOL or USDT_TRX and pays out to a foreign bank account

Arrow colors in the diagram: green is fiat movement, orange is crypto movement, and blue is a trade. Solid lines are plans; dashed lines are the stages a plan runs.


Table of Contents

  1. Prerequisites
  2. Customer onboarding
  3. Create accounts
  4. Create deposit bank account
  5. Add the customer's Interac e-Transfer account
  6. Fund the CAD account with a deposit plan
  7. Create the recipient counterparty
  8. Create the recipient external bank account
  9. Create and execute the remittance plan
  10. Return funds with a withdrawal plan
  11. Webhooks
  12. Additional resources

1. Prerequisites

Before integrating the CA Remittance flow, configure your sandbox bank with the required features.

Bank configuration

When creating your bank in the sandbox environment, configure these settings:

Customer type support:

Enable individual customers:

  • Individual customers (individual_customers)

Fiat account assets:

Enable the fiat currency for the funding country:

  • CAD

Trading symbols:

Enable the trading pair for each payout corridor: USDC_SOL-CAD for CAD to USDC_SOL, or USDT_TRX-CAD for CAD to USDT_TRX.

⚠️

Canada: zero balances required

Due to regulatory requirements in Canada, Cybrid cannot hold balances in customer accounts on the platform. All funds submitted to the platform in Canada must have instructions assigned to keep the funds in transit, with zero balances maintained once transactions complete.

ℹ️

Enable the payout symbols for your corridors

Contact Cybrid support to enable the payout symbols for the payout corridors you require (for example, INR-USDC_SOL). Confirm corridor support via supported_payout_symbols.

ℹ️

Customer-owned e-Transfer accounts

Your bank must have the individual_customer_raw_routing_details feature to create the customer's Interac e-Transfer external bank account in step 5.

ℹ️

API scopes

Your API credentials need the plans:read, plans:execute, executions:read, and executions:execute scopes to create and execute plans, plus customers:read when the originator or receiver is a customer and counterparties:read when it is a counterparty.

ℹ️

Supported corridors for C2C remittances

This guide implements a consumer-to-consumer (C2C) remittance. For the full list of destination corridors and the participant types each supports, see Supported Corridors. Some corridors originate from the US only (for example, Pakistan) and are not available from Canada.


2. Customer onboarding

Create the customer, then verify their identity with KYC through the Persona SDK.

Create the customer

Endpoint: POST /api/customers Reference: Create Customer

Set type to individual. Only type is required at creation.

POST /api/customers
Content-Type: application/json
Authorization: Bearer YOUR_TOKEN

{
  "type": "individual",
  "email_address": "[email protected]",
  "phone_number": "555-0100"
}
{
  "guid": "customer_guid",
  "type": "individual",
  "state": "storing",
  "created_at": "2026-07-19T12:00:00.000Z",
  "updated_at": "2026-07-19T12:00:00.000Z"
}
ℹ️

PII fields are optional at creation

Not all fields are required to create a customer. Email and phone help identify customers beyond the customer_guid. Do not provide the customer's name at creation — Persona collects it during KYC, and the legal name returned by Persona becomes the customer's name on file.

Customer states

StateDescription
storingPlatform is storing customer details
unverifiedCustomer created, awaiting identity verification
verifiedCustomer identity verified
rejectedCustomer verification rejected
frozenCustomer account frozen

Poll GET /api/customers/{customer_guid} until state transitions to unverified.

ℹ️

Polling interval

Use exponential backoff starting at 1 second. In sandbox, state transitions typically complete within seconds. In production, some operations may take longer.

Verify the customer

Endpoint: POST /api/identity_verifications Reference: Create Identity Verification

Create the Persona inquiry. Cybrid returns a persona_inquiry_id you pass to the Persona SDK to launch the capture flow — government ID and selfie (KYC). Use method: id_and_selfie:

POST /api/identity_verifications
Content-Type: application/json
Authorization: Bearer YOUR_TOKEN

{
  "type": "kyc",
  "method": "id_and_selfie",
  "customer_guid": "customer_guid"
}
{
  "guid": "identity_verification_guid",
  "type": "kyc",
  "method": "id_and_selfie",
  "customer_guid": "customer_guid",
  "state": "storing",
  "outcome": null,
  "created_at": "2026-07-19T12:00:00.000Z",
  "updated_at": "2026-07-19T12:00:00.000Z"
}
ℹ️

Preparing customers before verification

Preparing customers before verification greatly increases success rates. See: Verify an Individual Customer

⚠️

Customer must be unverified

Identity verification can only be initiated for customers in the unverified state. The customer state transitions from storing to unverified before you can start the verification process.

Identity verification states

StateDescription
storingPlatform is storing verification details
waitingWaiting for the customer to complete verification
pendingVerification submitted, awaiting processing
reviewingVerification under manual review
expiredVerification session expired
completedVerification completed (check the outcome field)

Poll GET /api/identity_verifications/{identity_verification_guid} until state transitions to completed, then confirm outcome is passed.

Integrate the Persona SDK

Persona offers Hosted Flow, Embedded Flow, and native iOS/Android SDKs. The example below uses the Embedded Flow via NPM — see Persona's integration methods to pick the option that fits your app.

✅

Recommended integration

Cybrid recommends the embedded flow with the native iOS and Android SDKs for the best customer experience.

Install the SDK:

npm install [email protected] --save

Initialize the client with the persona_inquiry_id from the identity verification response:

import Persona from 'persona';

const client = new Persona.Client({
  inquiryId: 'persona_inquiry_id',
  language: 'en',
  onReady: () => client.open(),
  onComplete: ({ inquiryId, status, fields }) => {
    // Poll Cybrid or subscribe to identity_verification.completed
  },
  onCancel: ({ inquiryId, sessionToken }) => { /* user dismissed */ },
  onError: (error) => { /* log SDK error */ }
});

Key callbacks:

  • onReady — SDK ready to open.
  • onComplete — user finished the flow; verification can still fail downstream, confirm via the Cybrid API.
  • onCancel — user dismissed the flow.
  • onError — SDK error.

The language parameter accepts ISO 639-1 codes. See Persona's supported languages for the full list.

ℹ️

Resume incomplete sessions

If the customer abandons the flow before completing, generate a new session token via POST /api/persona_sessions and pass it to the SDK as sessionToken instead of inquiryId. See Resume Persona Inquiry Session.

ℹ️

Sandbox testing with expected_behaviours

In sandbox, set expected_behaviours on the identity verification request to force a deterministic outcome — useful for end-to-end tests without driving the Persona flow.

ValueEffect
passed_immediatelyVerification completes with outcome: passed.
failed_immediatelyVerification completes with outcome: failed.
tax_id_not_checkedTax ID check is skipped during verification.

Example expected_behaviours request body:

{
  "type": "kyc",
  "method": "id_and_selfie",
  "customer_guid": "customer_guid",
  "expected_behaviours": ["passed_immediately"]
}
❗️

Sandbox only

The expected_behaviours field is rejected in production with a 400 error: Parameter expected_behaviours not permitted in production. Remove the field before deploying.

When the customer returns from the Persona SDK workflow, confirm the customer record has transitioned to verified by querying GET /api/customers/{customer_guid}. Once verified, you can create the customer's accounts and fund them.

Related: Create a Customer · Verify an Individual Customer

✅

Checkpoint

The customer is verified. You can now create their accounts and move on to funding.


3. Create accounts

Create the CAD fiat account and the trading account for the customer. The examples use USDC_SOL; for corridors that pay out from USDT_TRX, create a USDT_TRX trading account instead.

Endpoint: POST /api/accounts Reference: Create Account

Create the CAD fiat account

POST /api/accounts
Content-Type: application/json
Authorization: Bearer YOUR_TOKEN

{
  "type": "fiat",
  "customer_guid": "customer_guid",
  "asset": "CAD",
  "name": "CAD Account"
}
{
  "guid": "fiat_account_guid",
  "type": "fiat",
  "customer_guid": "customer_guid",
  "asset": "CAD",
  "name": "CAD Account",
  "state": "storing",
  "created_at": "2026-07-19T12:00:00.000Z",
  "updated_at": "2026-07-19T12:00:00.000Z"
}

Create the USDC_SOL trading account

POST /api/accounts
Content-Type: application/json
Authorization: Bearer YOUR_TOKEN

{
  "type": "trading",
  "customer_guid": "customer_guid",
  "asset": "USDC_SOL",
  "name": "USDC_SOL Trading Account"
}
{
  "guid": "trading_account_usdc_sol_guid",
  "type": "trading",
  "customer_guid": "customer_guid",
  "asset": "USDC_SOL",
  "name": "USDC_SOL Trading Account",
  "state": "storing",
  "created_at": "2026-07-19T12:00:00.000Z",
  "updated_at": "2026-07-19T12:00:00.000Z"
}

Account states

StateDescription
storingPlatform is storing account details
createdAccount created and ready for use

Poll GET /api/accounts/{account_guid}?include_balances=false until each account's state transitions to created.

ℹ️

Account types

Fiat accounts hold currencies like CAD, while trading accounts hold cryptocurrencies like USDC_SOL and USDT_TRX. The remittance plan in step 9 trades CAD into the trading account for your corridor before paying out, so the trading account must exist before you create the plan.

ℹ️

Customer fiat accounts require a deposit bank account

Every customer fiat account requires a main deposit bank account before any deposit or withdrawal can be executed. Create it immediately after the fiat account — see step 4 and Customer Deposit Bank Accounts.

Related: Creating Platform Accounts


4. Create deposit bank account

Create a main deposit bank account for the customer's CAD fiat account. This is required before any deposit or withdrawal can be executed.

Endpoint: POST /api/deposit_bank_accounts Reference: Create Deposit Bank Account

POST /api/deposit_bank_accounts
Content-Type: application/json
Authorization: Bearer YOUR_TOKEN

{
  "type": "main",
  "account_guid": "fiat_account_guid",
  "customer_guid": "customer_guid"
}
{
  "guid": "deposit_bank_account_guid",
  "type": "main",
  "customer_guid": "customer_guid",
  "account_guid": "fiat_account_guid",
  "asset": "CAD",
  "state": "storing",
  "unique_memo_id": "unique_memo_id",
  "counterparty_name": "John Doe",
  "account_details": [
    { "account_number": "111222333" }
  ],
  "routing_details": [
    { "routing_number_type": "CPA", "routing_number": "000100002" }
  ],
  "created_at": "2026-07-19T12:00:00.000Z",
  "updated_at": "2026-07-19T12:00:00.000Z"
}

Deposit bank account states

StateDescription
storingPlatform is storing account details
createdDeposit bank account created

Poll GET /api/deposit_bank_accounts/{deposit_bank_account_guid} until state transitions to created.

⚠️

Deposit bank account required

Every customer fiat account must have a main deposit bank account before any deposit or withdrawal can be executed. Provision the deposit bank account immediately after creating the customer's fiat account — see Customer Deposit Bank Accounts.

ℹ️

Routing details

The response includes account_details (account number), routing_details (CPA routing number), counterparty_name (account holder name), and counterparty_address (account holder address) for incoming EFT deposits.

ℹ️

No deposit bank account error

Creating an execution for a deposit or withdrawal plan on a customer fiat account that has no main deposit bank account fails with HTTP 422 and message_code no_deposit_bank_account. Remediate by creating the main deposit bank account on the fiat account, then create the execution again. If the plan has passed its expires_at, create a new plan first.

Related: Customer Deposit Bank Accounts


5. Add the customer's Interac e-Transfer account

Create an external bank account for the customer's own Interac e-Transfer address. This account is the source of the deposit plan in step 6, and the destination if you return funds in step 10.

Endpoint: POST /api/external_bank_accounts Reference: Create External Bank Account

Set account_kind to raw_routing_details, asset to CAD, and customer_guid to the customer. Do not send counterparty_guid. In counterparty_bank_account_details, add an ETRANSFER entry with account_identifier_type set to EMAIL; a second ETRANSFER entry with account_identifier_type set to PHONE_NUMBER is optional.

POST /api/external_bank_accounts
Content-Type: application/json
Accept-Version: 2026-09-01
Authorization: Bearer YOUR_TOKEN

{
  "name": "external_bank_account_name",
  "account_kind": "raw_routing_details",
  "customer_guid": "customer_guid",
  "asset": "CAD",
  "counterparty_name": {
    "first": "John",
    "last": "Doe"
  },
  "counterparty_address": {
    "street": "123 Main St",
    "city": "Toronto",
    "subdivision": "ON",
    "postal_code": "M5V 2T6",
    "country_code": "CA"
  },
  "counterparty_bank_account_details": [
    {
      "payment_rail": "ETRANSFER",
      "account_identifier_type": "EMAIL",
      "account_identifier": "[email protected]"
    },
    {
      "payment_rail": "ETRANSFER",
      "account_identifier_type": "PHONE_NUMBER",
      "account_identifier": "+14165550123"
    }
  ]
}

The holder name must match the customer's identity record. Poll GET /api/external_bank_accounts/{external_bank_account_guid} with Accept-Version: 2026-09-01, or subscribe to the external_bank_account.completed, external_bank_account.failed, and external_bank_account.expired webhooks, until state transitions to completed; the account moves to completed once the ownership check passes.

Webhook Events: external_bank_account.completed, external_bank_account.failed, external_bank_account.expired

⚠️

Account requirements

The customer must be verified, and your bank must have the individual_customer_raw_routing_details feature; otherwise the request returns 422 with message_code set to not_raw_routing_details_bank. On API versions before 2026-09-01, an EMAIL entry is rejected with invalid_account_number. Do not add bank code entries to the same request: an account created with them does not support Interac e-Transfer.

Related: Use a customer-owned Interac e-Transfer account


6. Fund the CAD account with a deposit plan

Create a deposit plan from the customer's Interac e-Transfer account to their CAD fiat account, then execute it. Interac sends the deposit request to the customer by email, and by SMS if the external bank account has a phone number, and the execution also returns a gateway_url you can display so the customer can authorize the deposit through their own bank.

ℹ️

Availability

Interac e-Transfer is only available to Canadian banks on the Cybrid Platform and only works with CAD on CAD-based fiat accounts.

Create the deposit plan

Endpoint: POST /api/plans Reference: Create Plan

Set type to deposit, the source to the e-Transfer external bank account with payment_rail set to etransfer, and the destination to the CAD fiat account.

POST /api/plans
Content-Type: application/json
Authorization: Bearer YOUR_TOKEN

{
  "type": "deposit",
  "customer_guid": "customer_guid",
  "source_account": {
    "guid": "external_bank_account_guid",
    "amount": 10000,
    "payment_rail": "etransfer"
  },
  "destination_account": {
    "guid": "fiat_account_guid"
  }
}
{
  "guid": "plan_guid",
  "type": "deposit",
  "customer_guid": "customer_guid",
  "state": "storing",
  "expires_at": "2026-07-19T12:01:00.000Z",
  "source_account": {
    "guid": "external_bank_account_guid",
    "type": "external_bank_account",
    "asset": "CAD",
    "requested_amount": 10000,
    "payment_rail": "etransfer"
  },
  "destination_account": {
    "guid": "fiat_account_guid",
    "type": "fiat",
    "asset": "CAD"
  },
  "stages": [],
  "fees": [],
  "created_at": "2026-07-19T12:00:00.000Z",
  "updated_at": "2026-07-19T12:00:00.000Z"
}
ℹ️

Amounts are in base units

Amounts are in base units. For CAD, 10000 = $100.00 (cents). For USDC_SOL, 10000000 = 10.00 USDC_SOL (micro-dollars).

ℹ️

Source or destination amount

Specify amount on either the source or destination account. A source amount fixes what the customer sends; a destination amount fixes what lands in the CAD fiat account after fees.

Plan states

StateDescription
storingPlatform is storing plan details
planningPlatform is building the plan
completedPlan is ready for execution
failedPlan creation failed

Poll GET /api/plans/{plan_guid} until state transitions to completed. The completed plan has a single deposit stage. Execute the plan before expires_at.

Webhook Events: plan.planning, plan.completed, plan.failed

Execute the deposit plan

Endpoint: POST /api/executions Reference: Create Execution

POST /api/executions
Content-Type: application/json
Authorization: Bearer YOUR_TOKEN

{
  "plan_guid": "plan_guid"
}
{
  "guid": "execution_guid",
  "type": "deposit",
  "plan_guid": "plan_guid",
  "customer_guid": "customer_guid",
  "state": "storing",
  "source_account": {
    "guid": "external_bank_account_guid",
    "type": "external_bank_account",
    "asset": "CAD"
  },
  "destination_account": {
    "guid": "fiat_account_guid",
    "type": "fiat",
    "asset": "CAD"
  },
  "stages": [],
  "fees": [],
  "created_at": "2026-07-19T12:00:00.000Z",
  "updated_at": "2026-07-19T12:00:00.000Z"
}

Display the gateway URL

Interac sends the deposit request to the contact details on the customer's Interac e-Transfer account, so displaying the gateway_url is optional. To display it, poll GET /api/executions/{execution_guid} until the deposit stage returns a link in its links array with type set to gateway_url. Show the value to the customer so they can select their bank and authorize the deposit.

{
  "guid": "execution_guid",
  "type": "deposit",
  "state": "executing",
  "stages": [
    {
      "guid": "stage_guid",
      "type": "deposit",
      "state": "executing",
      "links": [
        {
          "type": "gateway_url",
          "value": "gateway_url"
        }
      ]
    }
  ]
}
ℹ️

Domain allowlisting

The gateway_url uses the domain etransfer.interac.ca. Allowlist this domain in your application if needed.

⚠️

Asynchronous processing

Generating the gateway_url can take time in both sandbox and production. Use webhook registration and polling as a backup to handle the asynchronous gateway_url generation.

ℹ️

Deposit request expiry

The customer must authorize the deposit before the e-Transfer request expires. Deposit requests are valid for 1 day.

⚠️

Sandbox behavior

In sandbox, Interac e-Transfer deposits complete automatically, the gateway_url does not open a working Interac flow, and failures cannot be simulated.

Wait for completion

Poll GET /api/executions/{execution_guid} or subscribe to the execution.completed webhook. Once the execution is completed, the CAD funds are available in the fiat account; destination_account.executed_amount is the amount deposited.

Execution states

StateDescription
storingPlatform is storing execution details
executingPlatform is executing the plan
reviewingExecution under review
completedPlan execution completed successfully
failedPlan execution failed (check the failure_code)

Webhook Events: execution.executing, execution.completed, execution.failed. No webhook fires for reviewing; poll the execution.

Handle terminal failed states via the failure_code:

  • payment_request_expired — the customer did not authorize before the request expired.
  • recipient_cancelled — the customer rejected the e-Transfer request.

Related: Interac e-Transfer · Customer Deposit Bank Accounts

✅

Checkpoint

The deposit execution is completed and CAD is available in the customer's fiat account. Wait for this state before you create the remittance plan.


7. Create the recipient counterparty

Create the recipient as a customer-level individual counterparty and verify it via watchlists. The counterparty must reach the verified state before you can create the recipient external bank account and the remittance plan.

Create the counterparty

Endpoint: POST /api/counterparties Reference: Create Counterparty

Include only the required fields: type, name, address.city, and address.country_code. Add customer_guid for the customer-scoped counterparty.

POST /api/counterparties
Content-Type: application/json
Authorization: Bearer YOUR_TOKEN

{
  "type": "individual",
  "customer_guid": "customer_guid",
  "name": {
    "first": "John",
    "last": "Doe"
  },
  "address": {
    "city": "Mumbai",
    "country_code": "IN"
  }
}
{
  "guid": "recipient_counterparty_guid",
  "type": "individual",
  "customer_guid": "customer_guid",
  "state": "storing",
  "created_at": "2026-07-19T12:00:00.000Z",
  "updated_at": "2026-07-19T12:00:00.000Z"
}
ℹ️

Required fields only

For individual counterparties the required fields are type, name.first, name.last, address.city, and address.country_code. Add customer_guid for customer-scoped counterparties created with a bank token. The API spec marks only country_code as required on address, but the Cybrid platform enforces city + country_code together — see Create a Counterparty.

ℹ️

Corridor-specific fields

For Cybrid-managed remittance corridors, the destination country may require additional fields on the recipient counterparty (date_of_birth, identification_numbers, address street + subdivision, etc.). Refer to the relevant payout guide for the destination country before omitting fields in production. See Supported Corridors.

Verify the counterparty

Endpoint: POST /api/identity_verifications Reference: Create Identity Verification

Counterparty verification screens the recipient's PII through watchlist checks against government sanctions lists, PEP databases, and adverse media sources. It is an API call that does not require an SDK.

POST /api/identity_verifications
Content-Type: application/json
Authorization: Bearer YOUR_TOKEN

{
  "type": "counterparty",
  "method": "watchlists",
  "counterparty_guid": "recipient_counterparty_guid"
}
{
  "guid": "identity_verification_guid",
  "type": "counterparty",
  "method": "watchlists",
  "counterparty_guid": "recipient_counterparty_guid",
  "customer_guid": "customer_guid",
  "state": "storing",
  "outcome": null,
  "failure_codes": [],
  "created_at": "2026-07-19T12:00:00.000Z",
  "updated_at": "2026-07-19T12:00:00.000Z"
}

Counterparty states

StateDescription
storingPlatform is storing counterparty details
unverifiedCounterparty created, awaiting verification
verifiedCounterparty verified via watchlist check
rejectedCounterparty rejected

Poll GET /api/identity_verifications/{identity_verification_guid} until state transitions to completed. When outcome is passed, the counterparty transitions to verified; when failed, inspect failure_codes (for example watchlist_check_failure, pep_check_failure, media_check_failure) and the counterparty transitions to rejected. Results are applied as soon as the screening provider returns them; a one-minute backup check covers delayed provider notifications. Alternatively, subscribe to the identity_verification.completed webhook event.

Webhook Events: identity_verification.waiting, identity_verification.completed

Related: Verify a Counterparty · Creating Counterparties


8. Create the recipient external bank account

Create the recipient's foreign external bank account tied to the verified counterparty. The example below uses India (INR over IFSC); required fields vary by destination corridor.

Endpoint: POST /api/external_bank_accounts Reference: Create External Bank Account

ℹ️

Use raw routing details for foreign payouts

Use account_kind raw_routing_details for the recipient's foreign bank account and tie it to the verified counterparty_guid. The payment_rail and bank_code_type depend on the destination corridor — IFSC for India, and other rails (SPEI, PIX, SEPA, and so on) for other corridors.

ℹ️

Accept-Version for foreign raw-routing accounts

Creating foreign raw-routing external bank accounts requires Accept-Version: 2025-10-01 or later; the examples send 2026-09-01, where the Platform verifies ownership as the account is created and a counterparty account omits counterparty_name, counterparty_address and counterparty_email_address. Corridor-specific bank-account fields vary by destination; refer to the relevant payout guide before omitting fields in production.

POST /api/external_bank_accounts
Content-Type: application/json
Accept-Version: 2026-09-01
Authorization: Bearer YOUR_TOKEN

{
  "name": "Recipient INR Account",
  "account_kind": "raw_routing_details",
  "customer_guid": "customer_guid",
  "counterparty_guid": "recipient_counterparty_guid",
  "asset": "INR",
  "counterparty_bank_account_details": [
    {
      "account_identifier": "account_number",
      "payment_rail": "IFSC",
      "bank_code": "bank_ifsc_code",
      "bank_code_type": "IFSC"
    }
  ]
}
{
  "guid": "recipient_external_bank_account_guid",
  "name": "Recipient INR Account",
  "asset": "INR",
  "account_kind": "raw_routing_details",
  "environment": "sandbox",
  "bank_guid": "bank_guid",
  "customer_guid": "customer_guid",
  "counterparty_guid": "recipient_counterparty_guid",
  "state": "storing",
  "created_at": "2026-07-19T12:00:00.000Z",
  "updated_at": "2026-07-19T12:00:00.000Z"
}
ℹ️

Counterparty must be verified

The referenced counterparty must be in the verified state. Creating an external bank account against an unverified counterparty fails with the unverified_counterparty failure code.

External bank account states

StateDescription
storingPlatform is storing external bank account details
pendingPlatform is creating the external bank account
completedExternal bank account created and ready for use
failedExternal bank account creation failed (check the failure_code)
reviewingHeld for a compliance review
expiredCompliance review lapsed; the account cannot be used
deletingPlatform is deleting the external bank account
deletedExternal bank account deleted

Poll GET /api/external_bank_accounts/{external_bank_account_guid} with Accept-Version: 2026-09-01, or subscribe to the external_bank_account.completed, external_bank_account.failed, and external_bank_account.expired webhooks, until state transitions to completed; the account is then ready for use. On earlier versions pending and reviewing read as storing and expired as failed. The external_bank_account.expired webhook fires only for accounts created on API version 2026-09-01 or later; for accounts created on an earlier version, subscribe to external_bank_account.completed and external_bank_account.failed, or poll. The counterparty's ownership is implied, so there is no ownership verification step. The account usually moves storing → pending → completed. If the counterparty matches an existing identity that needs a compliance review, it moves to reviewing and ends completed, failed with compliance_rejection, or expired. If it ends in failed or expired, stop polling and do not use the account. On failed, inspect failure_code (for example create_failed, compliance_rejection or legal_entity_incomplete_pii) and re-create the counterparty or the account as needed.

Webhook Events: external_bank_account.completed, external_bank_account.failed, external_bank_account.expired

Related: Foreign Fiat External Bank Accounts · Add External Bank Accounts

✅

Checkpoint

The recipient counterparty is verified and their foreign external bank account is completed. You have everything needed to create and execute the remittance plan.


9. Create and execute the remittance plan

Create a remittance plan with the CAD fiat account as the source and the recipient's foreign external bank account as the destination, then execute it. The plan trades CAD to USDC_SOL in the customer's trading account, then converts USDC_SOL to INR and pays out over the local rail.

Create the remittance plan

Endpoint: POST /api/plans Reference: Create Plan

POST /api/plans
Content-Type: application/json
Authorization: Bearer YOUR_TOKEN

{
  "type": "remittance",
  "customer_guid": "customer_guid",
  "source_account": {
    "guid": "fiat_account_guid",
    "amount": 10000
  },
  "destination_account": {
    "guid": "recipient_external_bank_account_guid"
  },
  "purpose_of_transaction": "family_support"
}
{
  "guid": "plan_guid",
  "type": "remittance",
  "customer_guid": "customer_guid",
  "state": "storing",
  "expires_at": "2026-07-19T12:01:00.000Z",
  "source_account": {
    "guid": "fiat_account_guid",
    "type": "fiat",
    "asset": "CAD",
    "requested_amount": 10000
  },
  "destination_account": {
    "guid": "recipient_external_bank_account_guid",
    "type": "external_bank_account",
    "asset": "INR"
  },
  "stages": [],
  "fees": [],
  "created_at": "2026-07-19T12:00:00.000Z",
  "updated_at": "2026-07-19T12:00:00.000Z"
}

Poll GET /api/plans/{plan_guid} until state transitions to completed, then execute it before it expires. The completed plan has two stages: a trade stage from the CAD fiat account to the USDC_SOL trading account, then a payout stage from the trading account to the recipient's external bank account.

ℹ️

Specify the amount on the source account

You must specify an amount on either the source or destination account — the amount drives the plan's quote. If source amount is specified, the plan ensures that amount is debited. If destination amount is specified, the plan ensures that exact amount is deposited. Include amount under source_account by default, expressed in CAD base units. To keep a zero balance, use the deposit execution's destination_account.executed_amount.

ℹ️

Intermediate accounts

The example omits intermediate_accounts; Cybrid selects the customer's trading account (USDC_SOL or USDT_TRX, depending on the corridor) for the trade stage. Pass intermediate_accounts only when the customer has more than one eligible trading account for a stage.

ℹ️

Purpose of transaction

purpose_of_transaction is corridor-dependent. Some destinations reject a plan without an accepted purpose (invalid_purpose_of_transaction). Refer to the destination payout guide for accepted values.

ℹ️

Supporting documents (corridor-dependent)

Some corridors require supporting documents attached to the plan's supporting_documents (for example, an invoice carrying a document_reference_number). This is most common for B2B payouts — see the "Upload a supporting document" step in the CA B2B and US B2B integration guides, and File Upload, before going live.

ℹ️

Travel rule information

Travel rule information is required only when the originator is not the holder of the trading account or when the receiver is not the holder of the external bank account.

⚠️

Reversals may incur fees

If the final withdrawal to the destination bank account fails after currency conversions have occurred, any reversals may incur fees.

Execute the plan

Endpoint: POST /api/executions Reference: Create Execution

POST /api/executions
Content-Type: application/json
Authorization: Bearer YOUR_TOKEN

{
  "plan_guid": "plan_guid"
}
{
  "guid": "execution_guid",
  "type": "remittance",
  "plan_guid": "plan_guid",
  "customer_guid": "customer_guid",
  "state": "storing",
  "source_account": {
    "guid": "fiat_account_guid",
    "type": "fiat",
    "asset": "CAD"
  },
  "destination_account": {
    "guid": "recipient_external_bank_account_guid",
    "type": "external_bank_account",
    "asset": "INR"
  },
  "stages": [],
  "fees": [],
  "created_at": "2026-07-19T12:00:00.000Z",
  "updated_at": "2026-07-19T12:00:00.000Z"
}

Poll GET /api/executions/{execution_guid} or subscribe to the execution.completed webhook until state transitions to completed; see Execution states. Each stage reports its own state, and the payout completes after the trade and payout stages are both completed. On failure, inspect the failure_code (for example compliance_rejection, invalid_destination, party_name_invalid, external_vendor_error).

ℹ️

Creating an execution initiates the transaction

Creating an execution initiates the actual transaction. Ensure the plan has been reviewed and is ready before executing.

⚠️

Plans expire quickly

Remittance plans expire (default ~60 seconds, plan_expired error). Use the expires_at field on the plan response to confirm when the plan expires, and execute it before then.

ℹ️

Executed amounts

The executed amounts in the response represent the actual amounts transferred, which should match the quoted amounts from the plan.

Related: Sending Cross-Border Payments · Payout Prices


10. Return funds with a withdrawal plan

To return CAD to the customer, for example when a remittance cannot proceed, create a withdrawal plan from the CAD fiat account to the customer's Interac e-Transfer account from step 5, then execute it.

Endpoint: POST /api/plans Reference: Create Plan

Set type to withdrawal and payment_rail to etransfer on the destination. Include a security_question and security_answer pair on the destination account for the Interac e-Transfer send.

POST /api/plans
Content-Type: application/json
Authorization: Bearer YOUR_TOKEN

{
  "type": "withdrawal",
  "customer_guid": "customer_guid",
  "source_account": {
    "guid": "fiat_account_guid",
    "amount": 10000
  },
  "destination_account": {
    "guid": "external_bank_account_guid",
    "payment_rail": "etransfer",
    "security_question": "What is the password we agreed upon?",
    "security_answer": "Sunflower"
  }
}
{
  "guid": "plan_guid",
  "type": "withdrawal",
  "customer_guid": "customer_guid",
  "state": "storing",
  "expires_at": "2026-07-19T12:01:00.000Z",
  "source_account": {
    "guid": "fiat_account_guid",
    "type": "fiat",
    "asset": "CAD",
    "requested_amount": 10000
  },
  "destination_account": {
    "guid": "external_bank_account_guid",
    "type": "external_bank_account",
    "asset": "CAD",
    "payment_rail": "etransfer"
  },
  "stages": [],
  "fees": [],
  "created_at": "2026-07-19T12:00:00.000Z",
  "updated_at": "2026-07-19T12:00:00.000Z"
}

Poll GET /api/plans/{plan_guid} until state transitions to completed; the completed plan has a single withdrawal stage. Execute it with POST /api/executions, as in step 6, and poll the execution until it is completed. When the withdrawal is submitted, Interac notifies the customer by email or SMS at the contact details on their Interac e-Transfer account.

ℹ️

Security question and answer

security_question (maximum 40 characters) and security_answer (maximum 25 characters) must be sent together, and only for an etransfer destination. The answer must use letters, digits, and hyphens only; if the provider rejects the question or answer, the execution fails with failure_code set to invalid_security_question. See Interac e-Transfer for security question best practices.

Related: Interac e-Transfer


Webhooks

Subscribe to webhooks for real-time notifications instead of polling. Create webhook subscriptions in the Partner Portal under Developers → Subscriptions (see Webhooks). Accounts and deposit bank accounts have no webhook events — use polling for those resources. Stages have no webhook events; read stage details from the execution.

ℹ️

Webhook events

This integration uses the following webhook events:

EventTrigger
identity_verification.waitingIdentity verification is waiting for the customer to start.
identity_verification.completedIdentity verification completed (check outcome).
external_bank_account.completedExternal bank account is ready for use.
external_bank_account.failedExternal bank account failed (check the failure_code).
external_bank_account.expiredOwnership verification or compliance review lapsed.
plan.planningDeposit, remittance, or withdrawal plan is being built.
plan.completedPlan is ready for execution.
plan.failedPlan creation failed.
execution.executingExecution is running; poll stages for the gateway_url.
execution.completedDeposit, payout, or withdrawal completed.
execution.failedExecution failed (check the failure_code).

See: Webhook Events


Additional resources


Did this page help you?