Enrollment
In order to securely collect consumer bank account information, BankPay provides an SDK that directly collects information from consumers without it ever being stored on your servers. Enrollments are a long-lived process, including a creation, bank account addition, and authorization phase. To support these multiple states, BankPay uses an Enrollment Intent object to track the lifecycle of an enrollment.
click to view the Enrollment Interface diagram
Creating an Enrollment Intent
Using your secret key, you make a server-to-server API call to create an EnrollmentIntent. You will pass either a consumer_id or consumer specific information to create this intent.
You may optionally include the consumer’s basic contact information as a convenience to them and to increase the conversion rate of completing the enrollment.
Example Enrollment Intent Creation Call For New Consumer
POST /api/enrollment-intents
{
"billing_address":{
"city_locality":"Tampa",
"country_code":"US",
"line_1":"123 Main St",
"line_2":"Suite 100",
"state_province":"FL",
"postal_code":"33603"
},
"company_name":"ACME, Inc.",
"date_of_birth":"1970-01-01",
"email_address":"john.doe@example.com",
"email_address_is_verified":true,
"external_customer_id":"example",
"first_name":"John",
"last_name":"Doe",
"phone_number":"8132551234",
"phone_number_is_verified":true
}
Example Enrollment Intent Creation Call For Existing Consumer
POST /api/enrollment-intents
{
"consumer": "consumer_1HViHo3gLsG3qCzhello"
}
Example Enrollment Intent Creation Response
{
"data":{
"expires_at":"2020-04-06T13:12:31Z",
"id":"enrollment_intent_Oqj1mlD0ydg6KsEXzTPcWZZibmz5h59v",
"status":"created",
"address":{
"id":"address_tpcMLpgYjGvS1pzHHnNdiTcTSpIRxza8",
"standardized":true
},
"bank_account":null,
"consumer":{
"id":"consumer_boFSdB9vmNhiQrD2tgZJ7cHJO39bjEYz"
}
},
"meta":{
"type":"enrollment_intent"
}
}
Receiving Bank Account Information from Consumer
BankPay provides an SDK that directly collects the consumers bank account information.
Within your app, you will initiate BankPay with your publishable key, then pass the needed information and BankPay will then present an interface for the consumer to directly provide their bank account information, either through a secure bank login or by manually entering their routing and account numbers.
During this step, you will receive back a response once the bank account information has been added. You must then process the enrollment through a server-to-server API call using your secret key. This must take place while the consumer is interacting with the SDK so that we can display feedback to them.
Example Enrollment Intent Authorization Call
POST /api/enrollment-intents/:enrollment-intent-id
{
"action": "process"
}
Once you have successfully processed the enrollment, BankPay provides feedback to the consumer and you can safely dismiss the SDK.
Upon success, you should store the consumer.id and bank_account.id returned from this call in your database. A consumer may enroll multiple bank accounts by triggering the enrollment process multiple times. You should store multiple bank account responses, including the bank_account.id, bank_account.routing_number, bank_account.account_type, and (masked) bank_account.account_number. You can display this information to the consumer so they can confirm the bank account they want to use in a future transaction.
Transaction
Transactions are a long-lived process, including a creation, service fee acceptance, authorization, and capture phase. To support these multiple states, BankPay uses a Transaction Intent object to track the lifecycle of a transaction.
click here to view Transaction Interface diagram
Creating a Transaction Intent
Using your secret key, you make a server-to-server API call to create a TransactionIntent. You will pass a consumer_id, bank_account_id and other information to create this intent.
Example Transaction Intent Creation Call
POST /api/transaction-intents
{
"amount":9.99,
"bank_account":"bank_account_jilefFE9sQWqXADBCpd7IBAY4SeVPGhU",
"billing_address":{
"city_locality":"Tampa",
"country_code":"US",
"line_1":"123 Main St",
"line_2":"Suite 100",
"state_province":"FL",
"postal_code":"33603"
},
"consumer_id":"consumer_boFSdB9vmNhiQrD2tgZJ7cHJO39bjEYz",
"store_number":"1"
}
Example Transaction Intent Creation Response
{
"data":{
"amount_authorized":"5.99",
"amount_captured":null,
"authorized_at":null,
"bank_account_id":"bank_account_jilefFE9sQWqXADBCpd7IBAY4SeVPGhU",
"captured_at":null,
"captured_status":null,
"consumer_id":"consumer_boFSdB9vmNhiQrD2tgZJ7cHJO39bjEYz",
"id":"transaction_intent_UkgnvxUgruGyMx6UBWHrf6XTma96Gu8x",
"reference_id":null,
"service_fee":"5.00",
"service_fee_accepted_at":null,
"status":"pending_service_fee_acceptance"
},
"meta":{
"type":"transaction_intent"
}
}
Receiving Service Fee Acceptance from Consumer
BankPay provides an SDK that directly collects the consumer’s acceptance of a possible service fee.
Within your app, you will initiate BankPay with your publishable key, then pass the needed information and BankPay will then present an interface for the consumer to directly view the possible service fee disclosure and indicate their acceptance.
Our SDK will notify you once it determines the service fee has been accepted. You must then authorize the transaction through a server-to-server API call using your secret key. This must take place while the consumer is interacting with the SDK so that we can display feedback to them.
Capturing a Transaction Intent
Once the Transaction Intent has had the service fee accepted and has been authorized, you must finally capture the funds. This step may be performed immediately or later depending on your business logic. For example, an in-person transaction may immediately capture the funds, but a mail order transaction may wait to capture the funds until the product is ready to ship.
PATCH /api/transaction-intents/:transaction-intent-id
{
"action": "capture"
"amount": "5.99"
}