CAD Collections and Payout

LedgerBlock supports both CAD collection and payout, allowing merchants to receive CAD from customers and send CAD to beneficiaries through the supported Interac payment rail.

CAD collection handles incoming funds, while CAD payout handles outgoing funds.

How CAD Collection and Payout Works

The CAD payment flow depends on the direction of the transaction:

CAD Collection

Customer
   ↓
Sends CAD
   ↓
Interac
   ↓
LedgerBlock
   ↓
CAD Wallet Credited
   ↓
Collection Webhook

CAD Payout

CAD Wallet
   ↓
Payout Request
   ↓
LedgerBlock
   ↓
Interac
   ↓
Beneficiary
   ↓
Payout Webhook

CAD Collection

For CAD collection, the customer sends CAD to the merchant's configured Interac collection details.

Once LedgerBlock receives and processes the payment, the transaction is recorded and the corresponding CAD wallet is credited.

LedgerBlock then sends a collection webhook to the merchant's configured notification URL.

A successful collection webhook contains information such as the transaction reference, transaction amount, transaction fee, currency, collection email, sender information, and transaction status.

Example:

{
  "message": "Transaction Completed",
  "transaction_id": "20580e50-1b32-40a6-aa46-ac8e795b3zas",
  "transaction_reference": "CA1MR6ahQBCJ",
  "transaction_status": "SUCCESSFUL",
  "transaction_fee": 0.0,
  "transaction_amount_without_fee": 20.0,
  "transaction_amount": 20.0,
  "transaction_currency": "CAD",
  "payee_collection_email": "[email protected]",
  "source_information": {
    "collection_email": "[email protected]",
    "collection_name": "John Doe"
  },
  "event_id": "9d46a6c7-fbb4-48f0-912c-4f9611fe5844",
  "type": "collection"
}

The merchant can use the collection webhook to:

• Confirm that the CAD payment was successfully received.
• Identify the transaction.
• Identify the sender where available.
• Confirm the amount received.
• Reconcile the payment with its internal records.
• Update the customer's transaction status.

CAD Payout

For CAD payout, the merchant initiates a payment from the user's CAD wallet to a beneficiary.

LedgerBlock validates and processes the payout through Interac.

A payout can generate more than one webhook during its lifecycle. The first notification indicates that the payout has been initiated and is still being processed. A final notification is sent when the payout is completed.

Payout Initiated

The initiated payout webhook indicates that the transaction has entered processing.

{
  "message": "Transaction Initiated",
  "transaction_id": "20580e50-1b32-40a6-aa46-ac8e795b3zas",
  "transaction_reference": "2a446ee4-8d3a-40ed-b33f-6430df69e7bf",
  "merchant_reference": "ORDER-1001",
  "transaction_status": "PENDING",
  "transaction_fee": 0.4,
  "transaction_amount_without_fee": 19.6,
  "transaction_amount": 20.0,
  "transaction_currency": "CAD",
  "customer_id": "9d4c4ec5-59ea-4130-bf8a-6a5edec401ee",
  "recipient": {
    "account_number": null,
    "account_name": "Oluwatobi Ishola",
    "bank_name": null,
    "amount": 19.6
  },
  "extras": {
    "interac_instruction": {
      "question": "What is the PIN?",
      "answer": 1234
    }
  },
  "event_id": "9d46b957-61b2-4b27-85cf-059069893237",
  "type": "payout_initiated"
}

The interac_instruction contains the Interac security question and answer associated with the payout.

Important: A payout_initiated event with a PENDING status is not a final confirmation. Merchants should wait for the final payout webhook before marking the transaction as completed.

Payout Completed

When the payout is successfully completed, LedgerBlock sends the final payout webhook.

{
  "message": "Transaction Completed",
  "transaction_id": "20580e50-1b32-40a6-aa46-ac8e795b3zas",
  "transaction_reference": "2a446ee4-8d3a-40ed-b33f-6430df69e7bf",
  "merchant_reference": "ORDER-1001",
  "transaction_status": "SUCCESSFUL",
  "transaction_fee": 0.4,
  "transaction_amount_without_fee": 19.6,
  "transaction_amount": 20.0,
  "transaction_currency": "CAD",
  "customer_id": "9d4c4ec5-59ea-4130-bf8a-6a5edec401ee",
  "recipient": {
    "account_number": null,
    "account_name": "Oluwatobi Ishola",
    "bank_name": null,
    "amount": 19.6
  },
  "extras": {
    "interac_instruction": {
      "question": "What is the PIN?",
      "answer": 1234
    }
  },
  "event_id": "9d46b957-61b2-4b27-85cf-059069893237",
  "type": "payout"
}

The merchant should use the final SUCCESSFUL payout event to mark the transaction as completed and reconcile the payout.

Transaction Information

Both collection and payout webhook events provide transaction information that merchants can use for reconciliation.

For collection transactions, the webhook also provides information about the collection email and the source of the payment.

For payout transactions, the webhook provides recipient information and, where applicable, Interac instructions.

Webhook Handling

Merchants should configure their notification URL before processing transactions so LedgerBlock can send transaction updates.

Your webhook handler should:

1. Receive the webhook event.
2. Verify the webhook request.
3. Identify the transaction using the transaction reference or transaction ID.
4. Check the transaction status.
5. Update the corresponding transaction in the merchant's system.
6. Return a successful response after processing the event.

For payouts, do not mark a transaction as completed when the status is only PENDING. Wait for the final successful notification.

Collection and Payout at a Glance