> ## Documentation Index
> Fetch the complete documentation index at: https://docs.9pic.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# PayMongo Setup

> Add PayMongo credentials to 9Pic Checkout and prepare a PHP event for test or live payments.

<Warning>
  9Pic Checkout is a **Beta**, **Enterprise plan** feature. Only team admins can add or change a PayMongo configuration.
</Warning>

## Overview

PayMongo collects payments for 9Pic Checkout in the Philippines. Add one PayMongo configuration for your organisation, then assign it to the event that will sell packages in **PHP**.

You need a **secret key** from the PayMongo Dashboard. Use a test key while you check the buyer journey, and a live key only when the event is ready to accept real payments.

## Before You Start

| Requirement                    | Why it matters                                                                              |
| ------------------------------ | ------------------------------------------------------------------------------------------- |
| **PayMongo merchant access**   | You need permission to view **Developers -> API keys** in the PayMongo Dashboard.           |
| **Correct mode**               | Use a `sk_test_…` key for setup checks. Use a separate `sk_live_…` key for public checkout. |
| **A team admin account**       | Only team admins can open and manage Payment Configuration.                                 |
| **An Enterprise organisation** | Payment Configuration and 9Pic Checkout are available on the Enterprise plan.               |
| **PHP packages**               | Events that use PayMongo can only sell packages priced in PHP.                              |

<Warning>
  Do not share the secret key in email, chat, task tickets, screenshots, frontend code, or a public repository. If you think it has been exposed, create a new key in PayMongo and update the configuration in 9Pic.
</Warning>

## Get Your PayMongo Secret Key

<Steps>
  <Step title="Open API keys in PayMongo">
    Sign in to the PayMongo Dashboard and open **Developers -> API keys**.
  </Step>

  <Step title="Copy the secret key for the mode you need">
    Copy the **secret key** for test mode or live mode. Test keys start with `sk_test_`. Live keys start with `sk_live_`.
  </Step>

  <Step title="Store the key safely">
    Keep the key in your organisation's approved password manager until you add it to 9Pic. Do not paste it into a buyer-facing website or app.
  </Step>
</Steps>

![PayMongo Dashboard Developers page showing masked Live and Test API Secret Key and Public Key fields](https://assets.9pic.ai/docs/dashboard-guide/payment-config/paymongo-api-keys.webp)

<Info>
  Need help finding the keys in PayMongo? Use the [PayMongo API keys guide](https://docs.paymongo.com/docs/api-keys) or contact the PayMongo team that provisioned your merchant account.
</Info>

## Add PayMongo to 9Pic

<Steps>
  <Step title="Open Payment Config">
    In the dashboard sidebar, select **Payment Config**.
  </Step>

  <Step title="Start a new gateway">
    In **Payment Gateway Configurations**, click **Add Gateway**, then select **PayMongo**.
  </Step>

  <Step title="Name the configuration">
    Enter an optional **Label** that makes the configuration easy to recognise, such as `PayMongo Test` or `PayMongo Live Philippines`.
  </Step>

  <Step title="Enter an optional Account ID">
    **Account ID** is optional for PayMongo. Use it only if your team wants a reminder of which PayMongo account the key belongs to.
  </Step>

  <Step title="Enter the secret key">
    Paste the key into **PayMongo Secret Key**. This required value is stored as a protected credential for your organisation.
  </Step>

  <Step title="Create the gateway">
    Click **Create Gateway**. The new PayMongo configuration appears in the organisation's gateway list.
  </Step>
</Steps>

## Assign PayMongo to an Event

<Steps>
  <Step title="Open the event Checkout configuration">
    Open the event, then open its **Checkout** configuration.
  </Step>

  <Step title="Assign the PayMongo configuration">
    In the **Payment gateway** card, select **Assign** (or **Edit** if a gateway is already assigned), choose the PayMongo configuration, and save.
  </Step>

  <Step title="Decide whether buyers pay provider fees">
    When PayMongo is selected, the **Pass on fees** switch is available. Leave it off to keep the listed package price as the charged amount. Turn it on if buyers should pay the payment-provider fee on the PayMongo page. Package prices stay the same; the total shown on the payment page may increase depending on the payment method.
  </Step>

  <Step title="Set package prices in PHP">
    Create or update Checkout packages in **PHP**. Other currencies cannot be used with PayMongo. Each package must be at least PHP 1.00.
  </Step>

  <Step title="Publish and test">
    Publish the packages and run a complete buyer journey with a `sk_test_` configuration before you switch the event to a live key.
  </Step>
</Steps>

<Warning>
  Replacing the assigned gateway while Checkout is live pauses Checkout first. Confirm the new configuration and package currency before you publish it again.
</Warning>

## Verify the Setup

| Check                    | What to confirm                                                                   |
| ------------------------ | --------------------------------------------------------------------------------- |
| **Correct mode**         | Test events use a `sk_test_` key; public checkout uses a `sk_live_` key.          |
| **Payment page opens**   | A buyer can continue from 9Pic to the PayMongo hosted payment page.               |
| **Payment completes**    | A successful test payment returns to 9Pic and marks the order paid.               |
| **Currency is PHP**      | Package prices and the PayMongo payment page both show PHP.                       |
| **Buyer methods appear** | Card, GCash, Maya, GrabPay, and QR Ph appear as enabled on your PayMongo account. |
| **Cancellation works**   | Cancelling returns the buyer to 9Pic without marking the order paid.              |

## Troubleshooting

<AccordionGroup>
  <Accordion title="9Pic says the PayMongo secret key is not configured.">
    Edit the PayMongo configuration in **Payment Config** and confirm that **PayMongo Secret Key** has a value. Then assign that configuration on the event's **Payment gateway** card.
  </Accordion>

  <Accordion title="My test key does not work for a public event.">
    A `sk_test_` key is only for setup checks and cannot complete public checkout. Add or update the configuration with a `sk_live_` key from PayMongo live mode.
  </Accordion>

  <Accordion title="I cannot select PHP, or another currency is blocked.">
    Events assigned to PayMongo can only sell PHP packages. Choose PHP, or assign a gateway that supports the currency you need.
  </Accordion>

  <Accordion title="The buyer does not see GCash, Maya, GrabPay, or QR Ph.">
    9Pic requests those methods when they are available on your PayMongo account. Enable the method in PayMongo, then retry a test purchase.
  </Accordion>

  <Accordion title="The payment page total is higher than the package price.">
    Check whether **Pass on fees** is on for the event. When that switch is on, buyers pay the payment-provider fee and the PayMongo page total can be higher than the listed package price.
  </Accordion>
</AccordionGroup>

## Next Steps

<CardGroup cols={2}>
  <Card title="Payment Config" icon="wallet" href="/dashboard-guide/payment-config">
    Manage the payment gateways saved for your organisation.
  </Card>

  <Card title="Checkout Setup" icon="gear" href="/dashboard-guide/checkout/configuration">
    Assign a gateway, publish packages, and enable Checkout for an event.
  </Card>
</CardGroup>