Skip to content

On-File Transactions Overview

PayWithMyBank can be used to allow a user to store an Online Banking account on file. You can then use that on file account to initiate Payments and Withdrawals in your system as needed. There are 5 pieces required for this use case.

  1. Create a Bank Authorization using Online Banking. Implement the PayWithMyBank Online Banking interface to allow a User to authenticate with their Bank and authorize you to use that bank for payment transactions. This returns a transactionId and splitToken that you will store on the Users account in your system as a method of payment.
  2. Display Bank or User PII from PayWithMyBank. With a valid transactionId, you can use the PayWithMyBank Get Transaction and Get Financial Institution User API to retrieve information from the Users selected bank to display or pre-fill fields on your site or application.
  3. Create a Transaction from the Bank Authorization. When the User requests to make a payment, you can use the PayWithMyBank Capture API, passing the previously obtained transactionId, splitToken, amount, and merchantReference. When a User requests to make a withdrawal, you can use the PayWithMyBank Deposit API, passing the previously obtained transactionId, amount, and merchantReference.
  4. Handle Event Notifications. The payment transaction returns a PENDING or ERROR response. Implement PayWithMyBank Event Notifications to receive transaction status updates in real time and message your customers accordingly.
  5. Refresh a Bank Authorization using Online Banking. A transactionId can become invalidated and a splitToken can become expired. If that happens, you'll want to send the User back to Online Banking to select a new Bank or refresh their Bank Authorization.

Integration Options and Branding Requirements

PayWithMyBank offers two types of Integration Options for its Online Banking solution - Select Bank Widget and PayWithMyBank Lightbox.

The Select Bank Widget is show in-line on your page (outlined here in red) and shows the most popular bank accounts. Clicking one of the buttons on the Widget opens the PayWithMyBank Lightbox, where the User can sign in and authorize their account for use..

Select Bank Widget example

Alternately, you can trigger the PayWithMyBank Lightbox using your own button. The PayWithMyBank Lightbox opens over your existing page.

PayWithMyBank Lightbox example

In addition to determining if the Select Bank Widget or opening the PayWithMyBank Lightbox directly is the best option for you, PayWithMyBank has a number of Branding Requirements to consider. If you have any questions or specific requirements, please work with your PayWithMyBank team or contact techsupport@paywithmybank.com.

Create a Bank Authorization using Online Banking

The PayWithMyBank Online Banking Payment service enables end users to pay by signing into their online banking interface within your website. The PayWithMyBank User interaction can be completed in 3 simple steps.

zoomify

  1. The User selects Online Banking as a payment method on your website, which either displays the PayWithMyBank Widget (which then launches the PayWithMyBank Lightbox) or launches the PayWithMyBank Lightbox directly.
  2. From the PayWithMyBank Lightbox, the user authenticates with their bank and selects they account they wish to use for the transaction.
  3. Before returning the User to your returnUrl, we will send an Event Notification to your listener with the transactionId and splitToken. You'll store the Users account on file at this point and return a successful response to the PayWithMyBank Notification system. The User is then returned to your returnUrl with the transactionId, at which point you can continue your flow as usual.

To integrate the PayWithMyBank Online Banking Payment service into your website or app, you will need to do the following:

Integrate the PayWithMyBank SDK into your flow.

PayWithMyBank offers 3 SDK's: JavaScript, iOS, and Android. The SDK has 2 main methods: selectBankWidget and establish. The methods accept 2 parameters, options and establishData. The options parameter is optional and can be used to control pieces of the Lightbox experience. The establishData parameter is used pass transaction parameters to PayWithMyBank that are used when establishing the Bank Authorization transaction.

The following examples are using the JavaScript SDK

1. To load the SDK on the page, use the following JavaScript tag (replacing {accessId} with the Access Id provided to you by PayWithMyBank):

1
<script src="https://sandbox.paywithmybank.com/start/scripts/paywithmybank.js?accessId={accessId}"> </script>

2. To provide optional PayWithMyBank configuration options, create a PayWithMyBankOptions object:

1
2
3
4
5
var PayWithMyBankOptions = {
  closeButton: false,
  dragAndDrop: false,
  widgetContainerId: "widget-container-id" //Page element container for the widget
};

For details on the PayWithMyBank configuration options, refer to the SDK Specification.

3. To provide the transaction details to the SDK, create an establishData object:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
var establishData = {
  accessId: {accessId},
  requestSignature: {requestSignature},
  merchantId: {merchantId},
  description: 'transaction description',
  currency: 'USD',
  amount: '0.00',
  merchantReference: 'merchant reference',
  paymentType: 'Deferred',
  returnUrl: 'https://merchant.com/paywithmybank/return',
  cancelUrl: 'https://merchant.com/paywithmybank/cancel'        
};

Warning

Do not pass Consumer PII (name, email address, etc) in the description field. You can pass Consumer PII in the customer object.

Tip

Ensure you're securing your call by including the requestSignature parameter.

4. Finally, call the PayWithMyBank SDK's establish or selectBankWidget function:

Select Bank Widget

1
PayWithMyBank.selectBankWidget(establishData, PayWithMyBankOptions);

Establish

1
PayWithMyBank.establish(establishData, PayWithMyBankOptions);

The following is a full HTML page using the above example.

Info

