Platfone Docs

Configure payment gateways

Accept Payments from Users

Each payment gateway has its own method for handling payments and refunds. The Platfone Firebase Backend provides a unified interface for managing payments and refunds from multiple payment gateways. It includes support for popular gateways and can be extended to support additional ones.

Supported Payment Gateways

The Platfone Firebase Backend currently supports the following payment gateways:

  1. Stripe
  2. PayPal
  3. Cryptomus
  4. Apple App Store
  5. Google Play Store

How It Works

When a user makes a payment, the backend verifies the transaction and adds a document to the payments collection in the Firestore database. This document contains payment information such as the unique payment ID, Firebase user ID, payment gateway, payment amount, and payment status. Each update to a Firestore document triggers a function that synchronizes the balance with Platfone Retail API and marks the document as processed. A positive amount increases the balance, while a negative amount decreases it (for refunds).

Stripe

The Platfone Firebase Backend supports payments via the Stripe payment gateway.

Basic Process Overview:

  • The app requests a payment intent from the Firebase Cloud Function.
  • The app sends the payment intent to Stripe.
  • Stripe processes the payment and sends a webhook event to the Firebase Cloud Function.
  • The payment is verified and added to the Firestore database with either a positive amount (for payments) or a negative amount (for refunds).

Configuration:

  1. Choose Yes when prompted by the installer to enable Stripe.
  2. Copy the Stripe webhook URL as printed by the installer.
  3. Set up the Stripe webhook:
    • Go to the Stripe Dashboard and add a new endpoint.
    • Set the endpoint URL to the copied Stripe URL from the installer.
    • Select the payment_intent.amount_capturable_updated, charge.refunded and review.closed events, then click “Add endpoint” to save.
    • Click “Reveal” to get the signing secret, which you’ll set as the STRIPE_WEBHOOK_SECRET during the Platfone Firebase Backend installation.
  4. Get your Stripe API keys:
    • Go to Stripe Dashboard to get your Publishable key and Secret key. You will be prompted for them during the backend installation.
  5. For instructions on configuring Stripe payments in your app, refer to the example apps:

PayPal

The Platfone Firebase Backend supports payments via the PayPal Advanced Checkout integration.

Basic Process Overview:

  1. Client-Side Integration:

    • The app integrates PayPal’s JavaScript SDK to render PayPal buttons and card fields.
    • Users interact with these components to initiate payments.

  2. Server-Side Order Creation:

    • The app sends a request to a Firebase Cloud Function to create an order.
    • The Cloud Function utilizes PayPal’s Orders API to create the order and returns an orderID to the client.

  3. Payment Approval:

    • The client uses the orderID to approve the payment through PayPal’s SDK components.

  4. Order Capture:

    • Upon approval, the client notifies the Firebase Cloud Function to capture the order.
    • The Cloud Function captures the payment via PayPal’s Orders API and updates the Firestore database with the transaction details, recording positive amount.

  5. Webhook Notification:

    • PayPal sends a webhook PAYMENT.CAPTURE.REFUNDED event to a designated Firebase Cloud Function upon payment refund.
    • The Cloud Function verifies the event and updates the Firestore database with the transaction details, recording negative amount.

Configuration:

  1. Enable PayPal Integration:

    • During the backend installation, choose Yes when prompted to enable PayPal.

  2. Obtain PayPal API Credentials:

    • Log in to the PayPal Developer Dashboard.
    • Navigate to Apps & Credentials and create a new REST API app.
    • Retrieve your Client ID and Secret, which will be required during the backend installation.

  3. Set Up Webhook:

    • Copy the PayPal webhook URL provided by the installer.
    • In the PayPal Developer Dashboard, go to Webhooks under your application settings.
    • Add a new webhook endpoint with the copied URL.
    • Subscribe to the following events:
      • “Payment capture refunded” PAYMENT.CAPTURE.REFUNDED (for refunds)
    • Save the webhook configuration.

Cryptomus

The Platfone Firebase Backend supports payments via the Cryptomus cryptocurrency payment gateway.

Basic Process Overview:

  1. Client-Side Integration:

    • The app integrates Cryptomus’s payment interface to facilitate cryptocurrency transactions.
    • Users initiate payments through the app, selecting their preferred cryptocurrency.

  2. Server-Side Invoice Creation:

    • The app sends a request to a Firebase Cloud Function to create a payment invoice.
    • The Cloud Function utilizes Cryptomus’s API to generate the invoice and returns the payment details to the client.

  3. Payment Processing:

    • Users complete the payment using the provided cryptocurrency details.
    • Cryptomus processes the payment and confirms the transaction.

  4. Webhook Notification:

    • Cryptomus sends a webhook event to a designated Firebase Cloud Function upon payment completion.
    • The Cloud Function verifies the payment and updates the Firestore database with the transaction details, recording positive amounts for payments and negative amounts for refunds.

