Interac e-Transfer

The Paysafe Payments API supports Interac e-Transfer as a Payment Instrument. You can process Interac e-Transfer payments using the Payments API.

  1. Transaction Types
  2. Typical Scenarios
  3. API Contracts
  4. Appendix

Transaction Types

Interac e-Transfer supports below two transactions:

  • Payments

    It is used to transfer money from customer's bank account to merchant account. Post successful payments, merchant credits the customer's wallet. Request money interac flow is implemented to allow customers to deposit money. Merchant will be the requestor of money and customer will be the approver.

  • Withdrawal

    It is used to transfer money from merchant account to customer's bank account. Send money interac flow is implemented to allow customers to withdraw money.

Typical Scenarios

Payment

When you want to process an Interac payment request, do the following:

  1. Create a Payment Handle with the transactionType parameter set to PAYMENT and the paymentType parameter set to INTERAC_ETRANSFER
    • Post : paymenthub/v1/paymenthandles
  2. Since the customer has to complete payment by selecting bank account on interac page, Paysafe returns a response with the following:
    • The action parameter is set to REDIRECT
    • A redirect_payment link points to the Interac redirect URL
  3. Redirect the customer to the Interac redirect URL.
    • On redirecting the customer to redirection link, status of the Payment Handle becomes PAYABLE and you will be notified with webhook for PAYMENT_HANDLE_PAYABLE event
    • On redirection page, customer selects the bank, provides credentials, and accepts the request of transfer-money.
  4. Use the paymentHandleToken returned in the response to process the Payment request via Payments API using the private key. You must initiate a POST request to the endpoint:
    • Post : paymenthub/v1/payments
  5. Once the customer successfully completes the payment, the merchant will receive SETTLEMENT_COMPLETED/ PAYMENT_COMPLETED event (Since this is settlewithauth= true, we can assume that both are same) . Once you receive these events you can safely credit the amount to customers account/ ship the goods.

APIs to use: Payment Handles + Payments

Withdrawal

When you want to process a Interac withdrawal request, do the following:

  1. Ask customer the email ID to initiate a withdrawal.

  2. Check if the email ID is registered for Auto deposit. You can use Verification API to do the same. You get Auto Deposit status and max transferrable amount in response.

  3. Depending on auto-deposit registration status, below mentioned steps need to be implemented.

Registered for Auto Deposit Flow

  1. Create a Payment Handle with the transactionType parameter set to STANDALONE_CREDIT and the paymentType parameter set to INTERAC_ETRANSFER.

  2. This Payment Handle should immediately have the status of PAYABLE.

  3. Use the paymentHandleToken returned in the response to process the Withdrawal request via Standalone Credit API using the private key. You must initiate a POST request to the endpoint:

    • Post: /paymenthub/v1/standalonecredits
  4. Once the Withdrawal request is successfully completed, the status of the withdrawal (STANDALONE_CREDIT) will be in PROCESSING state. And funds are transferred to the customer's account upon which the status will be changed to COMPLETED.

Not registered for Auto Deposit Flow

  1. For non Auto deposit withdrawals, you have to pass the security question and answer to the API. This can be done either by asking customer to pass question & answer or you can have preconfigured question & answer (and share this with customer).
  2. Create a Payment Handle with the transactionType parameter set to STANDALONE_CREDIT, the paymentType parameter set to INTERAC_ETRANSFER and pass the set of question & answer in the API.
  3. This Payment Handle should immediately have the status of PAYABLE.
  4. Use the paymentHandleToken returned in the response to process the Withdrawal request via Standalone Credit API using the private key. You must initiate a POST request to the endpoint:
    • Post: /paymenthub/v1/standalonecredits
  5. Customer will receive the link via email and customer has to complete the process of answering the question via interac/bank page.
  6. You will receive webhook for the "SA_CREDIT_COMPLETED" event and once funds are credited into customer account.

APIs to use: Payment Handles for Verification + Verification +Payment handle for Standalone Credits + Standalone Credits

API Contracts

Payments

Payment Handle Request example

You have to pass Interac eTransfer object in the payment Handle request:

"interacEtransfer": {
        "consumerId": "krissjames.12@gmail.com",
        "type":"EMAIL"
    }

Parameter

Type Mandatory Description
consumerId string true Customer/end user email id or phone number, from whom money has to be collected.
true string false Default: EMAIL To pass mobile number we have to specify the type as PHONE.

Payment Handle Request example