You'll want to replace {accessId} and {merchantId} with the values provided to you by PayWithMyBank

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
<html>
  <head>
    <meta name="viewport" content="width=device-width, initial-scale=1" />
    <script>
      var PayWithMyBankOptions = {
        closeButton: false,
        dragAndDrop: true,
        widgetContainerId: 'widget',
      };
    </script>
    <script src="https://sandbox.paywithmybank.com/start/scripts/paywithmybank.js?accessId={accessId}"></script>
  </head>
  <body style="margin: 0;">
    <div id="widget"></div>
  </body>
   <script>
    var establishData = {
      accessId: {accessId},
      merchantId: {merchantId},
      merchantReference: {merchantReference},
      description: 'transaction description',
      currency: 'USD',
      amount: '0.00',
      merchantReference: 'merchant reference',
      paymentType: 'Deferred',
      returnUrl: 'https://merchant.com/paywithmybank/return',
      cancelUrl: 'https://merchant.com/paywithmybank/cancel'        
    };
    PayWithMyBank.selectBankWidget(establishData, PayWithMyBankOptions);
  </script>
</html>

Receive the Split Token

Before the User is returned via the returnUrl, PayWithMyBank will send you an Event Notification that contains the objectId (transactionId), splitToken, and other related fields. Once you receive the Notification, save the payment method to the Users account and return a 200 OK response to the Notification server.

Info

PayWithMyBank will not redirect the User to your returnUrl until we either receive a response (success or failure) or the request times out after 3 seconds.

Warning

If you fail to receive or store the splitToken, it can not be resent. You can (and should) attempt a Capture API call without it.

Example Authorization notification

1
merchantId=1002463580&merchantReference=123123&paymentType=2&transactionType=1&eventId=1002596466&eventType=Authorize&objectId=1002596444&objectType=Transaction&message=&timeZone=Etc%2FUTC&createdAt=1556311335754&accessId=ASs345fldAHJPTHXcaK&fiCode=051000017&status=2&statusMessage=Authorized&splitToken=CLnEidulLRABGHAgACo4dO9iOB%2BMPGWJheNrxkZGZBJatkOVU0228urTXrz8xzqqyXRr7s1ZJFsVlZBuug48VW7kMq0BprQ%3D

Please refer to Event Notifications for more information on handling Event Notifications.

Handle the redirect

If the User cancels the request, PayWithMyBank will direct the User to your provided cancelUrl. If the User successfully authorizes the request, PayWithMyBank will direct the User to your provided returnUrl.

Once you get a successful redirect to your returnUrl, check to ensure you've received the Split Token and added the account on file. If you have not, add the account on file with the provided transactionId and a blank or null splitToken.

Example Cancel URL

1
https://merchant.com/paywithmybank/cancel?transactionId=1002632909&transactionType=1&merchantReference=123123&status=7&payment.paymentType=2&panel=1&payment.paymentProviderTransaction.status=UC01&requestSignature=tp%2B%2B%2BI5nM%2BSeOT8TQKLGvfaEGcs%3D

Example Return URL

1
https://merchant.com/paywithmybank/return?transactionId=1002633191&transactionType=1&merchantReference=123123&status=2&payment.paymentType=2&payment.paymentProvider.type=1&payment.account.verified=false&panel=1&requestSignature=b7yr%2F3qOupPa1B7VeI32PhGQ7C8%3D

Redirect URL Parameters

PayWithMyBank will append the following parameters to your returnUrl or cancelUrl:

Parameter Definition
transactionId A unique PayWithMyBank transaction identifier. (15 characters)
transactionType Will always be 1 in this use case.
merchantReference A specific merchant reference for this cancelation. For example, this could be your order number or session id.
status Integer value representing the Transaction Status. This will either be 2 (Authorized) or 7 (Cancelled). Refer to Transaction Status Values in the SDK Specification for a complete list of values and their definitions.
payment.paymentType Will always be 2 (Deferred) in this use case.
payment.paymentProvider.type Will always be 1 (Easy Online Debit / Online Banking) in this use case.
payment.account.verified ...
panel Integer value representing the PayWithMyBank screen the user exited the flow on. Refer to Panel Values in the SDK Specification for a complete list of values and their definitions.
payment.paymentProviderTransaction.status Integer value representing the Payment Provider Transaction Status of the transaction. Refer to Payment Provider Transaction Status in the SDK Specification for a complete list of values and their definitions.
requestSignature This is a signature that you can calculate to ensure the request you receive is coming from PayWithMyBank. See Validate the Redirect Signature for more information.

Display Bank or User PII from PayWithMyBank

With a valid Bank Authorization, you can use the PayWithMyBank Get Transaction API to retrieve information about the Users bank account that can be displayed in their account on your system. You can also use the PayWithMyBank Get User API to retrieve personal information (name, address, email, etc) that can be used to pre-fill fields on your flow or verify information you have already collected from the User.

Use Get Transaction to display Bank information

Calling the Get Transaction API allows you to get transaction details and current status of a transaction. You call the Get Transaction API by executing a GET request to the Get Transaction endpoint (/transactions/{transactionId}), where {transactionId} is the Bank Account Authorization transaction id.

Example Get Transaction request

1
https://sandbox.paywithmybank.com/api/v1/transactions/1002548448

