To Take Note for Stripe

IP Addresses

If your project requires IP addresses of external integrations to be whitelisted, refer to Stripe’s list of IP addresses .

Stripe uses API keys for authentication with their APIs.
The test API key can be found when accessing the Stripe dashboard in test mode.
The live API key can be found when accessing the Stripe dashboard in live mode.
- Note: the live API key can only be revealed once, so make sure it is saved in BitWarden.

Take note that the success_url parameter (URL for success page) passed to Stripe must be a string under 500 characters.
It is recommended to only add the Checkout Session ID to the success_url.
Any additional information should be passed to Stripe via the Checkout Session’s metadata .
Using the checkout session ID provided to the success_url, we can retrieve the checkout session and all of its metadata.
In the event that the customer is paying for hundreds of items and the success page has to show a list of all the items, store the list of items in a table in the database and pass the primary key of the record to Stripe as metadata.

To avoid unnecessary handling, only listen for specific Stripe events that your application is interested in.
Ensure that each unique event from Stripe will only be handled once.
- If an event is received from Stripe again, it should not be processed.
Take note that Stripe only saves events from the last 30 days. Events older than 30 days will be deleted by Stripe.
- Any events that have failed to be handled correctly needs to be correctly handled before they get deleted by Stripe.

Stripe recommends creating a new Checkout Session each time the customer attempts to pay. This means that multiple Checkout Sessions and Payment Intents can be created for a single purchase if the customer makes multiple attempts to pay.
It is important to record each attempt with a unique ID such that the payment status for each attempt can be updated correctly.
For all failed attempts that have not been cancelled, Stripe will automatically cancel the Checkout Session 24 hours after creation. This creates a payment_intent.cancelled event which will be updated via webhook.
- When processing the cancellation event, ensure that you fetch and update the payment attempt via its unique ID.

Stripe compiles all transactions for a day and deposits a lump sum into the linked bank account as a Payout after x days (configurable in Stripe dashboard).
For each transaction, Stripe also charges a fee. The net amount credited for the transaction can be found in the Net field.
In order to reconcile the payment transactions with bank account statements, we will have to listen for and process the payout.paid event from Stripe.
From the payout.paid event, we get a payout object ID, which can be used to retrieve the details of the individual transactions compiled in the Payout.
- The balance transactions list API will return a list of transactions with a specified payout object ID.
- Expand the data.source field when calling the balance transactions list API to retrieve information about the transactions.

Stripe applies rate limits on their APIs which prevents many requests in quick succession.
- Error code 429 is typically associated with rate limits.
Due to Stripe’s rate limiting, load tests integrated with Stripe API are not recommended.
- It is recommended to mock out requests to the Stripe API for load testing.

It is possible that your application is hosted in a contained environment and traffic will have to go through an API Gateway in order to reach Stripe.
The OpenAPI specifications for Stripe’s APIs can be found here .
Note that the OpenAPI specs have tens of thousands of lines. When onboarding to API Gateway, it is possible that the file may get rejected.
- In this case, it is recommended to drop the schemas (except error) and convert all schema types of the endpoints (except error) to object.
- Also consider dropping unused endpoints from the specs.
- A sample of the edited OpenAPI specs in JSON format can be found below: stripe-openapi-spec3.json