---
updatedAt: 2025-06-10T21:36:52.000Z
agentTools:
  projectIndex: https://www.payretailers.dev/llms.txt
---

# Introduction

Explore our API documentation and discover the resources available to enhance your integration experience.

> 📘
>
> If you have just arrived at our website, we recommend starting at the **[Welcome](https://www.payretailers.dev/docs/welcome)** page.

### Welcome to Payretailer's API Reference!

The **API Reference** section provides comprehensive information on utilizing our API, enabling you to begin processing your first transactions and payouts. Additionally, it includes valuable resources for troubleshooting and resolving any issues you may encounter.

If the documentation does not address your needs, please refer to the **[Discussion](https://payretailers.readme.io/discuss)**  section to see if your question has already been asked and answered.\
You can also reach out to the appropriate support team through our **[Help & Support](https://payretailers.readme.io/docs/help-support)**  page for further assistance.

### API Conventions

> 🚧 BASE ENDPOINT
>
> The base endpoint for our API is `https://api-sandbox.payretailers.com/payments/v2`
>
> The **Ocp-Apim-Subscription-Key** must be included in the HTTP header for authentication with every API request.
>
> For our Sandbox the key is: 1aa4e605bd5b405fba6061b55e52f4cd

* The Subscription Key is merchant-specific and can only be utilized from the whitelisted IP addresses associated with that merchant.
* Requests are encoded as **JSON** and sent as HTTP **POST** or **GET** requests to the appropriate endpoint.

For the system to process these requests, they must:

* In the header, the `shopId` and `secret key` can be sent using **[HTTP Basic authentication](https://developer.mozilla.org/en-US/docs/Web/HTTP/Authentication#Basic_authentication_scheme)** or encoded in **[Base64](https://developer.mozilla.org/en-US/docs/Glossary/Base64)**.
* Include the headers `Content-Type: application/json` and `Accept: application/json`\
  if it is a **POST** request.
* Utilize **SSL connection** with 128-bit (or stronger) encryption.
* Ensure the request is **UTF-8** encoded.

### API Flow Overview

Here’s an overview of a typical POST call to our API for generating a Payin/Payout:

1. Our endpoint receives a **POST request** and initiates **data validation**.
2. If the request is **unsuccessful**, you will receive an error along with the corresponding error message.\
   You can find the meanings of all error messages on the **[Transaction Error Messages](https://www.payretailers.dev/reference/transaction-error-messages)** and **[Payout Error Messages](https://www.payretailers.dev/reference/payout-error-messages)** pages.
3. If the request is **successful**, our servers will respond with a confirmation in JSON format, indicating the creation of the transaction, paywall, or payout, along with the appropriate **status**.\
   For further details, please refer to the **[Transaction Flow Overview](https://www.payretailers.dev/reference/api-workflow-overview)** and **[Payout Flow Overview](https://www.payretailers.dev/reference/api-workflow-and-payout-batch-overview)**.
4. Immediately after the transaction is created, a callback will be generated and sent via webhook to the designated notification URL (specified as the value of the parameter “`notificationURL`”).\
   For more information, see **[Notifications](https://www.payretailers.dev/reference/notifications)**.
5. From this point forward, **any status change** notified by our PSP to our system will be promptly forwarded through callbacks, reflecting the corresponding new status to the notification URL.