The Get Transaction call returns a JSON response with Bank Account data that you can use in your application. Relevant fields from the response include:

  • payment.account.name: Name (friendly identifier) of the Users Bank Account.
  • payment.account.type: Type of Account selected (Checking or Savings).
  • payment.account.accountNumber: Last 4 digits of the Bank Account number selected.
  • payment.paymentProvider.paymentProviderId: PayWithMyBank Identifier for the Bank selected. You can use this identifier to display the Bank logo to the User.
  • payment.paymentProvider.name: Name of the Bank the User selected.
  • statusMessage: Status of the transaction. Should be Authorized.

You can then use this information to display the selected Payment Method to your user.

Example Payment Method

Example Get Transaction response (abbreviated)

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
{
  "transaction": {
    "transactionId": "1002580075",
    "payment": {
      "account": {
        "name": "Adv Plus Banking",
        "type": 1,
        "accountNumber": "3254",
      },
      "paymentProvider": {
        "paymentProviderId": "051000017",
        "name": "Bank of America"
      },
    },
    "statusMessage": "Authorized",
  }
}

Please refer to the Get Transaction definition in the API Reference for more information.

Use Get User Information to retrieve, validate, and display User information

Calling the Get User API allows you to get the personal information (Account Owner name, address, phone, and email) of the User from their selected Bank Account. You call the Get User API by executing a GET request to the Get Transaction endpoint (/transactions/{transactionId}/payment/paymentProvider/user), where {transactionId} is the Bank Account Authorization transaction id.

Example Get User request

1
https://sandbox.paywithmybank.com/api/v1/transactions/1002548448/payment/paymentProvider/user

The Get User call returns a JSON response with User data that you can use in your application. Relevant fields from the response include:

  • name: Name(s) associated with the Users Bank Account.
  • address: Address(es) associated with the Users Bank Account.
  • phone: Phone Number(s) associated with the Users Bank Account.
  • email: Email Address(es) associated with the Users Bank Account.

You can then use this information to pre-fill or display the Users information in your flow. You can also use this information to validate the personal information the User may have previously provided in your flow.

Example User Information

Example Get User response (abbreviated)

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
{
  "user": {
    "name": [
      "John Smith",
      "Mary Smith"
    ],
    "address": [
      {
      "address1": "2000 Broadway Street",
      "address2": "",
      "city": "Redwood City",
      "state": "CA",
      "zip": "94063",
      "country": "US"
      },
      {
      "address1": "105 Alternate1 Street",
      "address2": "#401",
      "city": "Redmond",
      "state": "WA",
      "zip": "98052",
      "country": "US"
      },
    ],
    "phone": [
      "2145553434"
    ],
    "email": [
      "jsmith@email.com"
    ],
  }
}

Please refer to the Get User definition in the API Reference for more information.

Create a Transaction from the Bank Authorization

Once you have a valid Bank Authorization, you can use the PayWithMyBank Transaction API's to initiate Payments and Withdrawals.

Use the Preauthorization API to create a preauthorization

The Preauthorization API allows the merchant to determine if a given amount of funds would be available for a given window. You call the Preauthorize API by executing a POST request to the Preauthorize endpoint (/transactions/{transactionId}/capture/preAuth), where {transactionId} is the Bank Account Authorization transaction id.

Info

Any amount captured during the specified window against an approved preauthorization transaction will be guaranteed. Any captures after the preauthorization window will be treated as a normal Capture request (where balance check and risk analysis will need to be passed in order for the transaction to be guaranteed).

In order to execute the Preauthorization API request, ensure you pass in the following fields:

  • splitToken: Split Token you received from the Bank Authorization Notification.
  • amount: Amount to be authorized.
  • merchantReference: Your specific identifier for this transaction. For example, this could be your Order Number or the same merchant reference value used in the Bank Authorization transaction. This will appear in Event Notifications and Reports.
  • window: Interval (in hours) that the preauthorization will be valid for.

Example Preauthorization request

1
splitToken=CPSrlZajLRABGGAgACowghLbNU6b7dM1S95Q1Pu1FbQ87yCE%2Ba%2BL0muWQxno%2Fz%2F%2F5Sc8TJ7JCBUPCXTkG4P4&amount=10.00&merchantReference=9ce392f7-f99b-41e9-9028-3f33c8b0a46e&window=72

If the preauthorization is approved, the Preauthorization API returns a transactionId that can be passed to the Capture API to capture funds.

Example Preauthorization response (abbreviated)

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
{
    "transaction": {
        "transactionId": "1001001894",
        "transactionType": 2,
        "currency": "USD",
        "amount": "2.10",
        "status": 2,
        "statusMessage": "Authorized",
        "ip": "192.168.100.147",
        "createdAt": 1449176555750,
        "updatedAt": 1449176576137,
        "merchantReference": "BE3C26BC3F713AF8",
        "recordVersion": 3,
        "payment": {
            "paymentId": "1001001891",
            "paymentType": 1,
            "merchant": {
                "merchantId": "110005502"
            },
            "merchantReference": "BE3C26BC3F713AF8",
            "fingerprint": "eaGRmtHdk23hA7U2zB5TmDAJjDE=",
            "verification": {
                "status": 3,
                "mode": 3,
                "verifyCustomer": false
            },
            "account": {
                "name": "Demo Checking Account",
                "type": -1,
                "profile": -1,
                "accountNumber": "6576",
                "token": "KSDF23KL6576",
                "verified": true,
                "verification": {
                    "type": 2
                },
                "source": 1
            },
            "description": "Merchant.com purchase #BE3C26BC3F713AF8",
            "returnUrl": "https://merchant.com/instant/receipt",
            "cancelUrl": "https://merchant.com/instant/cancel",
            "currency": "USD",
            "amount": "2.10",
            "paymentProvider": {
                "paymentProviderId": "200005501",
                "type": 1,
                "name": "Demo Bank"
            },
            "auth": {
                "token": "1001000020",
                "status": 2,
                "message": "Authorized"
            },
            "createdAt": 1449176555744,
            "updatedAt": 1449176576159,
            "recordVersion": 5,
            "paymentFlow": 59
        }
    }
}