Configuration:

  1. Enable Cryptomus Integration:

    • During the backend installation, choose Yes when prompted to enable Cryptomus.

  2. Obtain Cryptomus API Credentials:

    • Sign up on the Cryptomus website.
    • Create a new merchant project to manage your payments.
    • Generate your API keys from the merchant dashboard; these will be required during the backend installation.

  3. Set Up Webhook:

    • Copy the Cryptomus webhook URL provided by the installer.
    • In your Cryptomus merchant dashboard, navigate to the webhook settings.
    • Add a new webhook endpoint with the copied URL.
    • Configure the webhook to listen for relevant events, such as payment completions and refunds.
    • Save the webhook configuration.

  4. Client-Side Integration:

    • Integrate Cryptomus’s payment interface into your app to facilitate cryptocurrency transactions.
    • Ensure the client-side logic handles the initiation of payments and interacts with the Firebase Cloud Functions as needed.

For a visual walkthrough, you might find the following video helpful: https://www.youtube.com/watch?v=x71wO2kDRiI

Apple App Store

The Platfone Firebase Backend supports in-app purchases through the Apple App Store.

Basic Process Overview:

  • The payment transaction provided by the app is verified and added to the Firestore database with a positive amount.
  • When a REFUND Apple App Store notification is received, it is verified and added to the Firestore database with a negative amount.

Configuration:

  1. Choose Yes when prompted by the installer to enable Apple App Store in-app purchases.
  2. Copy the Apple App Store webhook URL as printed by the installer.
  3. Set up the notification URL in App Store Connect:
    • Go to App Store Connect.
    • In the App Information section, add the copied webhook URL as the notification URL.
  4. For instructions on configuring in-app purchases in your app, refer to the Apple in-app purchases section of the iOS example app README.

Google Play Store

The Platfone Firebase Backend supports in-app purchases through the Google Play Store.

Basic Process Overview:

  • The payment transaction provided by the app is verified and added to the Firestore database with a positive amount.
  • When a ONE_TIME_PRODUCT_REFUNDED Google Play Store notification is received, it is verified and added to the Firestore database with a negative amount.

Configuration:

  1. Choose Yes when prompted by the installer to enable Google Play in-app purchases.

  2. Go to the Google Play Console and select your app.

  3. Configure products under Products -> In-app products.

  4. Create a service account key:

    1. Go to the Google Cloud Console.
    2. Select the project linked to your Play Store app, then click Create Service Account.
    3. Enter a name and description for the service account (e.g., Platfone-firebase-backend), then click Create.
    4. Click Create Key and select JSON as the key type.
    5. Save the JSON file as google-play-service-account.json.

  5. Grant the service account access to app financial data:

    1. In the Google Play Console, go to Users and permissions and click Invite new users.
    2. Paste the email address from the service account JSON file and select Finance as the role.
    3. In the app permission tab, click Add app and select your app.
    4. Allow the service account to access the financial data of the app.
    5. Click Invite user.

  6. Configure a Google Pub/Sub topic:

    1. Go to the Google Cloud Console.
    2. Click on Create a topic and enter a Topic ID (a name for the topic).
    3. Click Create.
    4. Choose Subscription for the created topic and click EDIT.
    5. Change Delivery type to Push and paste the webhook URL from the installer into the Endpoint URL.
    6. Change the Retry policy to Retry after exponential backoff delay.
    7. Click Update.

  7. Grant the Google Play Store access to the Google Pub/Sub topic:

    1. In the Google Cloud Console, select the topic you created.
    2. Click on ADD PRINCIPAL.
    3. In the new principal field, enter [email protected].
    4. Select the Role as Pub/Sub Publisher.

  8. Configure Google Play Store notifications:

    1. In the Google Play Console, select your app.
    2. Under the Monetization setup section in Monetize, check Enable real-time notifications.
    3. Fill in the Topic name with the name of the topic you created in the Google Cloud Console.
    4. Set Notification content to include Subscriptions, voided purchases, and all one-time products.
    5. Click Save changes.

  9. Continue with the Platfone Firebase Backend installation and provide:

    1. The path to the service account key file (google-play-service-account.json).
    2. The Google Play package name of your app.
    3. JSON object with Product IDs and amount to be topped up. An example JSON is printed by the backend installer.

Adding Custom Payment Gateways

To add a custom payment gateway, you need to:

  1. Add a new function similar to existing in purchases.ts that will:

    1. Handle incoming payment notification from custom payment gateway

    2. Verify the payment and its authenticity

    3. Add a document to the payments collection in Firestore (governed by FIRESTORE_PAYMENTS_COLLECTION variable) with at least the following fields:

      • id: Unique ID for the payment. This can be the payment ID from the payment gateway.
      • customer_id: Firebase UID of the user making the payment.
      • amount: The amount of the payment in USD cents. Use a negative amount for refunds.
      • gateway: The name of the payment gateway.
      • is_synced: Should be set to false. A boolean flag to indicate if the payment has been synced with the Retail API.

      Field constraints can be found in the Create customer transaction endpoint of the Retail API.

  2. The function should be added to the index.js.

  3. Add the necessary configuration variables to the installer/src/params.yaml file or .env file.

  4. Re-run the installer to deploy the new function.

Prev
Prepare Firebase Project
Next
Deploy Platfone Firebase Backend