{
   "merchantRefNum":"118a0bb7-7239-43ea-b6a8-1dd8b5b765ad",
   "transactionType":"PAYMENT",
   "paymentType":"INTERAC_ETRANSFER",
   "amount":"544",
   "currencyCode":"CAD",
   "customerIp":"172.0.0.1",
   "interacEtransfer":{
      "consumerId":"madhubaddam@paysafe.com",
      "type":"EMAIL"
   },
   "billingDetails":{
      "street1":"100 Queen",
      "street2":"Unit 201",
      "city":"Melbourne",
      "state":"Victoria",
      "zip":"3000",
      "country":"AU"
   },
   "profile":{
      "firstName":"Madhu",
      "lastName":"Baddam",
      "email":"madhu@paysafe.com"
   },
   "returnLinks":[
      {
         "rel":"default",
         "href":"http://www.amazon.in"
      },
      {
         "rel":"on_failed",
         "href":"http://www.costco.ca"
      },
      {
         "rel":"on_cancelled",
         "href":"http://www.bestbuy.ca"
      }
   ]
}

Payment Handle Response example

{
  "id": "514b4cf1-8891-445d-9b58-e50ae02d8c3c",
  "paymentType": "INTERAC_ETRANSFER",
  "paymentHandleToken": "PHEkR6gInY2NM05X",
  "merchantRefNum": "afca4603-a9d7-4010-866f-f5a7204f36fd",
  "currencyCode": "CAD",
  "txnTime": "2021-10-06T13:15:22Z",
  "billingDetails": {
    "street": "100 Queen",
    "street2": "Unit 201",
    "city": "Melbourne",
    "zip": "3000",
    "state": "Victoria",
    "country": "AU"
  },
  "customerIp": "172.0.0.1",
  "status": "INITIATED",
  "links": [
    {
      "rel": "redirect_payment",
      "href": "https://api.qa.paysafe.com/alternatepayments/v1/redirect?accountId=1018169820&paymentHandleId=514b4cf1-8891-445d-9b58-e50ae02d8c3c&token=eyJhbGciOiJIUzI1NiJ9.eyJhY2QiOiIxMDE4MTY5ODIwIiwicHlkIjoiNTE0YjRjZjEtODg5MS00NDVkLTliNTgtZTUwYWUwMmQ4YzNjIiwiZXhwIjoxNjMzNTI3OTIzfQ.DvMBbCsxckQhKwsUSpHEAh9IkpGuIyaPFsa4heWUxNE"
    }
  ],
  "liveMode": false,
  "simulator": "EXTERNAL",
  "usage": "SINGLE_USE",
  "action": "REDIRECT",
  "executionMode": "SYNCHRONOUS",
  "amount": 544,
  "timeToLiveSeconds": 899,
  "gatewayResponse": {
    "id": "Gs27oxf1xsoUJRrB",
    "processor": "INTERAC",
    "status": "AVAILABLE"
  },
  "returnLinks": [
    {
      "rel": "on_failed",
      "href": "http://www.costco.ca"
    },
    {
      "rel": "default",
      "href": "http://www.amazon.in"
    },
    {
      "rel": "on_cancelled",
      "href": "http://www.bestbuy.ca"
    }
  ],
  "transactionType": "PAYMENT",
  "gatewayReconciliationId": "e17a0f2f-ab84-4fe0-a405-a6ef104120dc",
  "updatedTime": "2021-10-06T13:15:23Z",
  "statusTime": "2021-10-06T13:15:23Z",
  "interacEtransfer": {
    "consumerId": "madhu.baddam@paysafe.com",
    "type": "EMAIL"
  },
  "profile": {
    "firstName": "Madhu",
    "lastName": "Baddam",
    "email": "madhu@paysafe.com"
  }
}

To know more about each parameter, you can visit Payment Handles.

Payments Request example

{
  "merchantRefNum": "b9405251-5ede-4439-b844-73ff553144a5",
  "amount": "546",
  "currencyCode": "CAD",
  "settleWithAuth": true,
  "paymentHandleToken": "PHEkR6gInY2NM05X"
}

Payments Response example