Please refer to the Preauthorization API definition in the API Reference for more information.

Use the Capture API to initiate Payments

The Capture API allows the merchant to request the transfer of a specific amount from the Users Bank Account given a Bank Account Authorization. You call the Capture API by executing a POST request to the Capture endpoint (/transactions/{transactionId}/capture), where {transactionId} is the Bank Account Authorization or Preauthorization transaction id.

Tip

If you would like a given Capture request applied to a previously approved Preauthorization, ensure you pass the Preauthorization transaction id as an input to the Capture API. Otherwise, the Capture request will be treated as a stand-alone Capture request.

This API returns one of the following 3 responses:

  • PENDING: The transaction was accepted and is in progress. You will be notified via Event Notification of the final disposition of the transaction. For Guaranteed Payments, that will happen within 3-10 seconds. For non-Guaranteed Payments, that will happen within 3 banking days.
  • DECLINED: The transaction was declined and the User should be message appropriately (see Error Handling).
  • ERROR: There was an error processing the request. Correct the error and try the request again (see Error Handling).

In order to execute the Capture API request, ensure you pass in the following fields:

  • splitToken: Split Token you received from the Bank Authorization Notification.
  • amount: Amount to be captured.
  • merchantReference: Your specific identifier for this transaction. For example, this could be your Order Number or the same merchant reference value used in the Bank Authorization transaction. This will appear in Event Notifications and Reports.

Tip

If you don't have a splitToken value from the notification, attempt the Capture request anyway, ommiting that field from the request. If we in fact do require the splitToken to process the request, the API will either return a an error code 200 or send an Expired Split Token notification to your endpoint (see Handling expired Split Tokens).

Example Capture request

1
splitToken=CPSrlZajLRABGGAgACowghLbNU6b7dM1S95Q1Pu1FbQ87yCE%2Ba%2BL0muWQxno%2Fz%2F%2F5Sc8TJ7JCBUPCXTkG4P4&amount=10.00&merchantReference=9ce392f7-f99b-41e9-9028-3f33c8b0a46e

If the transaction was accepted for processing, the Capture API returns a PENDING transaction. You should create a PENDING transaction in your system and message the User appropriately.

Tip

If you wish to have the User wait while the transaction with PayWithMyBank processes, you should create the pending transaction in your system, display an appropriate processing message to the user, and periodically check the status of the Users transaction in your system. Once the Event Notification is received and you update the status of the Users transaction, you can display the appropriate message. You can set a timeout of 10 seconds in your application. If you don't receive an Event Notification in your system by 10 seconds, you can execute a Cancel API and attempt the request again.

Example Capture response (abbreviated)

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
{
  "transaction": {
    "transactionId": "1002636615",
    "transactionType": 3,
    "originalTransactionId": "1002636593",
    "payment": {
      "paymentId": "1002636591",
      "paymentType": 2,
      "merchantReference": "123123",
      "account": {
        "name": "Demo Checking Account",
        "type": 1,
        "profile": 1,
        "accountNumber": "6576",
      },
      "description": "Order",
      "paymentProvider": {
        "paymentProviderId": "200005501",
        "type": 1,
        "name": "Demo Bank"
      },
      "auth": {
        "token": "15LDRA3ENERD",
        "status": 2,
        "message": "Authorized"
      },
      "authorization": "15LDRA3ENERD",
      "authorizationStatus": 2,
      "authorizationStatusMessage": "Authorized",
    },
    "currency": "USD",
    "amount": "10.00",
    "pending": "10.00",
    "paymentProviderTransaction": {
      "paymentProviderTransactionId": "ptx-ynFSa0oAiaIruwksqTtasJOX-sbx",
      "status": 10,
      "statusMessage": "Established",
      "paymentProcessor": {
        "paymentProcessorId": "100000001"
      }
    },
    "status": 1,
    "statusMessage": "Pending",
    "merchantReference": "4160903e-4ef6-49c3-a186-69b51787e638",
    "statusCode": "SW010",
  }
}

Please refer to the Capture API definition in the API Reference for more information.

Use the Deposit API to initiate Withdrawals

The Deposit API allows the merchant to request the transfer of a specific amount to the Users Bank Account given a Bank Account Authorization. You call the Deposit API by executing a POST request to the Capture endpoint (/transactions/{transactionId}/deposit), where {transactionId} is the Bank Account Authorization transaction id. This API returns one of the following 3 responses:

  • AUTHORIZED: The transaction was accepted and is in progress. You will be notified via Event Notification of the final disposition of the transaction, usually within 3 banking days.
  • DECLINED: The transaction was declined and the User should be message appropriately (see Error Handling).
  • ERROR: There was an error processing the request. Correct the error and try the request again (see Error Handling).

In order to execute the Deposit API request, ensure you pass in the following fields:

  • amount: Amount to be captured.
  • merchantReference: Your specific identifier for this transaction. For example, this could be your Order Number or the same merchant reference value used in the Bank Authorization transaction. This will appear in Event Notifications and Reports.

