Managing Payment Integrations
How to manage 3rd-party payment integrations
Introduction
Village connects to a number of 3rd-party payouts providers such as Stripe or Paypal. This section focuses on the admin management of payments and incentives payouts through 3rd-party payment providers. This guide focuses on our Stripe integration.
Getting Started
Overview
Village has a native Stripe App. This app allows you to give Village specifically scoped permissions to view and administer functions within your Stripe account. These include:
Creating and issuing discounts and promotions. These are most commonly used where you want rules to trigger the application of coupons on demand-side users.
Applying payout balances to Stripe Connect accounts to administer payouts. This is most commonly used where you want to issue payouts of incentives or core payment flows to workers or supply-side users.
While Village makes the creation and automation of these flows easy, in all cases admins are able to manage the specific functionality that Village has access to, as well as managing final approval of any payouts.
Setup
During onboarding, the Village team will share access to its Stripe App for sharing and configuration of API keys. Read more about integration here.
To verify the connection, go to Side Menu > Payouts. You'll see active 3rd-Party Payment connections here.
Payouts
When users earn on your platform, these earnings show up in Village's embeddable end-user dashboard. Depending on your configuration, this may be limited to incentives and bonuses only, or may also include all core earnings on your platform.
A user can see these earnings, and choose to cash all or some portion of earnings out at any point after they are earned.
This pushes a payout request to your Stripe account for the desired cashout amount.
This payout request appears in your Stripe account, just like any other payout amount calculated through Stripe's internal earnings or miscellaneous payment flows. As such, it is incorporated through your regular payment processes from a tax and accounting perspective, all of which can be wholly managed through your existing Stripe account.
This payout request will also appear in the Payouts tab of the Village admin dashboard. Side Menu > Payouts > Manage. This gives you a summary of all payout requests, and allows you to approve or reject them from within Village. If you choose to do this within Village, this will take the corresponding action within your Stripe dashboard and initiate the payout.
Approval Management
Just like in Stripe, you'll have a number of options for managing the payout:
These approval statuses are the same as those in Stripe:
Approve (approves and processes payment)
Reject & Do Not Return (does not process payment and does not return the funds to the user wallet)
Reject & Return (does not process payment, but does return funds to the user wallet)
Retry (attempts to retry to payment)
Mark Complete (mark payment as resolved, eg. in the case that you have processed payment separately)
These statuses will be synced across Village and your Stripe account.
Stripe Connect Setup
Just as when you pay out through regular Stripe processes, a user must have a Stripe Connect account setup to receive payments. If they do not and you try to process payment, you will get the error message 'User Account Not Setup'.
When a user tries to cash-out a payment from their Village wallet and they have not previously configured a Stripe Connect account, Village will prompt them to complete their Stripe Connect setup in the payout request flow.
FAQ
Am I able to automate payout processes?
Upon setup, this process relies on a. user initiating payout, and b. an admin manually approving the payout amount. Particularly around initial integration, or if you are just starting out with Village we recommend this manual request and approval process to ensure the payout rules you have configured are performing as expected, and the payout amounts are correct.
If you do want to automate either of these processes, please reach out to the Village team. You're able to automate the payout to users on a fixed schedule, as well as automating a payout's approval.
What 3rd-party Payments Providers does Village integrate with?
Right now, we have automated integrations with Stripe and PayPal. If there are particular payment integrations you're interested in, please reach out to our team.
How does this work from a tax and accounting perspective?
Because Village pushes payment entries back to your existing Stripe account ledger, there is no need to incorporate any separate tax or accounting methodologies outside of your existing processes to handle incentives or payment structures initiated through Village.
Do users get paid out immediately when they request cashout?
No, unless you have turned on auto-approval, you will still need to approve any payout requests as part of your existing Stripe payout processes in Stripe (or through the Village dashboard). You are able to schedule these approval on a recurring basis if needed once you're comfortable with payout processes.
Is the end user dashboard embeddable?
Yes, all elements of the end user dashboard can be embedded in your existing user flows, including the cashout flow.
Last updated
