Configure payment gateways

Accept Payments from Users#

Each payment gateway has its own method for handling payments and refunds. The Platfone NodeJS 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#

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 stores a record in the tn_payments table in the MySQL database. Each webhook event triggers logic that synchronizes the balance with the Platfone Retail API and marks the record as processed.

Stripe#

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

Basic Process Overview:

• The client app requests a payment intent from the NodeJS backend endpoint.
• The client app sends the payment intent to Stripe.
• Stripe processes the payment and sends a webhook event to the backend.
• The backend verifies the event signature, records the transaction in the database, and updates the customer balance.

Configuration:

1. Set STRIPE_ENABLE=true in your environment to enable Stripe payments.
2. Obtain the Stripe webhook URL from your deployment and copy it.
3. In the Stripe Dashboard, add a new endpoint with the copied URL and subscribe to these events:
   • payment_intent.amount_capturable_updated
   • charge.refunded
   • review.closed
4. Copy the signing secret from Stripe and set it as STRIPE_WEBHOOK_SECRET in your environment.
5. In the Stripe Dashboard, retrieve your Publishable and Secret keys and configure STRIPE_PUBLISHABLE_KEY and STRIPE_SECRET_KEY.
6. For client-side instructions, refer to the example apps:
   • iOS example app Stripe configuration
   • Android example app Stripe configuration
   • Web example app Stripe configuration

PayPal#

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

Basic Process Overview:

1. The client app integrates PayPal’s JavaScript SDK to render payment buttons.
2. The client requests order creation from the backend, which calls PayPal’s Orders API.
3. The client approves the payment via PayPal SDK, then captures the order via the backend.
4. PayPal sends a PAYMENT.CAPTURE.REFUNDED webhook event for refunds.

Configuration:

1. Set PAYPAL_ENABLE=true in your environment to enable PayPal.
2. In the PayPal Developer Dashboard, create a REST API app and obtain your Client ID and Secret.
3. Copy the PayPal webhook URL from your deployment and add a new webhook under your app settings. Subscribe to PAYMENT.CAPTURE.REFUNDED.

Cryptomus#

The Platfone NodeJS Backend supports payments via the Cryptomus cryptocurrency gateway.

Basic Process Overview:

1. The client app requests a payment invoice via the backend, which calls Cryptomus API.
2. The backend returns an invoice URL or payment details.
3. Cryptomus sends a webhook event on payment completion or refund.

Configuration:

1. Set CRYPTOMUS_ENABLE=true in your environment.
2. Sign up at Cryptomus and create a merchant project to obtain API credentials.
3. Copy the Cryptomus webhook URL and configure it in your Cryptomus merchant dashboard.

Apple App Store#

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

Basic Process Overview:

• The client app sends purchase receipts to the backend for verification and record creation.
• Refund notifications (REFUND) are sent via App Store Server Notifications.

Configuration:

1. Set APPSTORE_ENABLE=true, APPSTORE_BUNDLE_ID, APPSTORE_APP_ID, APPSTORE_ENVIRONMENT, and APPSTORE_SHARED_SECRET in your environment.
2. Copy the App Store Server Notification URL from your deployment and configure it in App Store Connect under App Information > Server Notifications.

Google Play Store#

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

Basic Process Overview:

• The client app sends purchase tokens to the backend for verification and record creation.
• Real-time Developer Notifications are delivered via Google Pub/Sub webhooks.

Configuration:

1. Set GOOGLE_PLAY_ENABLE=true, GOOGLE_PLAY_PACKAGE_NAME, and provide a service account JSON with permissions for real-time notifications.
2. In the Google Play Console, enable Real-time developer notifications and configure your Pub/Sub endpoint.
3. Grant the Pub/Sub topic permission to [email protected] with the Pub/Sub Publisher role.

Adding Custom Payment Gateways#

To add a custom payment gateway, implement a webhook handler in your code that:

1. Verifies the incoming request.

2. Records a row in the tn_payments table with at least the following fields:

   • id: Unique payment identifier from the gateway.
   • amount: Transaction amount in cents (use negative for refunds).
   • customer_id: User identifier in your system.
   • gateway: Name of the payment gateway.

   then invoke insertPaymentRecord(paymentData) to save the payment record.

   const paymentData: PaymentData = {
      id: payment.paymentId,
      amount: payment.amount * -1,
      gateway: PaymentGateway.myGateway,
      customerId: payment.uid
   }
   await this.insertPaymentRecord(paymentData)

3. Deploy or restart your backend to apply the changes.