Example Deposit request

1
amount=25.00&merchantReference=5b83cfe7-b43c-4a6a-aec3-e483876a908a

If the transaction was accepted for processing, the Deposit API returns an AUTHORIZED transaction. You should create a PENDING transaction in your system and message the User appropriately.

Example Deposit response (abbreviated)

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
{
    "transaction": {
        "transactionId": "1002636638",
        "transactionType": 6,
        "originalTransactionId": "1002636593",
        "payment": {
            "paymentId": "1002636591",
            "paymentType": 2,
            "merchantReference": "123123",
            "account": {
                "name": "Demo Checking Account",
                "type": 1,
                "profile": 1,
                "accountNumber": "6576",
            },
            "description": "Order",
            "paymentProvider": {
                "paymentProviderId": "200005501",
                "type": 1,
                "name": "Demo Bank"
            },
            "auth": {
                "token": "15LDRA3ENERD",
                "status": 2,
                "message": "Authorized"
            },
            "authorization": "15LDRA3ENERD",
            "authorizationStatus": 2,
            "authorizationStatusMessage": "Authorized",
        },
        "currency": "USD",
        "amount": "25.00",
        "pending": "25.00",
        "paymentProviderTransaction": {
            "paymentProviderTransactionId": "ptx-6ygGA5gI7smyLVx52DY9D5oH-sbx",
            "status": 100,
            "statusMessage": "Pending",
            "paymentProcessor": {
                "paymentProcessorId": "100000001"
            }
        },
        "status": 2,
        "statusMessage": "Authorized",
        "merchantReference": "2534256c-634f-4ac6-a0dd-75d502cb1c3c",
        "statusCode": "AC100",
    }
}

Please refer to the Deposit API definition in the API Reference for more information.

Other Transaction API's

PayWithMyBank offers a number of other API's that can be used to process Payment Transactions as needed.

  • Refund API. You can use the Refund API to refund a previously completed Capture transaction.
  • Reclaim API. You can use the Reclaim API to refund a previously completed Deposit transaction.
  • Cancel API. You can use the Cancel API to cancel a previously authorized Bank Authorization or unsettled Capture transaction.

Handle Event Notifications

Notifications are event objects pushed to a Notification URL that you provide. When a notification is received, you should update the transaction record in your system and continuing processing the transaction as needed.

Warning

While PayWithMyBank makes every effort to send notifications in order, we can not guarantee that they will be received or processed by you in the order sent. Please ensure to keep the transaction state and createdAt timestamp in mind when processing events to ensure an old update isn't applied over a newer one.

When processing an Event Notification, the following fields are useful:

  • objectId: This is the transactionId of the transaction.
  • merchantReference: This is your reference id for the transaction.
  • createdAt: Timestamp that the event was created. If this before the last updated timestamp on your copy of the transaction, you should ignore this notification.
  • parentObjectId: If the transaction is related to another transaction (ie, a Capture is related to an Authorization), this will be the transactionId of the related transaction (ie, if this event is for a Capture transaction, the parentObjectId will the the transactionId for the Authorization).
  • transactionType: This is the type of transaction you are being notified about. If it is an Authorization flow, the transactionType will be 1. If it is an API (ie, Capture or Deposit), it will be the transactionType associated with that API (ie, 3 or 6).
  • transactionStatus: Status of the transaction to be updated in your system.
  • splitToken: If the transactionType is 1 (Authorization) and transactionStatus is 2 (Authorized), this will be the splitToken that needs to be saved on the Users profile and passed in subsequent Capture API calls.

If you need more details on a given transaction, you can use the provided objectId with the Get Transaction API call.

Note

The splitToken can only ever be sent once. If it is not received or stored, go ahead and attempt your Capture API call without it. If we require a splitToken to complete a Capture request, we will send you the Expired split token notification.

For more information on Event Notifications, refer to Event Notifications in this document or the Event Notification API Reference.

Common Failure Scenarios

Common failure scenarios are outlined in the table below.

Transaction Status Payment Provider Transaction Status Error Code Description Action to Take Suggested User Messaging
Failed SW057 326 Expired split token See Refresh a Bank Authorization using Online Banking. None
Failed SW051 380 Invalid / corrupt split token See Refresh a Bank Authorization using Online Banking. None
Failed SW056 330 Invalid account Remove the bank account from the Users profile in your system. Prompt the User to add another method of payment. Sorry, we are unable to process your request at this time. Please choose a different payment method.
Failed SW054 390 Fraud analysis. Remove the bank account from the Users profile in your system. Prompt the User to add another method of payment. Sorry, we are unable to process your request at this time. Please choose a different payment method.
Failed SW055 390 Fraud analysis (Negative Data). Remove the bank account from the Users profile in your system. Prompt the User to add another method of payment. Sorry, we are unable to process your request at this time. Please choose a different payment method.
Failed SW052 378 Internal error or bank request error Show the suggested User message on the payment method page and allow the User to try the payment again. Sorry, we are unable to process your request at this time. Please choose a different payment method.
Denied SW021 331 Not enough balance Show the suggested User message on the payment method page and allow the User to use another method of payment. Your account can not be used for payment at this time. Please select another method of payment to continue.

Capture and Deposit Transactions

The following diagram shows the Transaction State of a Capture or Deposit transaction. Transaction status updates are sent via Event Notification and can also be retrieved via the PayWithMyBank Transactions Report.

