While we want Stripe to do the heavy lifting of the payment processing, you want to know what has happened, and have it recorded in your Salesforce org, so that you can maintain it as your single source of truth. To do this, you will utilise webhooks from Stripe. Every time an event occurs in Stripe, if you have set up the webhooks correctly, you will receive all the necessary data into Salesforce, ready for PosiPay to update your records.
| Info |
|---|
Please note that to avoid creating duplicate Gateway Events and to ensure successful Gateway Transaction and Gift Transaction processes, there should be only one webhook endpoint per Gateway Account in your org. |
How to set up
...
webhooks in the Stripe Dashboard
Go to Developers > Webhooks > Add endpoint.
...
When the Add endpoint is clicked, the image below will be shown.
Endpoint URL = Get the Webhook Endpoint URl from your Gateway Account record.
Listen to = Events on you account
Select events to listen to = Refer to the screenshots below for the adding of events.
...
Choose which Stripe Events to listen to
You must select which events to listen to for each Stripe object. There are 3 objects that PosiPay needs to listen to. Each object has different events, so carefully select only what is needed. Wherever possible, do not select all events available.
Charge
Invoice
...
Please note: If PosiPay version is 92 and above please do not include the invoice.created and invoice.updated event.
...
Payouts
...
...
Fundraising Extension uses invoices for gift transaction scheduled payments. PosiPayments needs to have a facility to listen to any invoice events.
The payload is sent out to salesforce from the stripe webhook.
...
Invoice payments can:
Request payment on specific future dates Automatically charge a payment
Payouts
...
Payment
payment_intent.canceled
...
payment_method.attached
payment_method.automatically_updated
payment_method.updated
Customer
customer.created
customer.updated
How to configure payouts on your dashboard
Go to Balances and click Manage. See the sample screenshot below.
...
More details about the payout schedule are here.
Gateway Event Mapping (Stripe → Salesforce)
Gateway Invoice Field | Response Field | Notes |
Event ID | id (Event) |
|
Raw Request |
| Full JSON body |
Webhook Event Object |
data.object.object |
|
Gateway Account |
data.object.metadata.gateway_id |
|
Gateway Transaction Mapping (Stripe → Salesforce)
Gateway Invoice Field | Response Field | Notes |
|---|---|---|
Payment Intent ID | data.object.charges.data.payment_ intent |
|
Charge ID | data.object.latest_charge |
|
Balance Transaction ID |
data.object.charges.data.balance_ transaction |
|
Amount |
data.object.amount |
|
Transaction Currency |
data.object.currency |
|
Payment Type | data.object.charges.data.payment_ method_details.type | If the type is “card”, the Payment Type is set to “Cards”. If the type is “au_becs_debit”, the Payment Type is set to “Bank Debits”. |
Transaction Status |
data.object.status | If the status is “succeeded”, the Transaction Status is set to “Success”. If the status is “processing”, the Transaction Status is set to “Pending”. Otherwise, Transaction Status is set to “Failed”. |
Payment Date | created |
|
Decline Code |
data.object.last_payment_error.de cline_code | This field is hidden in the page layout if empty. |
Result Code | data.object.last_payment_error.co de | This field is hidden in the page layout if empty. |
Result Message | data.object.last_payment_error.me ssage | This field is hidden in the page layout if empty. |
Gateway Invoice Mapping (Stripe → Salesforce)
...
Gateway Invoice Field
...
Response Field
...
Notes
...
Invoice ID
...
data.object.id (Event)
...
...
Payment Intent ID
...
data.object.payment_intent
...
...
Amount Paid
...
data.object.amount_paid
...
...
Invoice Status
...
data.object.status
...
Enable Payment Method
Enable the following Payment Methods in your Stripe Account. To enable Payment Methods, go to Payment Settings and click the Turn On button.
...
How to configure Block Rules for Fraud Detection (Radar)
Go to Homepage > Search for Fraud/Radar in the search bar above > Click the Rules tab
...
In the Rules tab, you can review the specific conditions of the block rules and Authentication rules that have been established.
...
To configure fraud detection, you'll need to click on the "Add Rule" button. Doing so will display the “Create Rule” interface on the right side of the screen. This is where you can specify the rules for blocking payments.
...
After you have added the conditions, click on “Test Rule". You will then be redirected to the “Review Rule” page to check and review the new rule before it is added.
...
In the "Review new rule" section, you can check the conditions and see if there are any errors or important notices before adding the new rule. After carefully reviewing, click the Add Rule button to successfully add it.
...
After adding the rule, the newly added rules or conditions will be reflected under the Block Rules.
...
The Stripe will follow the conditions established in the Block Rules. If the payment meets these conditions, it will be tagged as Fraud and blocked.
Upgrading Stripe API Version
Upgrade your Stripe API version default to 2022-08-01 or later, if you are still using the older versions.
Go to Homepage > Developer > Overview tab > API Version > Click Upgrade available…
Click Upgrade to upgrade the API Version.
...
After clicking the Upgrade button, the page will refresh, and the latest version of the API will be reflected.
...
Set up the Smart Retries on a Stripe account
Open your Stripe Account and go to Billing.
In the Invoices tab,locate Advanced invoicing features.
In the Retry schedule select Use custom retry schedule for one-off invoices.
Select Retry 1 day after the previous attempt.
...
Next place to go: Step 5 - Schedule an Invoice