{
  "id": "568530f0-262a-453f-b681-1088195d9439",
  "paymentType": "INTERAC_ETRANSFER",
  "paymentHandleToken": "PHEkR6gInY2NM05X",
  "merchantRefNum": "b9405251-5ede-4439-b844-73ff553144a5",
  "currencyCode": "CAD",
  "settleWithAuth": true,
  "dupCheck": true,
  "txnTime": "2021-10-06T13:18:58Z",
  "billingDetails": {
    "street1": "100 Queen",
    "street2": "Unit 201",
    "city": "Melbourne",
    "zip": "3000",
    "state": "Victoria",
    "country": "AU"
  },
  "status": "PROCESSING",
  "gatewayReconciliationId": "Io27oxf1xsqOrDIe",
  "amount": 546,
  "availableToRefund": 0,
  "consumerIp": "172.0.0.1",
  "liveMode": false,
  "simulator": "EXTERNAL",
  "updatedTime": "2021-10-06T13:20:18Z",
  "statusTime": "2021-10-06T13:20:18Z",
  "gatewayResponse": {
    "id": "Io27oxf1xsqOrDIe",
    "processor": "INTERAC",
    "status": "AVAILABLE"
  },
  "availableToSettle": 0,
  "interacEtransfer": {
    "consumerId": "madhu.baddam@paysafe.com",
    "type": "EMAIL"
  },
  "profile": {
    "firstName": "Madhu",
    "lastName": "Baddam",
    "email": "madhu@paysafe.com"
  },
  "settlements": {
    "amount": 546,
    "txnTime": "2021-10-06T13:18:58.000+0000",
    "availableToRefund": 0,
    "merchantRefNum": "b9405251-5ede-4439-b844-73ff553144a5",
    "id": "568530f0-262a-453f-b681-1088195d9439",
    "status": "PROCESSING"
  }
}

To know more about each parameter, you can visit Payments.

Verification

Payment Handle Request example

{
  "merchantRefNum": "8e103c2d-891c-4b42-b3ba-28aaf371ad25",
  "transactionType": "VERIFICATION",
  "paymentType": "INTERAC_ETRANSFER",
  "amount": 543,
  "currencyCode": "CAD",
  "dupCheck": true,
  "liveMode": true,
  "interacEtransfer": {
    "consumerId": "madhu@paysafe.com"
  },
  "profile": {
    "firstName": "Madhu",
    "lastName": "Baddam",
    "email": "madhu.baddam@paysafe.com"
  }
}

Payment Handle Response example

{
  "id": "cbd5a3a4-fbba-4d09-a666-662ff13c1628",
  "paymentType": "INTERAC_ETRANSFER",
  "paymentHandleToken": "PHd0GFCqwJqu9YkV",
  "merchantRefNum": "0a8c7252-1ba6-4e89-b666-3f11ed3ffb20",
  "currencyCode": "CAD",
  "txnTime": "2021-10-06T13:43:18Z",
  "status": "PAYABLE",
  "liveMode": false,
  "simulator": "EXTERNAL",
  "action": "NONE",
  "amount": 543,
  "timeToLiveSeconds": 899,
  "gatewayResponse": {
    "processor": "INTERAC"
  },
  "transactionType": "VERIFICATION",
  "updatedTime": "2021-10-06T13:43:18Z",
  "statusTime": "2021-10-06T13:43:18Z",
  "interacEtransfer": {
    "consumerId": "madhu@paysafe.com"
  },
  "profile": {
    "firstName": "Madhu",
    "lastName": "Baddam",
    "email": "madhu.baddam@paysafe.com"
  }
}

To know more about each parameter, you can visit Payment Handles.

Verification Request example

{
  "paymentHandleToken": "PHd0GFCqwJqu9YkV",
  "currencyCode": "CAD",
  "merchantRefNum": "0a8c7252-1ba6-4e89-b666-3f11ed3ffb20",
  "amount": "543"
}

Verification Response example

{
  "id": "d19ca286-6497-4dc5-bcd6-c1b80431800a",
  "paymentType": "INTERAC_ETRANSFER",
  "paymentHandleToken": "PHd0GFCqwJqu9YkV",
  "merchantRefNum": "ab428d69-1135-4db7-9305-999605b48814​​​",
  "currencyCode": "CAD",
  "txnTime": "2021-10-06T09:40:52Z",
  "billingDetails": {
    "street1": "100 Queen Street West",
    "street2": "stree 2",
    "city": "Toronto",
    "zip": "M5H 2N2",
    "state": "CA",
    "country": "NL"
  },
  "status": "COMPLETED",
  "amount": 543,
  "updatedTime": "2021-10-06T09:40:52Z",
  "statusTime": "2021-10-06T09:40:52Z",
  "liveMode": false,
  "simulator": "EXTERNAL",
  "gatewayResponse": {
    "processor": "INTERAC"
  },
  "interacEtransfer": {
    "consumerId": "madhu@paysafe.com",
    "maxAmount": 500000,
    "transferType": "ALIAS_REGULAR"
  },
  "profile": {
    "firstName": "Madhu",
    "lastName": "Baddam",
    "email": "madhu.baddam@paysafe.com"
  }
}

Withdrawal or Standalone Credit

Payment Handle Request example

