📘

Prerequisite

Set Up Enterprise Account In Sandbox

❗️

Note

You must be configured for this use case, or your transfer request will result in an error. Contact your Orum representative for more details if you plan to incorporate this use case into your product.

Overview

Pay by Bank offers a convenient way to enable persons to pay businesses for goods or services using a bank account. This option can be used as an alternative to credit or debit card payments and is preferred by some persons and businesses because it allows them to transact without incurring additional fees or charges that cards tend to possess. Some examples of when you may use a pay-by-bank transfer:

• E-commerce platforms: Enabling a new payment method on your e-commerce platform so customers can choose to pay merchants with their bank account
• Marketplaces: Enabling a new payment method on your marketplace so customers can choose to pay sellers with their bank account
• Donations: Enabling individuals to make charitable donations using their bank account

Transfer Request Requirements

Persons in the created state are only eligible to be the source in a pay-by-bank transfer OR the destination in a pay-by-bank return.

Steps

For the following steps, we’ll assume you’re building an e-commerce platform that enables consumers to pay merchants for goods and services with their bank accounts, and your customer, the Merchant, is an online sneaker company.

• E-commerce Platform enables merchants to sell their products on an online storefront
• Sneaker Company sells sneakers to consumers via their website (business)
• Consumer wants to purchase sneakers (person)

1. Authenticate to Deliver

Use the /authenticate and /refresh endpoints.

2. Create a consumer and their associated bank account

Use the POST /persons endpoint to create the consumer and the POST /external/accounts endpoint to create the consumer’s bank account. The external account can be created as soon as the consumer is created.

• The external account can be created while verification takes place
• If you are using your own account verification provider (BYO), the external account will be automatically verified

{
     "customer_reference_id": "consumer_1",
     "first_name": "Francis",
     "last_name": "Smith"
}

{
     "account_reference_id": "consumer_account_1",
     "customer_reference_id": "consumer_1",
     "customer_resource_type": "person",
     "account_type": "checking",
     "account_number": "987654321",
     "routing_number": "900000009",
     "account_holder_name": "Francis Smith"
}

3. Create the Sneaker Company and its associated bank account

Use the POST /business endpoint to create the Sneaker Company and the POST /external/accounts endpoint to create its external account. The external account can be created as soon as the Sneaker Company is created.

Before sending a transfer request, the Sneaker Company must complete KYB verification and continuous watchlist registration.

{
     "customer_reference_id": "sneaker_company_1",
     "legal_name": "Sneaker Company",
     "tax_id": "123456789",
     "tax_id_type": "tin",
     "addresses": [
          {
               "type": "legal",
               "country": "US",
               "address1": "100 Sneaker Lane",
               "city": "Sneakerville",
               "state": "NY",
               "zip5": "10001"
          }
     ]
}

{
     "account_reference_id": "sneaker_company_account_1",
     "customer_reference_id": "sneaker_company_1",
     "customer_resource_type": "business",
     "account_type": "checking",
     "account_number": "123456789",
     "routing_number": "100000001",
     "account_holder_name": "Sneaker Company Owner"
}

4. Send a Pay by Bank transfer

Use the POST /transfers endpoint to create the transfer. When initiating a pay-by-bank transfer for the purpose of a consumer purchase, ensure the consumer from Step 2 is in the source object and the Sneaker Company from Step 3 is in the destination object.

• The consumer only needs to be in a created state
• The Sneaker Company needs to be in a verified state
• The source and destination bank accounts must be in a verified state

{
     "currency": "USD",
     "source": {
          "account_reference_id": "consumer_account_1",
          "customer_reference_id": "consumer_1"
     },
     "destination": {
          "account_reference_id": "sneaker_company_account_1",
          "customer_reference_id": "sneaker_company_1"
     },
     "transfer_reference_id": "transfer_1",
     "amount": 35000,
     "speed": "asap"
}

5. Send a Pay by Bank refund

In the event Francis Smith returns their sneaker purchase, you can issue a refund using the same POST /transfers endpoint. Switch the source and destination inputs so that the Sneaker Company from Step 3 is in the source object and the Francis Smith from Step 2 is in the destination object.

• The consumer only needs to be in a created state
• The Sneaker Company needs to be in a verified state
• The source and destination bank accounts must be in a verified state

{
     "currency": "USD",
     "source": {
          "account_reference_id": "sneaker_company_account_1",
          "customer_reference_id": "sneaker_company_1"
     },
     "destination": {
          "account_reference_id": "consumer_account_1",
          "customer_reference_id": "consumer_1"
     },
     "transfer_reference_id": "transfer_2",
     "amount": 35000,
     "speed": "asap"
}

Troubleshooting Common Errors

Customer Status

Customer status errors can occur when the customer's status in either the source or destination is invalid. For pay-by-bank transactions, only one party can be in the "created" state, leading to errors when both the source and destination parties are in this state. The correct placement of the "created" party depends on the type of transfer being sent. For a standard pay-by-bank transfer, the source object should have the "created" person, while for a refund from the business to the person, the destination should have the "created" person. To resolve this issue, it is important to ensure the party in the source and destination objects are in the appropriate state.

Customer Type

Customer type errors can occur if the improper type (person or business) is used when sending a transfer. For pay-by-bank transfers, ensuring that the correct customer type is submitted as the source and/or destination object is important. The customer type should be the person for the source and a business for the destination for a standard pay-by-bank transfer. Conversely, for a pay-by-bank refund, the source and destination objects should be business and person, respectively. If the customer type in either the source or destination object is incorrect, an error may occur. To resolve this issue, it is important to ensure that the correct customer type is being submitted in the appropriate object to prevent any errors during the transfer process.