Pay by Bank
Transfer funds from a person's external checking or savings account to a business to purchase goods or services.
Prerequisite
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.
Use Case | Source | Destination |
---|---|---|
Pay by Bank | Person (Created) - Customer reference ID - First name - Last name External Account (Verified) - Account reference ID - Customer reference ID - Customer resource type - Account type - Account number - Routing number - Account holder name | Business (Verified) - Customer reference ID - Legal name - Tax ID - Tax ID type - Addresses External Account (Verified) - Account reference ID - Customer reference ID - Customer resource type - Account type - Account number - Routing number - Account holder name |
Pay by Bank — return or refund | Business (Verified) - Customer reference ID - Legal name - Tax ID - Tax ID type - Addresses External Account (Verified) - Account reference ID - Customer reference ID - Customer resource type - Account type - Account number - Routing number - Account holder name | Person (Created) - Customer reference ID - First name - Last name External Account (Verified) - Account reference ID - Customer reference ID - Customer resource type - Account type - Account number - Routing number - Account holder name |
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.
Updated 8 months ago