> ## 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.

# AFS Gateway Setup

> Add AFS Gateway credentials to 9Pic Checkout and prepare an event for test or live payments.

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

## Overview

AFS Gateway uses Mastercard Hosted Checkout to collect payments for 9Pic Checkout. Add one AFS configuration for your organisation, then assign it to the event that will sell packages.

You need two values from your AFS merchant setup: a **Merchant ID** and an **API password**. The Merchant ID identifies the account; the API password is private and should be handled like a password.

TODO screenshot (Codex Chrome required): Capture the Add Payment Gateway dialog with AFS Gateway selected, using redacted placeholder credentials.

## Before You Start

| Requirement                    | Why it matters                                                                                                         |
| ------------------------------ | ---------------------------------------------------------------------------------------------------------------------- |
| **AFS merchant access**        | You need the Merchant ID and API password issued for the AFS account you will use.                                     |
| **Correct environment**        | A Merchant ID starting with `TEST` uses the AFS simulator. AFS provides a separate live Merchant ID for real payments. |
| **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.                                          |
| **Supported event currency**   | AFS package prices can use BHD, USD, AED, SAR, or QAR.                                                                 |

<Warning>
  Do not share the API password in email, chat, task tickets, screenshots, frontend code, or a public repository. If you think it has been exposed, replace it in AFS and update the configuration in 9Pic.
</Warning>

## Get Your AFS Credentials

<Frame caption="AFS Admin menu with Integration Settings highlighted">
  <img src="https://assets.9pic.ai/docs/dashboard-guide/payment-config/afs-integration-settings-menu.webp" alt="AFS admin Admin dropdown menu showing Integration Settings selected among Login and Security, Software Download, Webhook Notifications, Merchant Emails, Customer Emails, and Payment Configuration" />
</Frame>

<Steps>
  <Step title="Open your AFS merchant setup">
    Sign in to the AFS merchant administration area for the account you plan to use. Open **Admin -> Integration Settings** and find the **Integration Authentication** section.
  </Step>

  <Step title="Get the API password">
    Copy **Password 1** from the Integration Authentication section. Paste this value into the **AFS API Password** field in 9Pic. Do not copy it into a buyer-facing website or app.
  </Step>

  <Step title="Decide whether you are testing or going live">
    Use the simulator credentials while testing. A Merchant ID that begins with `TEST` is recognised as a test configuration. Use the separate live Merchant ID only when the event is ready to accept real payments.
  </Step>

  <Step title="Store the API password safely">
    Keep the password in your organisation's approved password manager until you add it to 9Pic. AFS credentials should never be added to a buyer-facing website or app.
  </Step>
</Steps>

<Frame caption="AFS Integration Settings with the API password redacted">
  <img src="https://assets.9pic.ai/docs/dashboard-guide/payment-config/afs-integration-settings.webp" alt="AFS Admin Integration Settings page showing Integration Authentication, with Password 1 redacted and Password 2 not enabled" />
</Frame>

<Info>
  Need help locating the credentials in AFS? Use the [AFS integration guide](https://afs.gateway.mastercard.com/api/documentation/integrationGuidelines/index.html?locale=en_US) or contact the AFS team that provisioned your merchant account.
</Info>

## Add AFS Gateway 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 **AFS Gateway**.
  </Step>

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

  <Step title="Enter the Merchant ID">
    Paste the AFS Merchant ID into **Merchant ID**. This field is required. Use the ID that matches the environment you chose: a `TEST` ID for simulator checks or your live ID for real payments.
  </Step>

  <Step title="Enter the API password">
    Paste the AFS API password into **AFS API Password**. This required value is stored as a protected credential for your organisation.
  </Step>

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

## Assign AFS to an Event

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

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

  <Step title="Set package prices in a supported currency">
    Create or update Checkout packages in **BHD**, **USD**, **AED**, **SAR**, or **QAR**. Other currencies cannot be used with AFS.
  </Step>

  <Step title="Publish and test">
    Publish the packages and run a complete buyer journey using the simulator before you switch the event to a live AFS configuration.
  </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 Merchant ID beginning with `TEST`; public checkout uses the live Merchant ID. |
| **Payment page opens** | A buyer can continue from 9Pic to the AFS hosted payment page.                                  |
| **Payment completes**  | A successful test payment returns to 9Pic and marks the order paid.                             |
| **Price is correct**   | The amount shown by AFS matches the package price, including three decimal places for BHD.      |
| **Cancellation works** | Cancelling returns the buyer to 9Pic without marking the order paid.                            |

## Troubleshooting

<AccordionGroup>
  <Accordion title="9Pic says the Merchant ID or API password is missing.">
    Edit the AFS Gateway configuration and confirm that both required fields have values. The Merchant ID and AFS API Password are separate fields.
  </Accordion>

  <Accordion title="My test configuration does not work for a public event.">
    A Merchant ID beginning with `TEST` is only for the simulator and cannot be used for public checkout. Add or update the configuration with the live Merchant ID supplied by AFS.
  </Accordion>

  <Accordion title="I cannot select my AFS configuration for an event.">
    Confirm that the configuration was created for the same organisation as the event, then save the selection from the event's **Payment gateway** card.
  </Accordion>

  <Accordion title="The package currency is unavailable after I assign AFS.">
    AFS supports BHD, USD, AED, SAR, and QAR in 9Pic Checkout. Select one of those currencies or assign a gateway that supports the currency you need.
  </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>