> 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

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


---

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