Capture Deposit State Diagram

  1. The Capture and Deposit API creates a transaction with the initial status of Authorized.
  2. Once the transaction is submitted to the network for processing, the transaction is moved to the Processed state.
  3. After 3 banking days, if the transaction has not been moved to the Denied state, it is moved to the Completed state.
  4. If there are any issues depositing the funds after the transaction has been moved to Completed, it is moved to the Reversed state.

Refund and Reclaim Transactions

The following diagram shows the Transaction State of a Refund or Reclaim transaction. Transaction status updates are sent via Event Notification and can also be retrieved via the PayWithMyBank Transactions Report.

Refund Reclaim State Diagram

  1. The Refund and Reclaim API creates a transaction with the initial status of Authorized.
  2. Once the transaction is submitted to the network for processing, the transaction is moved to the Processed state.
  3. After 3 banking days, if the transaction has not been moved to the Denied state, it is moved to the Completed state.
  4. If there are any issues depositing the funds after the transaction has been moved to Completed, it is moved to the Reversed state.

Refresh a Bank Authorization using Online Banking

Handling invalidated Transaction Id's

If you receive a Capture API response or receive an Event Notification with an error code of 330 and a Payment Provider Transaction Status of SW056, simply follow these steps:

  • Remove the Account from the Users profile.
  • Message the User with an appropriate message, such as Sorry, we are unable to process your request at this time. Please choose a different payment method.. Allow the User to select another method payment.
  • Create a new Bank Authorization using Online Banking. Save the new Authorization on the users Profile.

Handling expired Split Tokens

If you receive a Capture API response or receive an Event Notification with an error code of 326 and a Payment Provider Transaction Status of SW057, or an error code of 380 and a Payment Provider Transaction Status of SW051, simply follow these steps:

Refresh an expired Bank Authorization using Online Banking

In the event a Users Split Token expires or becomes invalidated, you can use the Refresh flow to request a new one.

Diagram

  1. You call the PayWithMyBank SDK's establish function, passing in paramters to launch the Refresh flow.
  2. From the PayWithMyBank Lightbox, the user authenticates with their bank and is immediately returned to your returnUrl.
  3. Before returning the User to your returnUrl, we will send an Event Notification to your listener with the transactionId and splitToken. You'll update the Users account on file at this point and attempt to process the Capture transaction again.

To integrate the PayWithMyBank Refresh flow into your website or app, you will need to do the following:

Integrate the PayWithMyBank SDK into your flow.

PayWithMyBank offers 3 SDK's: JavaScript, iOS, and Android. The SDK has 2 main methods: selectBankWidget and establish. The methods accept 2 parameters, options and establishData. The options parameter is optional and can be used to control pieces of the Lightbox experience. The establishData parameter is used pass transaction parameters to PayWithMyBank that are used when establishing the Bank Authorization transaction.

The following examples are using the JavaScript SDK

1. To load the SDK on the page, use the following JavaScript tag (replacing {accessId} with the Access Id provided to you by PayWithMyBank):

1
<script src="https://sandbox.paywithmybank.com/start/scripts/paywithmybank.js?accessId={accessId}"> </script>

2. To provide optional PayWithMyBank configuration options, create a PayWithMyBankOptions object:

1
2
3
4
var PayWithMyBankOptions = {
  closeButton: false,
  dragAndDrop: false,
};

For details on the PayWithMyBank configuration options, refer to the SDK Specification.

3. To provide the transaction details to the SDK, create an establishData object:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
var establishData = {
  accessId: {accessId},
  requestSignature: {requestSignature},
  merchantId: {merchantId},
  description: 'transaction description',
  currency: 'USD',
  amount: '0.00',
  merchantReference: 'merchant reference',
  paymentType: 'Verification',
  authToken: 'new',
  transactionId: {transactionId}
  returnUrl: 'https://merchant.com/paywithmybank/return',
  cancelUrl: 'https://merchant.com/paywithmybank/cancel'        
};

Info

Ensure you are passing in the transactionId that you have stored on file. This transactionId will not change.

Warning

Do not pass Consumer PII (name, email address, etc) in the description field. You can pass Consumer PII in the customer object.

Tip

Ensure you're securing your call by including the requestSignature parameter.

4. Finally, call the PayWithMyBank SDK's establish function:

1
PayWithMyBank.establish(establishData, PayWithMyBankOptions);

The following is a full HTML page using the above example.

Info

You'll want to replace {accessId} and {merchantId} with the values provided to you by PayWithMyBank. You'll want to replace {transactionId} with your stored transaction id.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
<html>
  <head>
    <meta name="viewport" content="width=device-width, initial-scale=1" />
    <script>
      var PayWithMyBankOptions = {
        closeButton: false,
        dragAndDrop: true,
        widgetContainerId: 'widget',
      };
    </script>
    <script src="https://sandbox.paywithmybank.com/start/scripts/paywithmybank.js?accessId={accessId}"></script>
  </head>
  <body style="margin: 0;">
    <div id="widget"></div>
  </body>
   <script>
    var establishData = {
      accessId: {accessId},
        merchantId: {merchantId},
        description: 'transaction description',
      currency: 'USD',
      amount: '0.00',
        merchantReference: 'merchant reference',
      paymentType: 'Verification',
      authToken: 'new',
      transactionId: {transactionId}
        returnUrl: 'https://merchant.com/paywithmybank/return',
        cancelUrl: 'https://merchant.com/paywithmybank/cancel'      
    };
    PayWithMyBank.establish(establishData, PayWithMyBankOptions);
  </script>
