Skip to main content

Payments

Overview​

The Payments module is where you configure how your customers pay for their orders at checkout.

Orbit Resolve ships with three built-in payment methods:

  1. Cash on Delivery (COD): The customer pays in physical cash when the order arrives.
  2. Razorpay: A popular online payment provider for Indian businesses (supports UPI, domestic cards, net banking).
  3. Stripe: A global online payment provider (supports international cards, Apple Pay, Google Pay, etc.).

By adding your payment provider credentials to this page, you enable these methods for your customers globally across your organization.

Before You Start​

  • You must have Organization Administrator permissions to access this page.
  • To accept online payments, you must first create an account directly with Razorpay or Stripe. Orbit Resolve simply connects to them.

Accessing Payments​

Navigate to: Cockpit → Settings (Organization Settings) → Finance → Payments

The Payments dashboard showing the three available payment gateways.

Choosing a Payment Method​

Which payment methods should you enable? You can enable one, two, or all three depending on your business needs.

Your RequirementRecommended MethodWhat You Need
I want customers to pay cash when the physical product arrives.Cash on Delivery (COD)No setup required.
My customers are in India and want to pay via UPI or local bank accounts.RazorpayA Razorpay Merchant Account (INR currency).
My customers are international and want to pay via Credit Cards (Visa/Mastercard).StripeA Stripe Merchant Account.

Understanding Test and Live Modes​

Orbit Resolve separates your payment configuration into two entirely independent tabs: Test and Live.

Test and Live are separate configurations. You can safely experiment in Test mode without breaking your Live checkout.

  • Test (Sandbox): Used during setup. It allows you to place fake orders using "Test Credit Cards" to ensure your checkout works perfectly without actually moving any real money.
  • Live: Used for real customers. This charges real credit cards and deposits real money into your bank account.

Crucial Rule: You must get Test credentials from Razorpay/Stripe to put in the Test tab, and Live credentials to put in the Live tab. Never mix them up!

Setting Up Payments for the First Time​

Here is the general workflow you will follow to get online payments working:

  1. Start in Test Mode: Ensure the "Test" tab is selected in Orbit Resolve.
  2. Get Credentials: Log into your payment provider (Razorpay or Stripe) and copy your Test API Keys.
  3. Configure the Webhook: Tell your payment provider how to talk back to Orbit Resolve so it knows when a payment succeeds.
  4. Enter Credentials: Paste everything into Orbit Resolve and flip the Enabled switch to ON.
  5. Test a Fake Order: Place an order on your website using a fake test card to verify everything works.
  6. Go Live: Once you are confident, switch everything to "Live Mode" for real customers.

Below are the exact steps for each provider.

Setting Up Cash on Delivery (COD)​

Cash on Delivery is the simplest method because no external payment provider is involved.

To enable COD:

  1. Locate the Cash on Delivery card.
  2. Check the Enabled box.
  3. Click Save changes at the bottom of the card.

What happens at checkout? Customers will see "Cash on Delivery" as an option. When they place an order, it will immediately be accepted, but its payment status will be marked as PENDING. Once your delivery driver collects the cash, an administrator must manually open the order in Orbit Resolve and mark the payment as PAID.

Setting Up Razorpay​

Use Razorpay if you primarily process transactions in Indian Rupees (INR).

The Razorpay credential form. You must provide a Key ID, Key Secret, and Webhook Secret.

Step 1: Get Test Credentials​

  1. Log into your Razorpay Dashboard. Ensure you are in Test Mode (look for the toggle at the top of their screen).
  2. Go to Settings (gear icon) → API Keys → Generate Test Key.
  3. Razorpay will show you a Key ID (rzp_test_...) and a Key Secret.
    • ⚠️ Copy the Key Secret immediately. Razorpay will never show it to you again!

Step 2: Configure the Webhook​

A Webhook is how Razorpay silently tells Orbit Resolve, "Hey, that customer just successfully paid!" after they leave the checkout screen.

  1. In the Razorpay Dashboard, go to Settings → Webhooks → + Add New Webhook.
  2. Webhook URL: Look at the Setup Guide inside Orbit Resolve (click the button in the top right). Copy the exact Razorpay Webhook URL it provides you.
  3. Secret: Type a random password of your own choosing here. Copy this down! This is your Webhook Secret.
  4. Active Events: Check only these three boxes: payment.captured, payment.authorized, payment.failed.
  5. Click Create Webhook.

Step 3: Enter Credentials in Orbit Resolve​

  1. In Orbit Resolve, locate the Razorpay card. Make sure the Test tab is selected.
  2. Click Enter credentials.
  3. Paste the Key ID, Key Secret, and the Webhook Secret you created.
  4. Check the Enabled box.
  5. Click Save changes.

Setting Up Stripe​

Use Stripe if you want to accept global credit cards in various currencies.

The Stripe credential form. You must provide a Secret Key and Webhook Secret.

Step 1: Get Test Credentials​

  1. Log into your Stripe Dashboard. Ensure you have Test mode turned on (look for the orange banner or toggle).
  2. Open the Workbench (or go to Developers → API keys).
  3. Find your Publishable key (pk_test_...) and your Secret key (sk_test_...).
    • ⚠️ You may need to click "Reveal test key" to see the secret key. Copy it immediately.

Step 2: Configure the Webhook​

A Webhook tells Orbit Resolve when a Stripe checkout session completes successfully.

  1. In the Stripe Workbench, go to the Webhooks tab.
  2. Click + Add destination and select Webhook endpoint.
  3. Endpoint URL: Look at the Setup Guide inside Orbit Resolve (click the button in the top right). Copy the exact Stripe Webhook URL it provides you.
  4. Select Events: Search for and select only these three events:
    • checkout.session.completed
    • checkout.session.async_payment_failed
    • checkout.session.expired
  5. Click Create destination.
  6. On the next screen, look for Signing secret and click Reveal. Copy this value (whsec_...). This is your Webhook Secret.

