> For the complete documentation index, see [llms.txt](https://plexo.gitbook.io/rest-api/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://plexo.gitbook.io/rest-api/merchant-configuration/payment-methods-setup.md).

# Payment Methods Setup Guide

## Overview

This guide explains how to configure merchant payment methods and choose the correct integration mode for each one. Payment methods can be configured through:

1. **Dashboard** (recommended for most users)
2. **API** (for automated provisioning)

Use this page for payment-method configuration, processor settings, and Gateway vs PayFac setup. For merchant discovery and the list of public merchant endpoints, use [Merchant Management](/rest-api/merchant-configuration/merchant-management.md).

## Dashboard Configuration

{% hint style="success" %}
**Recommended Approach:** Use the Dashboard for a visual, guided payment method configuration experience.
{% endhint %}

### Accessing Payment Methods

1. Log into the Plexo Dashboard
   * Testing: `https://dashboard.testing.plexo.com.uy`
   * Production: `https://dashboard.plexo.com.uy`
2. Navigate to **Merchants** section
3. Select your merchant
4. Click **Payment Methods**

### Adding a Payment Method (Dashboard)

**Step-by-Step Instructions:**

**1. Click "Add Payment Method"**

* Button located in top-right of Payment Methods page
* Opens payment method configuration wizard

**2. Select Payment Method Type**

* Choose from dropdown: VISA, MASTERCARD, OCA, AMEX, DINERS, CABAL, PIX, etc.
* See supported methods table below

**3. Choose Integration Mode**

{% tabs %}
{% tab title="Gateway Mode" %}

* For merchants with direct processor relationships
* Requires MID, Terminal Number from processor
* Full control over processing settings
* Best for established businesses
  {% endtab %}

{% tab title="PayFac Mode" %}

* For merchants without processor relationships
* Simplified onboarding
* Managed by PayFac partner (Handy)
* Best for startups and small businesses
  {% endtab %}
  {% endtabs %}

**4. Configure Mode-Specific Settings**

* Gateway: Enter MID, Terminal, Processor selection
* PayFac: Enter Sub-Merchant ID

**5. Optional: Configure 3DS Settings**

* Enable 3D Secure authentication
* Select processor scoping and rules

**6. Save Configuration**

* Validate all required fields completed
* Click "Save" to create payment method
* Test immediately with test transaction

## Gateway Mode Setup

### What is Gateway Mode?

Gateway Mode allows merchants to process payments using their own credentials from payment processors/acquirers. This mode is ideal for established businesses with existing processor relationships.

**Requirements:**

* `MerchantIdentificationNumber` (MID) from processor
* `TerminalNumber` from processor
* Tax identification (RUT for Uruguay)
* Merchant Category Code (MCC)
* Selected payment processor

### Gateway Mode Configuration (API)

```json
POST /v1/merchants/{merchantId}/payment-methods

{
  "id": "visa-payment-method-id",
  "settings": {
    "merchantIdentificationNumber": "123456789",
    "terminalNumber": "12345678",
    "paymentProcessor": {
      "id": "processor-uuid",
      "acquirer": "visanet"
    },
    "rut": "210000001234",
    "merchantCategoryCode": "5411"
  }
}
```

### Gateway Mode Configuration (Dashboard)

**Field-by-Field Guide:**

**1. Payment Method**

* **Field:** Payment Method dropdown
* **Description:** Select the card brand or payment type
* **Options:** VISA, MASTERCARD, OCA, AMEX, DINERS, CABAL, etc.
* **Example:** Select "VISA" for VISA credit/debit cards

**2. Payment Processor**

* **Field:** Processor dropdown
* **Description:** Select the acquirer/processor for this payment method
* **Options:** Visanet, OCA, Fiserv, Getnet, Scotiabank, Totalnet, Sistarbanc, Cabal, Mock
* **Example:** Select "Visanet" if you have a Visanet merchant account

**3. Merchant Identification Number (MID)**

* **Field:** Merchant ID text input
* **Description:** Unique identifier assigned by your payment processor
* **How to Obtain:** Contact your processor (Totalnet, OCA, Fiserv, etc.)

**4. Terminal Number**

* **Field:** Terminal text input
* **Description:** Terminal identifier for transaction routing
* **Format:** Typically 8 digits
* **Example:** `12345678`
* **How to Obtain:** Provided with your MID by processor

**5. RUT (Tax ID)**

* **Field:** RUT text input
* **Description:** Business tax identification number
* **Format (Uruguay):** 12 digits (210000001234)
* **Format (Brazil):** CNPJ 14 digits
* **Example:** `210000001234`
* **Note:** Must match registration with processor

**6. Merchant Category Code (MCC)**

* **Field:** MCC text input
* **Description:** ISO 18245 code classifying business type
* **Format:** 4 digits
* **Example:** `5411` (Grocery Stores), `5812` (Restaurants)
* **How to Determine:** Assigned by processor based on business type

**Common MCCs:**

| MCC  | Business Type                |
| ---- | ---------------------------- |
| 5411 | Grocery Stores, Supermarkets |
| 5812 | Eating Places, Restaurants   |
| 5912 | Drug Stores, Pharmacies      |
| 5999 | Miscellaneous Retail         |
| 7011 | Hotels, Motels, Resorts      |
| 7399 | Business Services            |

{% hint style="info" %}
**Where to Get Credentials:** Contact your payment processor's merchant services team. They will provide your MID, Terminal Number, and confirm your RUT and MCC.
{% endhint %}

{% hint style="warning" %}
**Important:** Incorrect credentials will cause all transactions to fail. Double-check all values before saving.
{% endhint %}

## PayFac Mode Setup

### What is PayFac Mode?

PayFac Mode allows merchants to process payments through Plexo's payment facilitator partner (Handy) without requiring direct processor credentials. This mode offers faster onboarding and simplified compliance.

**Requirements:**

* PayFac merchant ID
* PayFac sub-merchant identifier
* Selected PayFac processor

### PayFac Mode Configuration (API)

```json
POST /v1/merchants/{merchantId}/payment-methods

{
  "id": "visa-payment-method-id",
  "settings": {
    "paymentFacilitator": {
      "id": "payfac-merchant-uuid",
      "merchantId": "{{SUB_MERCHANT_ID}}"
    },
    "paymentProcessor": {
      "acquirer": "handy-processor"
    }
  }
}
```

### PayFac Mode Configuration (Dashboard)

**Field-by-Field Guide:**

**1. Payment Method**

* **Field:** Payment Method dropdown
* **Description:** Select the payment type
* **Options:** VISA, MASTERCARD, PIX, OCA
* **Example:** Select "PIX" for Brazilian instant payments
* **Note:** Not all methods available in PayFac mode (see supported methods table)

**2. Payment Facilitator**

* **Field:** PayFac dropdown
* **Description:** Select the payment facilitator partner
* **Options:** Handy (currently only option)
* **Example:** Select "Handy"

**3. Sub-Merchant ID**

* **Field:** Sub-Merchant ID text input
* **Description:** Your unique identifier within the PayFac's system
* **Format:** Provided by Handy during onboarding
* **Example:** `12345`
* **How to Obtain:** Complete Handy onboarding process through Plexo

**4. PayFac Merchant Reference**

* **Field:** Merchant Reference (optional)
* **Description:** Additional reference for multi-location businesses
* **Example:** `store-montevideo-01`

**Onboarding Process:**

1. **Request PayFac Access**
   * Email: <soporte@plexo.com.uy>
   * Subject: "PayFac Onboarding Request"
   * Include: Business name, RUT/CNPJ, contact information
2. **Complete KYC Documentation**
   * Business registration documents
   * Tax identification
   * Ownership information
   * Bank account details
3. **Handy Approval**
   * Handy reviews application (1-3 business days)
   * Approval notification with Sub-Merchant ID
4. **Configure in Plexo Dashboard**
   * Enter Sub-Merchant ID
   * Select payment methods
   * Complete configuration
5. **Test and Go Live**
   * Test transaction in sandbox
   * Activate for production

{% hint style="success" %}
**Fast Onboarding:** PayFac mode typically completes onboarding in 3-5 business days vs. 2-4 weeks for direct processor relationships.
{% endhint %}

{% hint style="info" %}
**PayFac Benefits:**

* No direct processor contracts needed
* Faster approval process
* Simplified compliance (Handy manages PCI)
* Lower upfront costs
* Unified reporting
  {% endhint %}

## 3DS Configuration

**Processor Scoping:**

* `cybersource-totalnet` - For Totalnet processor with 3DS
* `cybersource-oca` - For OCA processor with 3DS

**Test 3DS Flow**

1. Create a payment with `POST /v1/payments`
2. Include `browserDetails` in the request so 3DS can run correctly
3. If the response contains an `actions` entry with `rel = approval_url`, redirect the customer to complete the challenge
4. Confirm the final payment state through `GET /v1/payments/{paymentId}` and review the `threeDS` result

### PayFac Mode 3DS

**Managed 3DS in PayFac Mode:**

In PayFac mode, 3DS authentication is typically managed by the PayFac partner (Handy). Merchants do not need to configure Cybersource credentials directly. Instead, Handy handles all 3DS interactions and compliance on behalf of the merchant.

**Benefits:**

* No Cybersource contract needed
* Handy manages 3DS infrastructure
* Simplified configuration
* Unified reporting

**Limitations:**

* Less control over 3DS settings
* PayFac policies apply
* May have different fees

### 3DS Dashboard Configuration

**Enabling 3DS (Dashboard):**

**1. Navigate to Payment Method Settings**

* Select configured payment method
* Click "Edit" or "Configure 3DS"

**2. Enable 3D Secure**

* Toggle "Enable 3D Secure" switch to ON
* Select authentication mode:
  * **Always Required**: All transactions require 3DS
  * **Risk-Based**: 3DS triggered based on risk score
  * **Optional**: Merchant decides per transaction

**3. Configure Processor Scoping (Gateway Mode)**

* **Cybersource Merchant ID**: Enter your Cybersource merchant ID
* **Organization ID**: Enter 3DS organization ID
* **API Key**: Enter Cybersource API key (stored securely)
* **Processor Binding**: Select processor (cybersource-totalnet or cybersource-oca)

**4. Set Challenge Preferences**

* **Challenge Threshold**: Amount above which to always challenge (optional)
* **Exemptions**: Configure SCA exemptions (low value, trusted merchants)
* **Fallback**: Behavior if 3DS unavailable (allow or decline)

**5. Configure Callbacks**

* **3DS Callback URL**: URL to receive authentication results
* **Timeout**: Max time to wait for authentication (default 10 minutes)

**6. Test Configuration**

* Click "Test 3DS" button
* Complete test authentication
* Verify liability shift confirmed

**7. Save and Activate**

* Review configuration summary
* Click "Save" to apply changes
* 3DS now active for new transactions

## Supported Payment Methods

You can configure these payment methods:

| Payment Method  | Code         | Supports Gateway | Supports PayFac |
| --------------- | ------------ | ---------------- | --------------- |
| VISA            | `visa`       | ✅                | ✅               |
| MASTERCARD      | `mastercard` | ✅                | ✅               |
| OCA             | `oca`        | ✅                | ✅               |
| AMEX            | `amex`       | ✅                | ❌               |
| DINERS          | `diners`     | ✅                | ❌               |
| CABAL           | `cabal`      | ✅                | ❌               |
| PIX             | `pix`        | ❌                | ✅               |
| *...and 7 more* |              |                  |                 |

*See* [*Supported Payment Methods*](/rest-api/reference/supported-payment-methods.md) *for complete list*

## Supported Processors

*Content to be added - list of processors by mode*

**Gateway Mode Processors:**

* Visanet
* OCA
* Fiserv
* Getnet
* Scotiabank
* Totalnet
* Sistarbanc
* *...and more*

**PayFac Processors:**

* Handy (via PagBrasil for PIX)
* *Additional processors via PayFac partner*

*See* [*Supported Payment Methods and Processors*](/rest-api/reference/supported-payment-methods.md) *for complete details*

## Validation and Testing

### Pre-Production Validation Checklist

Before enabling payment methods in production:

**Configuration Validation:**

* [ ] All required fields completed (MID, Terminal, Processor)
* [ ] Credentials validated with processor
* [ ] Tax ID (RUT/CNPJ) matches processor registration
* [ ] MCC code confirmed correct
* [ ] 3DS configuration tested (if enabled)
* [ ] Callback URLs configured and responding

**Testing Validation:**

* [ ] Successful authorization with test card
* [ ] Successful capture flow
* [ ] Failed payment handling (insufficient funds test)
* [ ] Refund process tested
* [ ] 3DS challenge flow tested (if enabled)
* [ ] Callback delivery confirmed

**Operational Validation:**

* [ ] Dashboard access for relevant team members
* [ ] Monitoring and alerting configured
* [ ] Settlement account verified
* [ ] Support contact information documented
* [ ] Reconciliation process defined

### Testing Payment Methods

**Test in Dashboard:**

1. **Navigate to Payment Method**
   * Go to Merchants → \[Your Merchant] → Payment Methods
   * Select configured payment method
2. **Click "Test Payment" Button**
   * Opens test transaction form
   * Pre-filled with test card
3. **Execute Test Transaction**
   * Amount: Enter test amount (e.g., 100.00)
   * Card: Use provided test card or enter custom
   * Submit payment
4. **Verify Result**
   * Status: Should show "Authorized" or "Captured"
   * Authorization Code: Present
   * Processor Response: Success

**Test via API:**

```bash
curl -X POST https://api.testing.plexo.com.uy/v1/payments \
  -H "Authorization: Basic $(echo -n 'clientId:apiKey' | base64)" \
  -H "Content-Type: application/json" \
  -d '{
    "merchantId": {{MERCHANT_ID}},
    "referenceId": "pm-test-1001",
    "invoiceNumber": "PM-TEST-1001",
    "amount": {
      "total": 10000,
      "currency": "UYU"
    },
    "paymentMethod": {
      "source": "card",
      "card": {
        "number": "4444333322221111",
        "expMonth": 12,
        "expYear": 2028,
        "cvc": "123",
        "cardholder": {
          "firstName": "Test",
          "lastName": "User"
        }
      }
    },
    "browserDetails": {
      "ipAddress": "203.0.113.10",
      "userAgent": "Mozilla/5.0"
    },
    "capture": {
      "method": "automatic"
    }
  }'
```

**Expected Response:**

```json
{
  "paymentId": "pay_test_123",
  "status": "authorized",
  "authorizationCode": "123456"
}
```

## Managing Payment Methods

### Updating Configuration

**Via Dashboard:**

1. Navigate to Payment Methods
2. Select payment method to update
3. Click "Edit" button
4. Modify fields (MID, Terminal, Processor, etc.)
5. Click "Save Changes"
6. Test updated configuration

**Via API:**

```http
PUT /v1/merchants/{merchantId}/payment-methods/{paymentMethodId}

{
  "settings": {
    "merchantIdentificationNumber": "new-mid-value",
    "terminalNumber": "new-terminal-value"
  }
}
```

{% hint style="warning" %}
**Important:** Updating payment method settings may cause temporary transaction failures. Schedule updates during low-traffic periods and test immediately.
{% endhint %}

### Disabling Payment Methods

**Temporarily disable** a payment method without deleting configuration.

**Via Dashboard:**

1. Navigate to Payment Methods
2. Select payment method
3. Toggle "Enabled" switch to OFF
4. Confirm action

**Via API:**

```http
PATCH /v1/merchants/{merchantId}/payment-methods/{paymentMethodId}

{
  "enabled": false
}
```

**Effects:**

* Payment method not available for new transactions
* Existing authorized payments can still be captured
* Configuration preserved for re-enabling
* Dashboard shows "Disabled" status

**Use Cases:**

* Temporary processor maintenance
* Seasonal payment method availability
* Testing alternative payment methods
* Compliance or regulatory holds

### Deleting Payment Methods

**Permanently remove** payment method configuration.

**Via Dashboard:**

1. Navigate to Payment Methods
2. Select payment method
3. Click "Delete" button
4. Confirm deletion (cannot be undone)

**Via API:**

```http
DELETE /v1/merchants/{merchantId}/payment-methods/{paymentMethodId}
```

{% hint style="danger" %}
**Warning:** Deleting a payment method is permanent. All configuration (MID, Terminal, 3DS settings) will be lost. Consider disabling instead if you may need it again.
{% endhint %}

**Effects:**

* Payment method immediately unavailable
* Configuration cannot be recovered
* Historical transactions remain visible
* Must reconfigure from scratch to re-enable

## Common Configuration Issues

### Issue: Transactions Failing with "Invalid Merchant ID"

**Symptoms:**

* All transactions decline
* Error message mentions merchant ID
* Processor response: "Invalid merchant"

**Causes:**

* Incorrect MID entered in configuration
* MID not activated by processor
* Typo in MID field

**Resolution:**

1. Verify MID with processor
2. Check for typos or extra spaces
3. Confirm MID is active and approved
4. Update configuration and retest

### Issue: 3DS Authentication Fails

**Symptoms:**

* 3DS redirect fails
* Error: "3DS provider unavailable"
* Transactions decline with 3DS error

**Causes:**

* Invalid Cybersource credentials
* Incorrect processor scoping
* Cybersource service not activated

**Resolution:**

1. Verify Cybersource merchant ID
2. Confirm API key correct
3. Check processor binding (cybersource-totalnet vs cybersource-oca)
4. Contact Cybersource support to verify service status
5. Test with 3DS disabled to isolate issue

### Issue: Callbacks Not Received

**Symptoms:**

* Payment processed but no callback
* Dashboard shows successful payment
* Callback URL not receiving notifications

**Causes:**

* Invalid callback URL
* Firewall blocking Plexo IPs
* Endpoint not returning 200 status
* SSL certificate issues

**Resolution:**

1. Verify callback URL is publicly accessible
2. Test endpoint with curl or Postman
3. Check your application logs and request traces
4. Ensure endpoint returns 200 OK
5. Whitelist Plexo IPs in firewall
6. Validate SSL certificate

### Issue: Transactions in Wrong Currency

**Symptoms:**

* Payments processed in unexpected currency
* Amounts don't match expected values

**Causes:**

* Currency mismatch between merchant and processor
* Incorrect currency in API request
* Multi-currency processor misconfigured

**Resolution:**

1. Verify supported currencies with processor
2. Check payment method currency configuration
3. Ensure API requests specify correct currency
4. Contact processor to confirm currency support

### Issue: Test Transactions Succeed, Production Fails

**Symptoms:**

* All works in testing environment
* Production transactions fail

**Causes:**

* Production credentials not configured
* Different MID/Terminal for production
* Production processor not activated
* IP whitelisting not updated

**Resolution:**

1. Verify production credentials separate from test
2. Confirm production MID/Terminal with processor
3. Check processor activation status
4. Update IP whitelisting for production
5. Test with small transaction first

## Migration Between Modes

### Migrating from PayFac to Gateway Mode

**When to Migrate:**

* Transaction volume exceeds PayFac thresholds
* Need lower processing rates
* Require more control over processing
* Want direct processor relationship

**Migration Steps:**

1. **Obtain Gateway Credentials**
   * Apply with payment processor
   * Receive MID, Terminal Number
   * Complete underwriting (2-4 weeks)
2. **Configure Gateway Mode**
   * Add new payment method in Gateway mode
   * Enter processor credentials
   * Configure 3DS (if needed)
   * Test thoroughly
3. **Parallel Testing**
   * Run both PayFac and Gateway in parallel
   * Compare transaction success rates
   * Verify settlement amounts match
   * Test all payment flows
4. **Cutover**
   * Update default payment method to Gateway
   * Monitor initial transactions closely
   * Keep PayFac enabled as backup for 7 days
   * Disable PayFac after successful migration
5. **Post-Migration**
   * Reconcile settlements from both modes
   * Update documentation and processes
   * Train team on new configuration

### Migrating from Gateway to PayFac Mode

**When to Migrate:**

* Simplify operations
* Reduce compliance burden
* Eliminate direct processor management
* Focus on core business

**Migration Steps:**

1. **Request PayFac Onboarding**
   * Contact Plexo support
   * Complete KYC documentation
   * Receive Sub-Merchant ID
2. **Configure PayFac Mode**
   * Add payment method in PayFac mode
   * Enter Sub-Merchant ID
   * Test in sandbox
3. **Gradual Migration**
   * Route percentage of traffic to PayFac (e.g., 10%)
   * Monitor performance and costs
   * Gradually increase percentage
   * Complete migration when stable
4. **Decommission Gateway**
   * Disable Gateway payment method
   * Notify processor to close account
   * Archive Gateway credentials securely

## Best Practices

### 1. Start with Testing Environment

**Always configure and test in the testing environment first.**

* Use testing Dashboard (dashboard.testing.plexo.com.uy)
* Test all payment flows thoroughly
* Validate error handling
* Only promote to production after successful testing

### 2. Use Dashboard for Manual Setup

**Dashboard provides visual guidance and validation.**

* API is best for automated provisioning at scale
* Dashboard ideal for initial setup and troubleshooting
* Dashboard shows configuration warnings and tips
* Easier to verify settings visually

### 3. Validate Credentials Before Saving

**Test credentials with processor before configuring.**

* Contact processor to verify MID and Terminal
* Request test transaction through processor's portal
* Confirm credentials active and approved
* Reduces configuration errors

### 4. Document Your Settings

**Keep records of all payment method configurations.**

* MID and Terminal numbers
* Processor contact information
* Cybersource credentials (securely)
* Configuration change log
* Settlement account details

### 5. Monitor Dashboard Alerts

**Check Dashboard regularly for configuration issues.**

* Dashboard shows warnings for misconfigurations
* Alerts for failed transaction patterns
* Notifications for processor issues
* Set up email alerts for critical events

### 6. Test Immediately After Configuration

**Don't wait to validate new payment method setup.**

* Use Dashboard "Test Payment" feature
* Run test transactions via API
* Test all payment flows (auth, capture, refund)
* Verify callbacks delivered

### 7. Implement Gradual Rollout

**For critical changes, roll out gradually.**

* Start with small percentage of traffic
* Monitor success rates and errors
* Increase gradually as confidence builds
* Keep fallback option available

### 8. Maintain Production Parity

**Keep testing and production configurations in sync.**

* Document all production changes
* Apply same changes to testing environment
* Use version control for API configurations
* Test in staging before production deployment

## Related Resources

* [Gateway vs PayFac Modes](/rest-api/core-concepts/gateway-vs-payfac.md)
* [Supported Payment Methods and Processors](/rest-api/reference/supported-payment-methods.md)
* [Supported Payment Methods and Processors](/rest-api/reference/supported-payment-methods.md)
* [3DS Configuration](/rest-api/payments/3ds-integration.md)
* [Merchant Management](/rest-api/merchant-configuration/merchant-management.md)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://plexo.gitbook.io/rest-api/merchant-configuration/payment-methods-setup.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.