{
  "merchantRefNum": "0ec1bcb3-2994-4440-acd9-1d71dd0f0988",
  "transactionType": "STANDALONE_CREDIT",
  "paymentType": "INTERAC_ETRANSFER",
  "amount": 500,
  "currencyCode": "CAD",
  "customerIp": "172.0.0.1",
  "interacEtransfer": {
    "consumerId": "madhu@paysafe.com",
    "question": "what is your name",
    "answer": "MadhuBaddam"
  },
  "profile": {
    "firstName": "Madhu",
    "lastName": "Baddam",
    "email": "madhu.baddam@paysafe.com",
    "phone": "12345678"
  },
  "browserDetails": {
    "userCookie": "testusercoockie"
  }
}

Payment Handle Response example

{
  "id": "9129cf41-c403-455f-b5b2-6cd76cbeaed7",
  "paymentType": "INTERAC_ETRANSFER",
  "paymentHandleToken": "PH6grPCguAtRInwc",
  "merchantRefNum": "4f55a9f1-f19d-4bc7-b52f-7ef7133995a1",
  "currencyCode": "CAD",
  "txnTime": "2021-10-06T13:37:58Z",
  "customerIp": "172.0.0.1",
  "status": "PAYABLE",
  "liveMode": false,
  "simulator": "EXTERNAL",
  "action": "NONE",
  "amount": 500,
  "timeToLiveSeconds": 899,
  "gatewayResponse": {
    "id": "Yd27oxf1xt1HwRRi",
    "processor": "INTERAC",
    "status": "ACCEPTED"
  },
  "transactionType": "STANDALONE_CREDIT",
  "gatewayReconciliationId": "14a92cf4-011a-4598-8cf0-3eb926b1abb8",
  "updatedTime": "2021-10-06T13:37:59Z",
  "statusTime": "2021-10-06T13:37:59Z",
  "browserDetails": {
    "userCookie": "testusercoockie"
  },
  "interacEtransfer": {
    "consumerId": "madhu@paysafe.com",
    "question": "what is your name",
    "answer": "MadhuBaddam",
    "maxAmount": 500000,
    "transferType": "ALIAS_REGULAR"
  },
  "profile": {
    "firstName": "Madhu",
    "lastName": "Baddam",
    "email": "madhu.baddam@paysafe.com",
    "phone": "12345678"
  }
}

To know more about each parameter, you can visit Payment Handles.

Withdrawal Request example

{
  "merchantRefNum": "4f55a9f1-f19d-4bc7-b52f-7ef7133995a1",
  "amount": "500",
  "currencyCode": "CAD",
  "paymentHandleToken": "PH6grPCguAtRInwc",
  "customerIp": "172.0.0.1",
  "description": "Magazine subscription"
}

Withdrawal Response example

{
  "id": "b7759f69-b194-41ad-aab2-164432596c04",
  "paymentType": "INTERAC_ETRANSFER",
  "paymentHandleToken": "PH6grPCguAtRInwc",
  "merchantRefNum": "4f55a9f1-f19d-4bc7-b52f-7ef7133995a1",
  "currencyCode": "CAD",
  "dupCheck": true,
  "txnTime": "2021-10-06T13:38:44Z",
  "customerIp": "172.0.0.1",
  "status": "PROCESSING",
  "gatewayReconciliationId": "f58a0d95-0934-46dd-bcd3-96c4990be3f3",
  "amount": 500,
  "liveMode": false,
  "simulator": "EXTERNAL",
  "updatedTime": "2021-10-06T13:38:44Z",
  "statusTime": "2021-10-06T13:38:44Z",
  "gatewayResponse": {
    "id": "Yd27oxf1xt1HwRRi",
    "processor": "INTERAC",
    "status": "AVAILABLE"
  },
  "interacEtransfer": {
    "consumerId": "madhu@paysafe.com",
    "question": "what is your name",
    "answer": "MadhuBaddam",
    "maxAmount": 500000,
    "transferType": "ALIAS_REGULAR"
  },
  "profile": {
    "firstName": "Madhu",
    "lastName": "Baddam",
    "email": "madhu.baddam@paysafe.com",
    "phone": "12345678"
  }
}

To know more about each parameter, you can visit Standalone Credits.

Appendix

Payment Handle

A Payment Handle represents tokenized information about the payment method that you set up for your customer. Once the Payment Handle is created, you can then include the paymentHandleToken returned in the Payment Handle request-response in a new payment request.

