Quick Start: Your First Payment
This guide walks you through creating a complete payment flow from merchant registration to payment completion. You’ll learn how to use Payment Intents to create a secure, hosted checkout experience for your customers.Overview: Payment Intent Flow
Prerequisites
Before you start, you’ll need:API Endpoint
Test Card
Step 1: Register Your Account
First, create a user account to access the platform.Register User
Expected Response (201 Created)
Expected Response (201 Created)
Common Errors
Common Errors
Step 2: Login & Get Access Token
Login to receive a JWT access token for API authentication.Login
Expected Response (200 OK)
Expected Response (200 OK)
access_token value. You’ll need it for all subsequent API calls.Example: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...Step 3: Create a Merchant Account
Create a merchant profile to start accepting payments.Create Merchant
Expected Response (201 Created)
Expected Response (201 Created)
id value from the response. You’ll need it to generate API keys.Example: 550e8400-e29b-41d4-a716-446655440000Step 4: Generate API Key
Create an API key to authenticate payment requests from your server.Create API Key
Expected Response (201 Created)
Expected Response (201 Created)
Step 5: Create a Payment Intent
Now you’re ready to create your first payment! A Payment Intent represents a customer’s payment session.Create Payment Intent
Expected Response (201 Created)
Expected Response (201 Created)
Understanding the Response
Payment Intent ID
id: Unique identifier for this payment sessionUse this to check payment status or cancel the intent.Client Secret
client_secret: Browser-safe authentication tokenInclude this in the checkout URL to authenticate the customer’s session securely.Checkout URL
checkout_url: Ready-to-use checkout page URLPre-built URL with payment intent ID and client secret included. Simply redirect your customer to this URL.Expiration
expires_at: Automatic expiration timestamp (1 hour)Payment intents expire automatically for security. Customer must complete payment before this time.Step 6: Redirect Customer to Checkout
The payment intent response includes a ready-to-usecheckout_url. Simply redirect your customer to this URL.
Option 1: Use the checkout_url (Recommended)
The response includes a pre-built checkout URL with all required parameters:Option 2: Build the URL manually
Implementation Examples
- HTML (Redirect)
- Node.js/Express
- Python/Flask
Step 7: Customer Completes Payment
Your customer will see a secure checkout page where they can enter their card details.
What Happens on the Checkout Page
Payment Intent Validation
client_secret to ensure the session is valid and not expired.Customer Enters Card Details
- Card number (e.g., 4242 4242 4242 4242)
- Cardholder name
- Expiry date (MM/YY)
- CVV (3 digits)
Payment Processing
- Card data sent to Payment API (secured by client_secret)
- Card tokenized (never stored in plain text)
- Transaction authorized or declined
- Payment intent status updated
Automatic Redirect
- ✅ Success: Redirects to
success_urlwith payment intent ID - ❌ Declined: Shows error, allows retry (max 5 attempts)
- ⏱️ Expired: Redirects to
cancel_url
Test Cards for Development
✅ Successful Payment
❌ Declined - Insufficient Funds
❌ Declined - Expired Card
❌ Declined - CVV Mismatch
- Use any future expiry date (e.g., 12/2027)
- Use any cardholder name
- For Mastercard, use: 5555 5555 5555 4444 (approved)
Step 8: Handle Success Redirect
After successful payment, the customer is redirected back to yoursuccess_url.
Success URL Parameters
{CHECKOUT_SESSION_ID} placeholder)Verify Payment Status
Always verify the payment status on your server (don’t trust client-side redirects alone).Expected Response (200 OK)
Expected Response (200 OK)
Implementation Example
Step 9: Receive Webhook Notifications (Optional)
For asynchronous payment confirmation, configure webhooks to receive real-time updates.Configure Webhook URL
First, set your webhook URL in merchant settings:Webhook Payload
When payment status changes, you’ll receive a POST request:Verify Webhook Signature
🎉 Congratulations!
You’ve successfully:✅ Registered an account
✅ Created a merchant
✅ Generated API key
✅ Created payment intent
✅ Processed payment
✅ Verified payment
Next Steps
Auth API Reference
Merchant API Reference
Payment API Reference
Checkout Integration
Common Issues
400 Bad Request - Invalid Amount
400 Bad Request - Invalid Amount
- ❌ Wrong:
"amount": 99.99 - ✅ Correct:
"amount": 9999(represents $99.99)
403 Forbidden - Client Secret Invalid
403 Forbidden - Client Secret Invalid
- Ensure you’re using the correct
client_secretfrom the payment intent response - Check the payment intent hasn’t expired (1 hour limit)
- Verify the payment intent ID in the URL matches the client secret
422 Unprocessable Entity - Payment Already Completed
422 Unprocessable Entity - Payment Already Completed
- Check payment intent status first:
GET /payment-intents/:id - If status is
authorized, payment is already complete - Create a new payment intent for a new payment
Payment Declined
Payment Declined
- Use approved test card: 4242 4242 4242 4242
- Check you’re using a future expiry date
- See test cards section for specific decline scenarios
Need Help?
GitHub Issues
Email Support
Ready to integrate? Head to the API Reference to explore all available endpoints!