Skip to content

Commit cc1d53b

Browse files
sharjeelyunussharjeelyunus
authored
Merge pull request #92 from EnsembleUI/stripe-docs
2 parents 4157018 + 6d40f6f commit cc1d53b

File tree

5 files changed

+457
-0
lines changed

5 files changed

+457
-0
lines changed

‎pages/_meta.json‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -42,6 +42,9 @@
4242
"authentication": {
4343
"title": "Authentication"
4444
},
45+
"payments": {
46+
"title": "Payments"
47+
},
4548
"moengage": {
4649
"title": "MoEngage"
4750
},

‎pages/actions/_meta.json‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -152,6 +152,9 @@
152152
"show-notification": {
153153
"title": "Show Notification"
154154
},
155+
"show-payment-sheet": {
156+
"title": "Show Payment Sheet"
157+
},
155158
"show-toast": {
156159
"title": "Show Toast"
157160
},

‎pages/actions/show-payment-sheet.md‎

Lines changed: 218 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,218 @@
1+
# showPaymentSheet
2+
3+
The `showPaymentSheet` action displays Stripe's Payment Sheet, allowing users to securely enter payment information and complete transactions within your Ensemble app.
4+
5+
### Properties
6+
7+
| Property | Type | Description |
8+
| :------------ | :----- | :--------------------------------------------------------------------------------------- |
9+
| clientSecret | string | The Stripe PaymentIntent client secret that identifies the payment to be completed. |
10+
| configuration | object | Optional configuration for the payment sheet. [see properties](#propertiesconfiguration) |
11+
| onSuccess | action | Execute an Action when the payment is successfully completed. |
12+
| onError | action | Execute an Action when the payment fails or is cancelled. |
13+
14+
#### properties.configuration
15+
16+
| Property | Type | Description |
17+
| :------------------------- | :----- | :--------------------------------------------------------------------------- |
18+
| merchantDisplayName | string | The merchant display name shown in the payment sheet. |
19+
| preferredNetworks | array | Preferred card networks (e.g., ["visa", "mastercard"]). |
20+
| customerId | string | Stripe customer ID (for returning customers). |
21+
| customerEphemeralKeySecret | string | Ephemeral key for the customer. |
22+
| returnURL | string | Return URL after payment. |
23+
| primaryButtonLabel | string | Label for the primary button. |
24+
| applePay | object | Apple Pay configuration. [see properties](#propertiesapplepay) |
25+
| googlePay | object | Google Pay configuration. [see properties](#propertiesgooglepay) |
26+
| style | string | Payment sheet style: 'light', 'dark', or 'system'. |
27+
| billingDetails | object | Billing details for the payment. [see properties](#propertiesbillingdetails) |
28+
29+
#### properties.configuration.applePay
30+
31+
| Property | Type | Description |
32+
| :------------------ | :----- | :------------------------------- |
33+
| merchantCountryCode | string | Apple Pay merchant country code. |
34+
35+
#### properties.configuration.googlePay
36+
37+
| Property | Type | Description |
38+
| :------------------ | :------ | :-------------------------------------- |
39+
| merchantCountryCode | string | Google Pay merchant country code. |
40+
| testEnv | boolean | Enable test environment for Google Pay. |
41+
42+
#### properties.configuration.billingDetails
43+
44+
| Property | Type | Description |
45+
| :------- | :----- | :----------------------------------------------------- |
46+
| email | string | Customer email address. |
47+
| phone | string | Customer phone number. |
48+
| name | string | Customer name. |
49+
| address | object | Customer address. [see properties](#propertiesaddress) |
50+
51+
#### properties.configuration.billingDetails.address
52+
53+
| Property | Type | Description |
54+
| :--------- | :----- | :--------------- |
55+
| city | string | City name. |
56+
| country | string | Country code. |
57+
| line1 | string | Address line 1. |
58+
| line2 | string | Address line 2. |
59+
| postalCode | string | Postal/ZIP code. |
60+
| state | string | State/Province. |
61+
62+
### Example
63+
64+
Here's a basic example of how to implement Stripe payments in your Ensemble app:
65+
66+
```yaml
67+
View:
68+
header:
69+
title: Payment Example
70+
body:
71+
Column:
72+
styles:
73+
padding: 24
74+
gap: 16
75+
children:
76+
- Text:
77+
text: Complete your purchase
78+
styles:
79+
fontSize: 18
80+
fontWeight: bold
81+
- Text:
82+
text: Total: $29.99
83+
styles:
84+
fontSize: 16
85+
- Button:
86+
label: Pay with Stripe
87+
onTap:
88+
showPaymentSheet:
89+
clientSecret: ${paymentIntentClientSecret}
90+
configuration:
91+
merchantDisplayName: "My Store"
92+
style: "system"
93+
primaryButtonLabel: "Pay $29.99"
94+
onSuccess:
95+
showToast:
96+
message: "Payment successful!"
97+
onError:
98+
showToast:
99+
message: "Payment failed or cancelled"
100+
```
101+
102+
### Advanced Configuration Example
103+
104+
```yaml
105+
showPaymentSheet:
106+
clientSecret: ${paymentIntentClientSecret}
107+
configuration:
108+
merchantDisplayName: "Premium Store"
109+
preferredNetworks: ["visa", "mastercard", "amex"]
110+
customerId: ${stripeCustomerId}
111+
customerEphemeralKeySecret: ${ephemeralKeySecret}
112+
returnURL: "myapp://payment-return"
113+
primaryButtonLabel: "Complete Payment"
114+
style: "dark"
115+
applePay:
116+
merchantCountryCode: "US"
117+
googlePay:
118+
merchantCountryCode: "US"
119+
testEnv: true
120+
billingDetails:
121+
email: ${userEmail}
122+
name: ${userName}
123+
address:
124+
city: ${userCity}
125+
country: "US"
126+
line1: ${userAddress}
127+
postalCode: ${userPostalCode}
128+
state: ${userState}
129+
onSuccess:
130+
showToast:
131+
message: "Payment successful!"
132+
onError:
133+
showToast:
134+
message: "Payment failed"
135+
```
136+
137+
### Error Handling
138+
139+
The `showPaymentSheet` action provides error handling through the `onError` callback. Common failure scenarios include:
140+
141+
- User cancels the payment
142+
- Invalid payment method
143+
- Insufficient funds
144+
- Network connectivity issues
145+
- Invalid payment intent
146+
147+
### Testing
148+
149+
For testing, use Stripe's test mode with test card numbers:
150+
151+
- **Success**: 4242 4242 4242 4242
152+
- **Decline**: 4000 0000 0000 0002
153+
- **Requires Authentication**: 4000 0025 0000 3155
154+
155+
### Complete Example
156+
157+
```yaml
158+
View:
159+
header:
160+
title: Checkout
161+
body:
162+
Column:
163+
styles:
164+
padding: 24
165+
gap: 16
166+
children:
167+
- Text:
168+
text: Order Summary
169+
styles:
170+
fontSize: 18
171+
fontWeight: bold
172+
- Text:
173+
text: |
174+
Product: Premium Widget
175+
Quantity: 1
176+
Total: $29.99
177+
- Button:
178+
label: Pay $29.99
179+
styles:
180+
backgroundColor: 0xff6772E5
181+
color: white
182+
onTap:
183+
showPaymentSheet:
184+
clientSecret: ${paymentIntentClientSecret}
185+
configuration:
186+
merchantDisplayName: "Widget Store"
187+
style: "system"
188+
primaryButtonLabel: "Pay $29.99"
189+
billingDetails:
190+
email: ${userEmail}
191+
name: ${userName}
192+
onSuccess:
193+
navigateScreen:
194+
name: OrderConfirmation
195+
inputs:
196+
orderId: ${orderId}
197+
onError:
198+
showDialog:
199+
widget:
200+
Column:
201+
styles:
202+
gap: 16
203+
padding: 20
204+
children:
205+
- Text:
206+
text: Payment Failed
207+
styles:
208+
fontSize: 18
209+
fontWeight: bold
210+
- Text:
211+
text: "There was an issue processing your payment. Please try again or contact support."
212+
- Button:
213+
label: Try Again
214+
onTap:
215+
dismissDialog:
216+
```
217+
218+
This implementation provides a complete Stripe payment flow with proper error handling and user feedback.

‎pages/payments/_meta.json‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
{
2+
"stripe": {
3+
"title": "Stripe Integration"
4+
},
5+
"stripe-example": {
6+
"title": "Stripe Example"
7+
}
8+
}

0 commit comments

Comments
 (0)