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 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 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 page for further assistance.

API Conventions

🚧

BASE ENDPOINTS

Sandbox: https://sandbox.payretailers.com/payments/v2

Production: https://api.payretailers.com/payments/v2

  • Requests are authenticated with HTTP Basic Authentication using your shopId and secretKey, combined as shopId:secretKey and encoded in Base64 in the Authorization header.
  • Requests are only accepted from the whitelisted IP addresses associated with your merchant account. An HTTP 401 error may mean invalid credentials or a non-whitelisted IP.
  • 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:

  • 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.
📘

Subscription Key no longer required

The Ocp-Apim-Subscription-Key header is no longer required or validated. Integrations that already send it can keep doing so with no impact. See Authentication for details.

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 and 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 and Payout Flow 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.
  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.