3rd Party Payments Integrations
Integrating with Stripe, PayPal, and other payment services
Last updated
Integrating with Stripe, PayPal, and other payment services
Last updated
Whenever you issue a Monetary (Cash) Award type to one of your users, they will have the option to "Cash Out" on their end-user dashboard. Depending on how you configure your Cash Award and the Third Party Payments associated with those Awards, Village will change how it handles end-user cash out requests for your Network.
There are multiple options for how Village will handle Cash Outs:
Stripe App - best if you use Stripe and want to manage all payouts directly through Village
PayPal App - best if you use PayPal and want to manage all payouts directly through Village
Manual payouts - best if you're just getting started, or you primarily use ACH or wire transfers
Webhooks for real-time payment initiation - best if your platform uses other 3rd-party payments providers and/or you want complete, automated control over payouts
Village has built direct integrations with Stripe and PayPal that require a quick but secure integration with the Village engineering team. For security reasons, this process is not self service.
Reach out to our team at support@villagelabs.co to get the process started.
Listen for events from Village so you can automatically trigger payouts in services like Stripe and PayPal.
Overview of webhook process:
Configure webhook endpoint
Set Secret
Validate Payloads from Village
Process Payouts Payload
Send Response to Village
To configure your webhook navigate to Side Menu -> Treasury -> Third Party Payments. Then select the Cash Award type you want to modify.
To configure your webhook endpoint, do the following:
Primary Payout Method: Webhook
HTTP Endpoint: https://your_endpoint_here
Set Secret:
In the "Secret" field, type a random string with high entropy. You can generate a string with ruby -rsecurerandom -e 'puts SecureRandom.hex(20)'
in the terminal, for example.
Click Save.
Next, set up an environment variable on your server that stores this token. Typically, this is as simple as running:
Never hardcode the token into your app!
When your secret token is set, Village uses it to create a hash signature with each payload. This hash signature is included with the headers of each request.
You should calculate a hash using your SECRET_TOKEN
, and ensure that the result matches the hash from Village. Village uses an HMAC hex digest to compute the hash.
Note: Webhook payloads can contain unicode characters. If your language and server implementation specifies a character encoding, ensure that you handle the payload as UTF-8.
Note:
No matter which implementation you use, the hash signature starts with sha256=
, using the key of your secret token and your payload body.
Using a plain ==
operator is not advised. A method like secure_compare
performs a "constant time" string comparison, which helps mitigate certain timing attacks against regular equality operators.
Village will pass the key cash out details to your platform so that you can easily initiate a payout using your third party payment provider's API.
In this code:
Before initiating a payout, make sure the connected account has enabled payouts and the bank account or debit card is set up properly.
Stripe expects the amount for its transactions in the smallest unit of whatever currency you're working with. So if you're dealing with dollars, you need to convert it to cents.
The Stripe API needs the ID of the connected account to which you want to pay out. This ID usually starts with "acct_". You'll need to map the destination_email
from your webhook to the corresponding Stripe Account ID.
For the metadata field, you can pass an optional dictionary of additional Stripe API parameters.
Stripe's Payout API also includes an optional description field where you can put a human-readable description for the payout.
You should handle exceptions that could be raised during the creation of the payout, such as InvalidRequestError
, AuthenticationError
, APIConnectionError
, StripeError
, etc., depending on your needs.
You need to replace os.getenv('
STRIPE_SECRET_KEY
')
with your Stripe secret key. It's not safe to hard code your key into your source code, so you should store it in an environment variable or some secure method.
Caution: If you have the Cash Payout webhook configured and Village does not receive a timely 200 Response, or if the request times out, the balance will be returned to the user and the Cash Out request will fail.
Expected Response Codes:
If Village receives a 200 response code it will complete the end user's Cash Out request and remove the Monetary Award type from their digital wallet.
Code | Description |
---|---|
200
OK: Successfully Processed.
400
Bad Request: your server could not process the request due to malformed payload.
500
Internal Server Error: An unexpected error occurred on the server while processing the request.