</html>

Receive the refreshed Split Token

Before the User is returned via the returnUrl, PayWithMyBank will send you an Event Notification that contains the parentObjectId (transactionId), splitToken, and other related fields. Once you receive the Notification, save the payment method to the Users account and return a 200 OK response to the Notification server.

Info

PayWithMyBank will not redirect the User to your returnUrl until we either receive a response (success or failure) or the request times out after 3 seconds.

Warning

If you fail to receive or store the splitToken, it can not be resent. You can (and should) attempt a Capture API call without it.

Example Verification notification

1
merchantId=1002463580&merchantReference=123123&paymentType=5&transactionType=1&parentObjectId=1002596444&parentMerchantReference=123123&eventId=1002642360&eventType=Authorize&objectId=1002642325&objectType=Transaction&message=&timeZone=Etc%2FUTC&createdAt=1557803299069&accessId=ASs345fldAHJPTHXcaK&accountVerified=true&fiCode=200005501&paymentProviderType=PWMB&status=2&statusMessage=Authorized&splitToken=CLvfv6KrLRABGGAgACowusCukkxmQ%2B%2BQseknVvMke5bDORHYSXZbLnPtCEPvL24Uae2XF7%2BcaSgIW%2BVC19J%2B

Please refer to Event Notifications for more information on handling Event Notifications.

Handle the redirect

If the User cancels the request, PayWithMyBank will direct the User to your provided cancelUrl. If the User successfully authorizes the request, PayWithMyBank will direct the User to your provided returnUrl.

Once you get a successful redirect to your returnUrl, check to ensure you've received the Split Token and added the account on file. If you have not, add the account on file with the provided transactionId and a blank or null splitToken.

Example Cancel URL

1
https://merchant.com/paywithmybank/cancel?transactionId=1002632909&transactionType=1&merchantReference=123123&status=7&payment.paymentType=2&panel=1&payment.paymentProviderTransaction.status=UC01&requestSignature=tp%2B%2B%2BI5nM%2BSeOT8TQKLGvfaEGcs%3D

Example Return URL

1
https://merchant.com/paywithmybank/return?merchantReference=123123&payment.account.verified=true&payment.paymentProvider.type=1&payment.paymentType=5&requestSignature=2yBF8Hlrte2yXttLEI934MfOiG4%3D&status=2&transactionId=1002642325&transactionType=1

Redirect URL Parameters

PayWithMyBank will append the following parameters to your returnUrl or cancelUrl:

Parameter Definition
transactionId A unique PayWithMyBank transaction identifier. (15 characters)
transactionType Will always be 1 in this use case.
merchantReference A specific merchant reference for this cancelation. For example, this could be your order number or session id.
status Integer value representing the Transaction Status. This will either be 2 (Authorized) or 7 (Cancelled). Refer to Transaction Status Values in the SDK Specification for a complete list of values and their definitions.
payment.paymentType Will always be 2 (Deferred) in this use case.
payment.paymentProvider.type Will always be 1 (Easy Online Debit / Online Banking) in this use case.
payment.account.verified ...
panel Integer value representing the PayWithMyBank screen the user exited the flow on. Refer to Panel Values in the SDK Specification for a complete list of values and their definitions.
payment.paymentProviderTransaction.status Integer value representing the Payment Provider Transaction Status of the transaction. Refer to Payment Provider Transaction Status in the SDK Specification for a complete list of values and their definitions.
requestSignature This is a signature that you can calculate to ensure the request you receive is coming from PayWithMyBank. See Calculating Redirect Request Signature for more information.

Testing

PayWithMyBank offers a Demo Bank in the Sandbox environment that can be used to trigger a number of testing scenarios. You access the Demo Bank, search for "Demo Bank" in the 'Select your bank' screen of the PayWithMyBank Lightbox. To simulate errors when using the Demo Bank, you can use the phrases below in the password field to generate errors.