Payments Flow:

  1. Create Payment Handle API request.
  2. In Payment Handle API response, you will get redirect link and paymentHandleToken.
    • A Payment Handle can be used in a payment request only if it has the status of PAYABLE.
    • PaymentHandleToken expires in 899 seconds
  3. Redirect user to the redirect link, provided in Payment handle response.
    • You will receive a Webhook with paymentHandleToken status as "PAYABLE"
  4. Wait for 10 mins and let user complete the transaction on Interac page.
    Interac doesn't redirect the customer to Merchant page once customer completes the payment. Hence you are advised to show a message to customer while redirecting to Interac page. You may show a message 'Please close the tab and come back to this page after completing the payment'. In addition, you can have listeners on tab close (on redirection Interac page) and once tab close event is received, you can do a GET API call to pull the status.
    • To find out what user has done on interac page (closed or cancelled or completed the transaction), you can do a GET API Call.
  5. Make POST "/payments" API call only when the paymentHandleToken status is "PAYABLE"
    • Customer has completed the transaction:
      • If Interac has notified Paysafe then you will receive "status" as COMPLETED in response and also you will receive PAYMENT_COMPLETED webhook.
      • If Interac has not notified Paysafe then you will receive "status" as PROCESSING in response

        • Interac takes max 30 mins to notify Paysafe after user completes the transaction on bank page.
        • Once POST "/payments" API call is made, status of paymentHandleToken changes from "PAYABLE" to "COMPLETED".

    • Customer has declined or not completed the transaction:
      • Your payment handle becomes Completed and Payment status will be in Processing.
      • 2 days later, we will mark the transaction as Failed and you will receive "PAYMENT_FAILED" notification.

      • If merchant does not make /payments call within 899 seconds for a paymentHandleToken:

        • Customer has completed the transaction via bankpage then Paysafe will complete payment on merchant's behalf and merchant will receive - a) PAYMENT_COMPLETED or b) PAYMENT_PROCESSING followed by PAYMENT_COMPLETED.
        • Customer has declined or not completed the transaction, we will fail the transaction and you will receive PAYMENT_HANDLE_FAILED event.

Payment Flow

Withdrawal Flow

Withdrawal flow can be implement in two ways:

  • Verification API + Standalone Credit API.
    • In this model, you will get to know max withdrawal limit and whether user has registered for Auto deposit or not and accordingly you can decide the user experience.
  • Standalone Credit API.

    Verification API

  1. Create Payment Handle API request with transactionType parameter set to VERIFICATION and the paymentType parameter set to INTERAC_ETRANSFER.
  2. This Payment Handle should immediately have the status of PAYABLE.
  3. Make POST "/verifications" API call with "PAYABLE" paymentHandleToken.
    • You will receive Auto-deposit status and max limit.

    Standalone Credit API

  1. Create Payment Handle API request with transactionType parameter set to STANDALONE_CREDIT and the paymentType parameter set to INTERAC_ETRANSFER.

  2. This Payment Handle status will either be PAYABLE or FAILED.
  3. Make POST "/standalonecredits" API call only if paymentHandleToken is "PAYABLE"
    • In Auto-deposit flow, money gets directly credited into user account. You will receive SA_CREDIT_PROCESSING immediately and SA_CREDIT_COMPLETED on T+1
    • If it is non-Auto-deposit flow, you will receive status as "PROCESSING"
      • Once customer completes the transaction within 30 days then you will receive the webhook SA_CREDIT_COMPLETED.
    • PaymentHandleToken expires in 899 seconds.
    • If merchant does not send /standalonecredits call within 899 seconds for a paymentHandleToken then paymentHandleToken will expire and you will received PAYMENT_HANDLE_EXPIRED webhook.

Withdrawal Flow

Webhooks

  • PAYMENT_HANDLE_PAYABLE - On receiving this webhook, merchant has to initiate the paymenthub/v1/payments call
  • PAYMENT_COMPLETED/SETTLEMENT_COMPLETED - The payment was completed successfully.
  • PAYMENT_PROCESSING: The payment in is in progress. For some cases it may be waiting an action by the customer or the merchant.
  • And the below optional webhooks
    • PAYMENT_HANDLE_EXPIRED - This webhook is sent when the customer has not completed the payment on the bank page within the paymentHandle token TTL time. So the merchant can close the transaction as not completed.
    • PAYMENT_HANDLE_COMPLETED - The payment handle token is used before expiry.
    • PAYMENT_FAILED - The payment has failed and the downstream PSP has returned an error (http status 402).
    • PAYMENT_ERRORED - The payment has an error (non http status 402 error).
    • SETTLEMENT_FAILED - Consume this to know when the Settlement status becomes FAILED.
    • SETTLEMENT_ERRORED - Consume this to know when the Settlement status becomes ERRORED.
Did you find this page useful?