# Postman

#### **Optty Direct API: Hosted Payment Page Integration Guide**

This document provides a guide for using the "Optty Direct (docs)" Postman collection to integrate with Optty's Hosted Payment Page (HPP). It outlines the required setup and the sequence of API calls for creating, managing, and receiving updates on payment links.

{% file src="/files/c05MF8t2vP7UEXgnYCVZ" %}

**1. Prerequisites: Initial Setup**

Before you begin, you must configure your environment and set up a webhook to receive payment status updates.

* **Sandbox UPP Account:** If you do not already have a sandbox merchant account please sign up here, [**https://www.optty.com/merchant-account**](https://www.optty.com/merchant-account)
* **Set Collection Variables**: In your Postman environment, set the following variables:
  * `client_id`: Your unique Optty client identifier.
  * `client_secret`: Your Optty client secret.\
    These credentials are used in the first authentication call to obtain a secure token for all subsequent requests.
* **Set Up Your Webhook URL**: To receive real-time transaction status updates, you must enable a webhook on your site. Please configure this under `Settings` on the side bar tab of the UPP. For development and testing purposes, you can use a service like **webhook.site** to generate a temporary URL to inspect incoming notifications.

***

**2. API Workflow: Order of Calls**

The collection is designed to be run in a specific order. Each request builds on the previous one.

| Step  | Call Name                                          | Description                                                                                                                                                                                                              |
| ----- | -------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **1** | **Authentication (`Auth - Merchant`)**             | Authenticates your service using your `client_id` and `client_secret`. A test script automatically saves the returned `access_token` to a collection variable for use in subsequent calls.                               |
| **2** | **Create Payment Link (`Create Session`)**         | A pre-request script generates a unique `invoiceNumber`, and the call creates a session link that you can present to your customer to complete the payment.                                                              |
| **3** | **Refund or Cancel Link (`Refund / Cancel Link`)** | This call uses the `invoiceNumber` from the latest created session to cancel a pending payment or refund a completed one. If the payment is not in a `PAID` state, it will be cancelled; otherwise, it will be refunded. |

<br>


---

# Agent Instructions: 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:

```
GET https://docs.optty.com/hosted-payment-page/postman.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.