> 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/tools/postman-collection.md).

# Postman Collection

Test Plexo API endpoints directly using Postman with our pre-built collection

## Overview

The **Plexo API Postman Collection** provides a ready-to-use set of API requests for testing and integration development. Import the collection into Postman and start making API calls in minutes.

### What's Included

✅ **41 pre-configured requests** covering all API endpoints ✅ **10 organized folders** by functionality (Customers, Payments, Sessions, etc.) ✅ **4 environment templates** (Local, Testing, Staging, Production) ✅ **Automated tests** for response validation ✅ **Example data** for all request bodies ✅ **Authentication** pre-configured with Basic Auth

***

## 🚀 Quick Start

### Step 1: Download Files

Download the Postman collection and environment files:

**Collection:**

* [plexo-api-collection.json](https://github.com/plexouy/gitbook-public-docs/blob/main/api-rest/en/postman/plexo-api-collection.json)

**Environments:**

* [Local Development](https://github.com/plexouy/gitbook-public-docs/blob/main/api-rest/en/postman/plexo-api-local-development.environment.json)
* [Plexo Testing](https://github.com/plexouy/gitbook-public-docs/blob/main/api-rest/en/postman/plexo-api-plexo-testing.environment.json)
* [Plexo Staging](https://github.com/plexouy/gitbook-public-docs/blob/main/api-rest/en/postman/plexo-api-plexo-staging.environment.json)
* [Plexo Production](https://github.com/plexouy/gitbook-public-docs/blob/main/api-rest/en/postman/plexo-api-plexo-production.environment.json) ⚠️ Use with caution!

### Step 2: Import into Postman

1. Open **Postman** application or web version
2. Click **Import** button (top-left)
3. Drag and drop `plexo-api-collection.json` or click to browse
4. Collection appears in your **Collections** sidebar

### Step 3: Import Environment

1. Click **Environments** tab in left sidebar
2. Click **Import** button
3. Select your environment file (e.g., `plexo-api-plexo-testing.environment.json`)
4. Environment appears in **Environments** list

### Step 4: Configure Credentials

1. Select your imported environment from dropdown (top-right)
2. Click the **eye icon** to view variables
3. Set **Current Value** for:
   * `username`: Your Plexo API username
   * `password`: Your Plexo API password
   * `merchantId`: Your merchant ID
4. Click **Save**

### Step 5: Make Your First Request

1. Expand **Customers** folder in collection
2. Select **Create Customer** request
3. Review request body (pre-filled with example data)
4. Click **Send**
5. View response and test results in bottom panel

🎉 **Success!** You've made your first API call.

***

## 📁 Collection Structure

The collection is organized into **10 folders** matching API functionality:

### Customers

Manage customer records and profile information.

**Endpoints:**

* Create Customer
* List Customers
* Get Customer by ID
* Update Customer
* Delete Customer

### Payment Instruments

Manage tokenized payment methods for customers.

**Endpoints:**

* List Customer Instruments
* Get Instrument Details
* Delete Instrument

### Sessions

Create and manage checkout and tokenization sessions.

**Endpoints:**

* Create Tokenization Session
* Create Checkout Session
* Get Session Details
* List Sessions

### Payments

Process and manage payment transactions.

**Endpoints:**

* Create Card Payment
* Create Token Payment
* Get Payment Details
* Capture Payment
* Refund Payment
* Cancel Payment

### Merchants

Configure merchant accounts and payment methods.

**Endpoints:**

* List Merchants
* Get Merchant Details
* List Payment Methods
* Configure Payment Method
* Update 3DS Settings

### Processors

Query available payment processors and configurations.

**Endpoints:**

* List Processors
* Get Processor Details

### Payment Facilitators

Manage PayFac configurations for sub-merchants.

**Endpoints:**

* List Payment Facilitators

### 3DS Authentication

Configure and manage 3D Secure authentication.

**Endpoints:**

* Configure 3DS for Payment Method
* Update 3DS Rules

### Callbacks

The public API does not expose standalone callback-management endpoints.

Use request-scoped callback fields instead:

* `PaymentRequestDto.callbackUrl`
* `SessionRequest.settings.callbacks.paymentCallbackUrl`
* `SessionRequest.settings.callbacks.tokenizationCallbackUrl`

### General

Utility endpoints for testing and health checks.

**Endpoints:**

* Health Check
* API Version

***

## 🔧 Environment Variables

### Core Variables

| Variable     | Description      | Example                            | Required              |
| ------------ | ---------------- | ---------------------------------- | --------------------- |
| `baseUrl`    | API base URL     | `https://api.testing.plexo.com.uy` | Yes                   |
| `username`   | API username     | `your-username`                    | Yes                   |
| `password`   | API password     | `your-password`                    | Yes                   |
| `merchantId` | Your merchant ID | `3490`                             | For merchant requests |

### Resource IDs

These variables are populated automatically or can be set manually:

| Variable       | Description           | Usage               |
| -------------- | --------------------- | ------------------- |
| `customerId`   | Customer ID           | Customer operations |
| `sessionId`    | Session ID            | Session operations  |
| `paymentId`    | Payment ID            | Payment operations  |
| `instrumentId` | Payment instrument ID | Token operations    |

### Environment-Specific Base URLs

| Environment       | Base URL                           |
| ----------------- | ---------------------------------- |
| Local Development | `https://localhost:7001`           |
| Plexo Testing     | `https://api.testing.plexo.com.uy` |
| Plexo Staging     | `https://api-staging.plexo.com`    |
| Plexo Production  | `https://api.plexo.com.uy`         |

***

## 🧪 Automated Tests

Every request includes **automated tests** that run after each call:

### Standard Tests

✅ **Status Code Validation**

```javascript
pm.test("Status code is successful", function () {
    pm.response.to.have.status(200);
});
```

✅ **Response Time Check**

```javascript
pm.test("Response time is acceptable", function () {
    pm.expect(pm.response.responseTime).to.be.below(5000);
});
```

✅ **JSON Validation**

```javascript
pm.test("Response has valid JSON", function () {
    pm.response.to.be.json;
});
```

✅ **Required Properties**

```javascript
pm.test("Response has 'id' property", function () {
    const jsonData = pm.response.json();
    pm.expect(jsonData).to.have.property('id');
});
```

### Viewing Test Results

After sending a request:

1. Scroll to **Test Results** tab in response panel
2. Green checkmarks ✅ indicate passing tests
3. Red X marks ❌ indicate failing tests
4. Click on any test to see details

***

## 🔐 Authentication

### Basic Authentication

The collection uses **HTTP Basic Authentication** by default:

1. **Username** and **password** stored in environment variables
2. Automatically added to **Authorization** header
3. Applied to all requests in collection

### Setting Credentials

**Option 1: Environment Variables (Recommended)**

```
username: your-api-username
password: your-api-password
```

**Option 2: Per-Request Override**

1. Open specific request
2. Go to **Authorization** tab
3. Enter credentials directly

### Testing Authentication

Use the **Health Check** request to verify credentials:

```bash
GET {{baseUrl}}/v1/health
```

Expected response:

```json
{
  "status": "healthy",
  "timestamp": "2025-12-11T10:30:00Z"
}
```

***

## 📝 Request Examples

### Example 1: Create Customer

**Request:**

```http
POST {{baseUrl}}/v1/customers
Content-Type: application/json
Authorization: Basic {{username}}:{{password}}

{
  "referenceId": "customer-{{$timestamp}}",
  "email": "customer@example.com",
  "firstName": "John",
  "lastName": "Doe",
  "phone": "+1-555-0123"
}
```

**Response (201 Created):**

```json
{
  "id": "abc123def456",
  "referenceId": "customer-1702292400",
  "email": "customer@example.com",
  "firstName": "John",
  "lastName": "Doe",
  "phone": "+1-555-0123",
  "status": "active"
}
```

### Example 2: Create Tokenization Session

**Request:**

```http
POST {{baseUrl}}/v1/sessions
Content-Type: application/json

{
  "merchantId": {{merchantId}},
  "type": "tokenization",
  "referenceId": "session-{{$timestamp}}",
  "customerId": "{{customerId}}",
  "settings": {
    "tokenization": {
      "type": "store"
    }
  }
}
```

**Response (200 OK):**

```json
{
  "id": "e2af5b8d-29a1-474c-8212-4ff0193ca80a",
  "referenceId": "session-1702292400",
  "type": "tokenization",
  "status": "active",
  "expiresAt": "2025-12-11T10:30:00Z",
  "actions": [
    {
      "rel": "REDIRECT",
      "href": "https://tokenizations.testing.plexo.com.uy/..."
    }
  ]
}
```

***

## 🐛 Troubleshooting

### 401 Unauthorized

**Problem:** Authentication failed

**Solutions:**

* ✅ Verify `username` and `password` in environment
* ✅ Check environment is selected (top-right dropdown)
* ✅ Ensure credentials haven't expired
* ✅ Confirm you have API access enabled

### 404 Not Found

**Problem:** Resource doesn't exist

**Solutions:**

* ✅ Verify resource IDs in environment variables (`customerId`, `merchantId`, etc.)
* ✅ Check `baseUrl` points to correct environment
* ✅ Ensure resource was created successfully
* ✅ Confirm resource wasn't deleted

### 400 Bad Request

**Problem:** Invalid request data

**Solutions:**

* ✅ Review request body for missing required fields
* ✅ Check data types match API schema (string, number, boolean)
* ✅ Verify enum values are valid (e.g., `status: "active"`)
* ✅ Ensure IDs format is correct (UUID, integer, etc.)

### SSL Certificate Errors (Local Development)

**Problem:** Self-signed certificate error when using localhost

**Solutions:**

1. Open **Settings** → **General**
2. Disable **SSL certificate verification**
3. Only use for local development!

### Variables Not Resolving

**Problem:** `{{variableName}}` appears in request instead of value

**Solutions:**

* ✅ Ensure environment is selected (top-right)
* ✅ Check variable exists in selected environment
* ✅ Verify **Current Value** is set (not just Initial Value)
* ✅ Save environment after making changes

***

## 🔄 Keeping Collection Updated

The Postman collection is **auto-generated** from the OpenAPI specification and updated regularly.

### Updating Collection

**Option 1: Re-import (Recommended)**

1. Download latest `plexo-api-collection.json`
2. In Postman, click **Import**
3. Select file
4. Choose **Replace** when prompted
5. Your environments and settings are preserved

**Option 2: Manual Sync**

1. Compare collection version with latest release
2. Add/update individual requests as needed

### Checking Version

Open collection **info** (ℹ️ icon) to see version:

```
Version: 2.0.0
Last Updated: 2025-12-11
```

***

## 📚 Additional Resources

### Documentation

* [API Reference](/rest-api/api-reference/api-reference.md) - Complete endpoint documentation
* [Getting Started Guide](/rest-api/payments/first-payment.md) - Integration quickstart
* [Authentication Guide](/rest-api/getting-started/authentication.md) - Auth setup

### Tools

* [OpenAPI Specification (Testing)](https://api.testing.plexo.com.uy/openapi/v2.json) - Live OpenAPI spec used by GitBook imports
* [Code Examples](https://github.com/plexouy/gitbook-public-docs/blob/main/api-rest/en/guides/README.md) - Integration examples in multiple languages

### Support

* **Email:** <soporte@plexo.com.uy>
* **Documentation:** [docs.plexo.com](https://docs.plexo.com)
* **Status Page:** [status.plexo.com](https://status.plexo.com)

***

## 💡 Pro Tips

### Tip 1: Use Collection Variables

Store commonly used IDs as **collection variables** instead of copying between requests:

1. Right-click collection → **Edit**
2. Go to **Variables** tab
3. Add variables (e.g., `testCustomerId`)
4. Reference as `{{testCustomerId}}` in requests

### Tip 2: Use Pre-request Scripts

Generate dynamic data automatically:

```javascript
// Generate unique reference ID
pm.collectionVariables.set("uniqueRef",
  "customer-" + Date.now());
```

### Tip 3: Chain Requests

Use test scripts to save response data for next request:

```javascript
// Save customer ID from response
const response = pm.response.json();
pm.environment.set("customerId", response.id);
```

### Tip 4: Use Collection Runner

Test multiple requests in sequence:

1. Click collection → **Run**
2. Select requests to run
3. Configure iterations
4. View aggregate results

### Tip 5: Monitor API in Cloud

Set up monitoring to track API health:

1. Click collection → **Monitor**
2. Choose schedule (hourly, daily)
3. Select environment
4. Receive alerts on failures

***

## 📄 License

This Postman collection is provided for Plexo API integration and testing purposes. Use in accordance with your Plexo API service agreement.

***

**Questions?** Contact Plexo support or refer to the [complete API documentation](/rest-api/api-reference/api-reference.md).