Skip to content

Disbursement Using Account Overview

PayWithMyBank can be used with legacy ACH Routing and Account Numbers to initiate a Disbursement using our real-time REST API's. 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. Create a Disbursement Transaction with the Deposit API. When the time comes to initiate a Disbursement, pass the transactionId created in Step 1 to the PayWithMyBank Deposit API.
  3. Handle Event Notifications. Once the Disbursement is completed, PayWithMyBank will send an Event Notification with the final disposition of the Disbursement.

In addition, you should implement the following operational interfaces:

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, 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.
  • account.accountNumber: This is the account number entered by the sender.
  • account.routingNumber: This is the routing number entered by the sender.
  • amount: The amount of the transaction. This represents the maximum amount of the transactions that can be processed with the Authorization. If the amount is 0.00, there will be no upper bound on the transaction.
  • currency: 3-letter ISO Currency Code. Currently only USD is supported.
  • paymentType: The Payment Type of the transaction to create. This should be Disbursement.
  • returnUrl: Not used.
  • canceUrl: Not used.

Ensure you pass a query string of createTransaction=true on the API Endpoint URL.

You can optionally pass in an account.type (Account Type - Checking or Savings). For a full list of the fields, consult the establish API reference.

The response will be a PayWithMyBank Transaction object. An abbreviate example is shown below. You'll want to store the transactionId so it can be passed to the Deposit call.

Example Request

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
POST /establish?createTransaction=true

{
  "merchantId": "1002463580",
  "merchantReference": "2eabae90-f466-47e3-99d5-73d0492e8f37",
  "account": {
    "accountNumber": "123456576",
    "routingNumber": "124003116",
    "type": 1
  },
  "amount": "0.00",
  "currency": "USD",
  "deviceType": "web",
  "paymentType": "Disbursement",
  "returnUrl": "#return",
  "cancelUrl": "#cancel"
}

Example 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
{
    "transaction": {
        "transactionId": "1002613662",
        "transactionType": 1,
        "payment": {
            "paymentId": "1002613661",
            "paymentType": 4,
            "merchantId": "1002463580",
            "account": {
                "type": 1,
                "accountNumber": "123456576",
                "routingNumber": "124003116",
                "source": 0
            },
            "returnUrl": "#return",
            "cancelUrl": "#cancel",
            "amount": "0.00",
        },
        "currency": "USD",
        "amount": "0.00",
        "status": 0,
        "statusMessage": "Authorized",
        "merchantReference": "2eabae90-f466-47e3-99d5-73d0492e8f37"
    }
}

Creating Disbursement Transactions with the Deposit API

With a valid transactionId from an Authorization request, you can use the PayWithMyBank Deposit API to initiate a Disbursement or Payout transaction to a users bank account.

To initiate the request, pass in the following inputs:

  • transactionId: Authorization Transaction ID retrieved from a PayWithMyBank Deferred or Disbursement Authorization.
  • amount: The amount to be sent. Required if the Authorization Transaction amount was 0.00. If not passed, the full amount of the Authorization Transaction will be used.
  • merchantReference: A specific merchant reference for this deposit. For example, this could be an merchant order number or the same merchant reference value used in the original establish call.

If successful, the response of this call will be an authorized Disbursement transaction. Updates to the status of the transaction will be sent via Event Notification.

Example Request

1
2
3
POST /transactions/1002613662/deposit

amount=25.00&merchantReference=f9c28cd0-bca1-47cb-a776-238b621e66cb

Example 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
{
    "transaction": {
        "transactionId": "1002613685",
        "transactionType": 6,
        "originalTransactionId": "1002613662",
        "payment": {
            "paymentId": "1002580220",
            "paymentType": 2,
        },
        "currency": "USD",
        "amount": "25.00",
        "status": 2,
        "statusMessage": "Authorized",
        "createdAt": 1556922524381,
        "processedAt": 1556922524393,
        "completedAt": 1556922524621,
        "updatedAt": 1556922524622,
        "ppTrxId": "ptx-CquvTsAaPDvaSB6ywZ2krXGS-sbx",
        "merchantReference": "f9c28cd0-bca1-47cb-a776-238b621e66cb",
        "statusCode": "AC100",
        "recordVersion": 1
    }
}

Handling Event Notifications

Disbursement Transactions

The following diagram shows the Transaction State of a Disbursement 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 Deposit API returns a 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.

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

Testing

The following table lists inputs and expected results that can be used for testing.

Input Expected result
accountNumber: 123456575
routingNumber: 124003116
Successful Authorization request.

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