Password Use Case
NoEligibleAccounts No eligible accounts found
LoginError Wrong username or password
NotRecognized Main Error that users see when using an ACA
NoSuchField This error ultimately ends up as a PageNotRec error. It happens when an item cannot be found on the page. ACA will try to execute another page. If there is no another page, “page not recognized” error will be returned. Customers shouldn’t see this error.
PostError HTTP connection error using GET. Customer shouldn’t see this error. In real ACA, this will result in a Site not available” error.
GetError HTTP connection error using POST. Customer shouldn’t see this error. In real ACA, this will result in a Site not available” error.
PromptTypeError When an ACA fails to create a prompt, this error is returned. If this error appears, it means the ACA has a bug.
JsError When ACA tries to run javascript code and there are any errors during running, this error will be thrown.
Unavailable Bank Site cannot be reached.
AccountLocked User’s account is locked.
Unclassified There are some run time exceptions that not captured by ACA, like NPE(null pointer exception), array out of bounds exception and so on.
BankAction The bank requires the user to login and perform some action on their site.
ConnectError There was a connection problem when accessing bank site
ConnectionError There was a connection problem when accessing bank site
BlockedIpError The bank indicates the caller IP was blocked
ChallengeError Simulates retry scenario, where the user provide wrong challenge (or anything that isn't userid or password) and is allowed to retry
ValidRouteCodeExtra Connector returns 2 accounts whose route codes are larger than 9 digits: one of them has a valid route code as substring, so both accounts use the same valid code
InvalidRouteCodeExtra Connector returns a single account whose route code is larger than 9 digits, but no valid route code is found as substring. Hence, the account is ignored
TimeoutError In order to simulate a timeout, connector sleeps for at least a minute before actually doing anything.
TestPrompts This is not an error. This is to test the prompts on next page, including (Checkbox, radio, text, password, date, description and so on)
NotEnoughFunds Connector returns a single account with zero balance. This is similar to having no eligible accounts, but with different reason.
NotEnoughFundsExtra Connector returns two accounts. One with zero balance, the other with a valid balance.
InvalidAccountNumberSize Connector returns a single account, but with account number shorter than the required. This is to test how the screen filters invalid accounts
InvalidAccountNumberSizeExtra Connector returns two accounts. One with account number shorter (3 characters) than the required, the other with valid account number.
PartialAccountNumbers Connector returns two accounts, however only with partial numbers. Simulating when for example the account is new and we still don't have statements to get full account number.
OnlyPartials PartialAccountNumbers + NoRouteCode
NoCustomer Simulates as if FIC was not able to retrieve customer information
NoRouteCode Regular flow with 2 accounts, but none with route code. This prompts a question for account location, where user must select where the account was open (from the given options)
InvalidRouteCode Regular flow but simulates an invalid routing code (will simulate if ProfitStars returns invalid routing code)
2FA Simulates as the bank requested a challenge question to the user. The question should be answered with the word 'error' if it's necessary to simulate a wrong credential. Otherwise, it should be anything to have a successful access.
WrongCredentials Simulates retry scenario, where the user provide wrong challenge (or anything that isn't userid or password) and is allowed to retry
SiteRequestError Simulates as if the bank couldn't process a particular request, allowing user to retry it
SessionTimeout Simulates as if the user took too long to provide the requested information, since the bank session is already expired
PreLoginError Simulates an error before the user gets authenticated
NotSupported Simulates an user with no supported accounts
AccountsWithNameAndAddress Simulates an User with 2 accounts and each one with different names and addresses.
ManyInformation Simulates an User with until 10 accounts.
AccountNotSupported Simulates an User with an account not supported by our service (Chase Liquid, etc)
AmountNull Simulates the Demo Checking Account returning an amount with null value.
AccNumberNull Simulates the Demo Checking Account returning null value in the account number and routing number
AccFromUsername Returns the account number from the pattern {prefix}_{accountnumber} on the username. Ex: To return an account with number 1234445 you can enter the username user1_1234445 or anotheruser_1234445.
RandomBalance Returns account with random balance
RandomAccounts Returns an account with random account number
LargeCustomerInfo Returns account with very large customer information
FICWarning It simply add to log engine fic-warning one example message to simulate the FIC Warning flow
EmailMFA Simulates as the bank requested the user to select an email address to send him a MFA token.
MixedMFA Simulates as the bank requested the user to select an email address or a phone number to send him a MFA token.
CreditCardsOnly Returns an account only with credit card
TCKAccounts Returns an account that is valid on TeleCheck test environment
AccountProfile Returns accounts with Business, Personal, Other, Unknown and Null profiles.
Balance{xxx} Configures the account to have a balance of {xxx}. For example, Balance1000 will set the account balance to $1000. This is useful when testing transactions of larger dollar amounts.
RandomAccWithSleep Returns random accounts with random account numbers and sleeps (in seconds) during the number passed in the password field
ExpiredSplitToken Allows the transaction to be authorized but every refresh API call fails because of an expired split token.
NotEnoughFundsOnRefresh Allows the transaction to be authorized but every refresh API call returns 0.00 as balance for all accounts.

To simulate a delay, just enter Sleep as username and the number of seconds as the password, The connector will wait for at least the given number of seconds before presenting any results.

Error Handling

PayWithMyBank uses conventional HTTP response codes to indicate success or failure of an API request.

HTTP Status Code Description
200 OK Everything worked as expected.
400 Bad Request Often due to a missing, required parameter.
401 Unauthorized Invalid accessId or accessKey.
500 Server error Something went wrong on PayWithMyBank's end.
503 Service Unavailable The server is currently unable to handle the request due to a temporary overloading or server maintenance.

Not all errors map cleanly onto HTTP response codes, however. In addition to the HTTP response code, PayWithMyBank returns an array of error objects that describes the errors as a JSON string such as the example below.

1
2
3
4
5
6
7
8
9
{
  "errors": [
    {
      "domain" : "com.paywithmybank.merchantgateway.v1.exception.InvalidParameterException",
      "code" : 200,
      "message" : "Could not find a transaction using Id 10000021"
    }
  ]
}
Error Code Description
100 Internal error. An internal error (an internal database exception for example) occurred when trying to process the request.
150 Remote error. A remote error (the consumer's bank interface is down) occurred when trying to process the request. This is an internal error.
200 Invalid parameter error. One of the request parameters is invalid (sending an invalid amount format string for example).
300 Security error. These are generic security errors that can happen when trying to process the request.
326 Expired split token.
330 Invalid account.
331 Not enough balance.
375 Access control error. These occurs when some security parameter (accessId, accessKey or requestSignature) is invalid and the request cannot be processed.
390 Fraud analysis. Suspicious transaction or negative data.

Further Reading