Skip to content

Server Side Establish Overview

PayWithMyBank can initiate the Online Banking flow via server side calls. This is typically used when you need to get a bank authorization in an offline flow. PayWithMyBank will initiate the process via SMS or email, or you can initiate the process yourself using the URL returned by PayWithMyBank. Once authorized, you can use additional PayWithMyBank API's to act against the authorization. This is a three step process:

  1. Create a Bank Authorization with the Establish API. Collect the customers Account and Routing Number in your flow. Pass this information to PayWithMyBank via the Establish API.
  2. Handle Event Notifications. Once the authorization is completed, PayWithMyBank will send an Event Notification with a transactionId that can be used with the PayWithMyBank API.
  3. Perform actions with the PayWithMyBank API's. Depending on your use case, you can use the PayWithMyBank API's to act upon the Bank Authorization.

Creating Bank Authorizations with the Establish API

Use the PayWithMyBank Establish API to create an Authorization Transaction that can be used with Deposit API.

To initiate the request, append the following parameters to the Establish API url:

  • notify: If true, PayWithMyBank will notify the user. Otherwise, you can use the URL in the response in your own notification.
  • channel: If notify is true, specifies the channel(s) to use to notify the user that a request needs to be completed. Values can either me email or sms (passed as a comma-separated list).

Additionally, pass in the following inputs:

  • merchantId: A unique PayWithMyBank merchant identifier.
  • merchantReference: A unique Merchant Reference identifier that represents your ID for the Authorization request.
  • customer: Information about the Customer that will be completing the request. name is required. email is required if the customer is to be notified via email. phone is required if the customer is to be notified via SMS.

Info

Ensure you pass a query string of notify=true and at least one channel parameter on the API Endpoint URL.

The response will be an Establish Data object. An example is shown below.

Example Request

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
POST /establish?channel=sms,email&notify=true

{
  "merchantId": "1002463580",
  "merchantReference": "e11166d2-f0ea-4215-a7b5-5f57a251481a",
  "customer": {
    "name": "Joe User",
    "phone": "+15551231234",
    "email": "joe@mail.com"
  }
 }

Example Response

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
{
    "establishData": {
        "merchantId": "1002463580",
        "paymentType": 6,
        "returnUrl": "https://sandbox.paywithmybank.com/start/establish/rtn",
        "cancelUrl": "https://sandbox.paywithmybank.com/start/establish",
        "data": "eNqTUjE3MEs1SE0y0DU1TE7TNUk1NdVNTE0x0E00NjY0SLJMTLUwMsrOKVbi981MzkhMzVFwyknMK8nPs+biNzMyVwgpSizLLM5XcM4skuL0ySxLLcrNL0pVYnJ21GK1NDE1NTBiCg22ceLRNrQ0MjWxMDcwMD",
        "accessId": "M8RaHgEjBE54zuFYMRQg",
        "requestSignature": "ZPomXHE9UW330XGSdqweY04U0E="
    },
    "url": "https://sandbox.paywithmybank.com/start/establish?a=M8RaHgEjBE54zuFYMRQq&m=1002463580&p=6&g=43&d=eNqTUjE3MEs1SE0y0DU1TE7TNUk1NdVNTE0x0E00NjY0SLJMTLUwMsrOKVbi981MzkhMzVFwyknMK8nPs%2BbiNzMyVwgpSizLLM5XcM4skuL0ySxLLcrNL0pVYnJjiUJBYWZ5ZkpFbmZSYl62XnJ9bAgDCESsQ&u=0&r=ZPomXHE9UW330XGPLX01VY04U0E%3D"
}

Handling Event Notifications

Authorized Transaction

Once the user has authenticated with their bank and selected the account to use, PayWithMyBank will send you an event notification that includes an objectId (transactionId) that can be used with the PayWithMyBank API's.

Example Event Notification

1
merchantId=1002463580&merchantReference=cc4275f6-9423-4f0d-8cbf-f78535742ea7&paymentType=6&transactionType=1&eventId=1002777467&eventType=Authorize&objectId=1002777451&objectType=Transaction&message=&timeZone=Etc%2FUTC&createdAt=1560635095925&accountVerified=true&fiCode=200005501&paymentProviderType=PWMB&status=2&statusMessage=Authorized

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

The following table lists expected errors and suggested actions that are associated with this product. For more information on Error Handling, consult the API Reference.

HTTP Status Code Suggested Action
400 Bad Request 200 Check the request parameters and retry the request.
401 Unauthorized 300 Check your API Credentials and Merchant Id and try the request again.
401 Unauthorized 375 Check your API Credentials and Merchant Id and try the request again.
500 Server Error 100 Retry the request and notify PayWithMyBank if the issue persists.

Further Reading