Step 3: Enter Credentials in Orbit Resolve​

  1. In Orbit Resolve, locate the Stripe card. Make sure the Test tab is selected.
  2. Click Enter credentials.
  3. Paste the Secret Key, Publishable Key, and the Webhook Secret.
  4. Check the Enabled box.
  5. Click Save changes.

Need a quick refresher? Click "Setup guide" in the top right corner at any time to open this helpful drawer.

Testing Checkout (Sandbox Flow)​

Never go live without testing! To test your setup:

  1. Visit your store checkout page and add ?payment_mode=test to the end of the URL (e.g., https://yourstore.com/checkout?payment_mode=test). This forces the checkout to use the sandbox credentials you just saved.
  2. Add a product to your cart and proceed to checkout.
  3. You should see your enabled payment methods (Razorpay or Stripe).
  4. Select one and use a fake test card provided by the gateway to complete the payment.
  5. You should be redirected to the "Order Success" page.

Understanding "Awaiting Payment Confirmation"​

Immediately after paying, the order success page will display an amber banner saying "Awaiting payment confirmation."

This is perfectly normal! It takes a few seconds for the Webhook to travel from the payment provider to Orbit Resolve. Once the webhook arrives, the banner will automatically disappear, and the order will be officially marked as PAID.

(If the banner stays there forever, your Webhook is broken. See Common Problems below).

Going Live​

When you are confident your test orders work flawlessly, it is time to accept real money.

  1. Go to your Razorpay or Stripe dashboard and switch to Live Mode.
  2. Generate brand new Live API Keys. (Your test keys will not work for real money).
  3. Create a brand new Live Webhook (following the exact same steps you did for the test webhook, but in Live mode) and get the new Live Webhook Secret.
  4. Go back to Orbit Resolve's Payments page.
  5. Click the Live tab on the gateway card.
  6. Click Enter credentials and paste your new Live keys.
  7. Check the Enabled box and click Save changes.

Your live checkout is now active!

Project-Level Payment Overrides​

What if your organization runs two different projects (e.g., two different storefronts) and you want money from Project B to go into a completely different bank account?

You can allow projects to override the main organization's payment configuration:

  1. On the main Organization Payments page, check the box that says Allow project override for the desired gateway (e.g., Stripe) and click Save.
  2. Now, go to the specific project's settings: Cockpit → Project → Settings (Store Settings) → Payments.
  3. You will see a button to Set project credentials.
  4. Paste the specific Stripe keys for that project's bank account there.

From now on, that specific project will use its own Stripe account, while all other projects in your organization will continue to use the default organization Stripe account.

Security and Credential Handling​

Your financial credentials are safe.

  • Encrypted at Rest: When you click "Save changes", Orbit Resolve instantly encrypts your Secret Keys using military-grade AES-256-GCM encryption before saving them to the database.
  • Never Exposed: Once saved, the server will never send your Secret Keys back to the browser in plain text. You will only ever see masked versions (e.g., sk_test_••••••••).
  • Leave Blank to Keep: If you ever need to change just one field (like your Webhook Secret), you do not need to re-type your Secret Key. Just leave the Secret Key blank, and the system will keep your old one securely stored.

Common Problems​

SymptomWhat it meansHow to fix it
Payment method doesn't appear at checkoutThe gateway is disabled, or you are looking at the wrong mode (Test vs Live).Check the "Enabled" toggle on the Payments page. Make sure you are using ?payment_mode=test if you are trying to test.
"Awaiting payment confirmation" stays foreverThe Webhook never reached Orbit Resolve, so the system doesn't know the customer paid.Log into Stripe/Razorpay and check your Webhooks settings. Ensure the URL is exactly correct and that you checked the required events.
Razorpay modal says "Authentication failed"You pasted the wrong Key ID or Key Secret.Generate new keys in the Razorpay dashboard and re-paste them into Orbit Resolve.
Stripe lands on "session expired"The customer waited longer than 24 hours to type in their card.Nothing is broken. The customer just needs to try checking out again.
Amber "Encryption key not configured" banner at the top of the pageThe backend server is missing a critical security password.You cannot fix this. Contact your DevOps/Developer team to add the PAYMENT_KEYS_ENC_KEY environment variable to the backend.

Advanced Technical Notes (For Developers)​

The following section is intended for developers integrating or troubleshooting the payments API.

API Endpoints​

  • List Configurations: GET /api/v1/org/payments/gateways
  • Upsert Configuration: POST /api/v1/org/payments/gateways
  • Project Override List: GET /api/v1/org/projects/{projectId}/payments/gateways
  • Project Override Upsert: POST /api/v1/org/projects/{projectId}/payments/gateways
  • Public Checkout Methods: GET /api/v1/public/storefront/payment-methods?org_slug=X&project_slug=Y&mode=test

Payload Structure​

Credentials are submitted as a flat JSON dictionary inside the credentials key during the POST request.

{
  "gateway_code": "stripe",
  "mode": "test",
  "is_enabled": true,
  "allow_project_override": false,
  "credentials": {
    "secret_key": "sk_test_...",
    "publishable_key": "pk_test_...",
    "webhook_secret": "whsec_..."
  }
}

Note: To preserve an existing credential during an update (e.g., changing only the webhook secret), omit the unchanged keys from the credentials dictionary entirely. Empty strings are ignored.

Mode State Management​

The UI utilizes localStorage (oo:payMode:{gateway}) to remember whether an administrator was last editing the test or live tab. This prevents frustrating tab-resets if the page reloads. However, submitting the save payload explicitly binds to the currently active tab mode.