# PayRetailers API Documentation

> Use Payretailers API to expand your business opportunities and process payments in all LATAM countries.

## Guides
- [Welcome to PayRetailers!](https://www.payretailers.dev/docs/welcome.md)
- [Getting Started](https://www.payretailers.dev/docs/getting-started.md)
- [Authentication](https://www.payretailers.dev/docs/authentication-1.md)
- [Payment Method Types](https://www.payretailers.dev/docs/payment-method-types.md)
- [Bank Transfers](https://www.payretailers.dev/docs/bank-transfers.md)
- [Cards](https://www.payretailers.dev/docs/cards.md)
- [Cash](https://www.payretailers.dev/docs/cash.md)
- [Integration Types](https://www.payretailers.dev/docs/integration-types.md): Merchants have various options to integrate Payretailers payment solution. On this page you will find information about each type of integration available.
- [Paywall Integration](https://www.payretailers.dev/docs/paywall-integration.md)
- [Optimizing Conversion with our Paywall](https://www.payretailers.dev/docs/increasing-conversion-with-our-paywall-2.md)
- [Hosted Payment Pages](https://www.payretailers.dev/docs/dynamic-integration.md)
- [Optimizing Conversion with our Hosted Payment Pages](https://www.payretailers.dev/docs/optimizing-conversion-rates-with-payretailers-hosted-payment-pages-2.md)
- [Direct API](https://www.payretailers.dev/docs/host-to-host-integration.md)
- [Direct API JavaScript Library](https://www.payretailers.dev/docs/host-to-host-integration-mexico-credit-cards.md): The Direct API JavaScript Library offers our clients an efficient and seamless solution to integrate with our payment services.   **Currently it's only available for Credit Cards in Mexico**.
- [Optimizing Conversion with our Direct API](https://www.payretailers.dev/docs/optimizing-conversion-rates-with-payretailers-direct-api-2.md)
- [Transaction Types](https://www.payretailers.dev/docs/transaction-types.md)
- [Payins](https://www.payretailers.dev/docs/payins.md)
- [Payouts](https://www.payretailers.dev/docs/payouts.md)
- [Solutions](https://www.payretailers.dev/docs/validations.md)
- [Customer Management Module](https://www.payretailers.dev/docs/customer-module.md)
- [Brazil](https://www.payretailers.dev/docs/brazil.md): Sports Betting & Gambling Regulated Merchants
- [PIX Integration Payins](https://www.payretailers.dev/docs/pix-integration-payins-copy.md)
- [PIX Integration Payouts](https://www.payretailers.dev/docs/pix-integration-payouts-copy.md)
- [PIX new account validation service](https://www.payretailers.dev/docs/pix-integration-validations.md)
- [Pix Automatic (Subscription Service)](https://www.payretailers.dev/docs/pix-automatico.md)
- [Mexico](https://www.payretailers.dev/docs/mexico.md)
- [SPEI CLABE per Customer](https://www.payretailers.dev/docs/clabe-per-customer.md): Only for Hosted Payment Pages and Direct API integrations
- [Payment Subscriptions](https://www.payretailers.dev/docs/payment-subscriptions.md)
- [Getting Started with Subscriptions](https://www.payretailers.dev/docs/getting-started-with-subscriptions.md)
- [Subscription Concepts](https://www.payretailers.dev/docs/subscription-concepts.md)
- [Automatic Scheduling](https://www.payretailers.dev/docs/automatic-scheduling.md)
- [Retry Policies](https://www.payretailers.dev/docs/retry-policies.md)
- [Webhooks and Notifications](https://www.payretailers.dev/docs/webhooks-and-notifications.md)
- [Subscription Products](https://www.payretailers.dev/docs/subscription-products.md)
- [Subscription Payment Methods](https://www.payretailers.dev/docs/subscription-payment-methods.md)
- [Merchant FX Control](https://www.payretailers.dev/docs/merchant-fx-control-1.md)
- [Payins FX Control](https://www.payretailers.dev/docs/merchant-fx-control.md)
- [Payouts FX Control](https://www.payretailers.dev/docs/payout-fx-control-experimental.md)
- [Argentina - Alias (CVU) Bank Transfer Payins](https://www.payretailers.dev/docs/alias-cvu-per-customer.md)
- [Transaction Matching Mode](https://www.payretailers.dev/docs/transaction-matching-mode.md)
- [Push Payment Mode](https://www.payretailers.dev/docs/push-payment-mode.md)
- [Colombia - Bre-B](https://www.payretailers.dev/docs/colombia-1.md)
- [Coverage and Methods](https://www.payretailers.dev/docs/coverage-and-methods.md)
- [Brazil](https://www.payretailers.dev/docs/brazil-1.md)
- [Colombia](https://www.payretailers.dev/docs/colombia.md)
- [Chile](https://www.payretailers.dev/docs/chile.md)
- [Mexico](https://www.payretailers.dev/docs/mexico-1.md)
- [Argentina](https://www.payretailers.dev/docs/argentina.md)
- [Peru](https://www.payretailers.dev/docs/peru.md)
- [Payment Buttons](https://www.payretailers.dev/docs/payment-buttons.md)
- [Service Status Page](https://www.payretailers.dev/docs/status-page.md)
- [Help & Support](https://www.payretailers.dev/docs/help-support.md): Are you experiencing issues with our payment processing solution? Our support teams are here to assist you and address any questions you may have! Please reach out to the appropriate team based on the type of issue you're encountering.
- [Getting Started with the Merchant Data API](https://www.payretailers.dev/docs/getting-started-with-the-merchant-data-api.md): The Merchant Data API is a read-only GraphQL API that gives you access to your payins, payouts, claims, and aggregation data. Use it to build reporting dashboards, reconcile transactions, and monitor dispute activity.
- [Authentication](https://www.payretailers.dev/docs/authentication.md): Every request to the Merchant Data API must include valid credentials. The API uses HTTP Basic Authentication with your Shop ID and API token.
- [Pagination, Filtering, and Sorting](https://www.payretailers.dev/docs/pagination-filtering-and-sorting.md): The Merchant Data API uses cursor-based pagination for all list queries (`payins`, `payouts`, `claims`). This guide explains how to paginate through results, apply filters, and understand the response structure.
- [Error Handling](https://www.payretailers.dev/docs/error-handling.md): The Merchant Data API returns errors using the standard GraphQL error format. This guide explains the error envelope, error categories, and how to build a resilient integration with retry logic.
- [Data Model Reference](https://www.payretailers.dev/docs/data-model-reference.md): This reference documents all entity types, fields, connections, filter inputs, and supporting types in the Merchant Data API.
- [Merchant Portal Overview](https://www.payretailers.dev/docs/merchant-portal-overview.md): The merchant portal is an **online dashboard** that enables you to manage your shop and all related activities. From this dashboard, you can create payment links and initiate payouts as needed. It serves as your primary tool for managing our payment solution.
- [Password Reset](https://www.payretailers.dev/docs/password-reset.md): Have you forgotten your back office password? Read on.
- [API Key Rotation](https://www.payretailers.dev/docs/api-key-rotation.md): Create a new API Secret Key and eliminate your old one
- [Balance Section](https://www.payretailers.dev/docs/balance-section-2.md)
- [Transactions Section](https://www.payretailers.dev/docs/transactions-section.md): In this section, you can view the details of all transactions made for each shop registered with PayRetailers. You’ll be able to see the transaction amount, description, status, date, payment method used, and customer details directly from the dashboard. For more in-depth information, you can download the transaction report.
- [Payouts Section](https://www.payretailers.dev/docs/payouts-section.md): The payouts section lets you filter and view all of the payouts created for any of the shops you have registered under your account.
- [Payment Tools Section](https://www.payretailers.dev/docs/payment-tools-section.md): Merchants are also able to process transactions directly through the back office. This is one of our code-free solution to use our payment solution. Here you will find steps to follow to generate **payment links** or **payment emails**.
- [Payment Links](https://www.payretailers.dev/docs/payment-links.md): Payment links are paywall URLs that can be generated from your merchant back office and then sent to customers. This is one of our code-free solutions for processing payments. Here you can find the steps to follow to generate a new payment link as well as how to check your payment links history.
- [Payment Emails](https://www.payretailers.dev/docs/payment-emails.md): Payment emails are paywall URLs sent directly in an email from your merchant back office to customers. The email is auto generated based on the information you fill in the form. This is one of our code-free solutions for processing payments. Here you can find the steps to follow to generate a new payment email as well as how to check your payment emails history.
- [Landing Info Customisation](https://www.payretailers.dev/docs/landing-info-customization.md): This section provides merchants with the ability to customise the checkout page for specific payment methods, allowing them to incorporate their own logos and select page colours that align with their brand identity.
- [Back Office Two-Factor Authentication(2FA)](https://www.payretailers.dev/docs/back-office-login-details.md)

## API Reference
- [Introduction](https://www.payretailers.dev/reference/introduction.md): Explore our API documentation and discover the resources available to enhance your integration experience.
- [Authentication](https://www.payretailers.dev/reference/authentication.md): Here, you’ll find all the essential information on how to correctly authenticate your API requests.
- [Transaction Flow Overview](https://www.payretailers.dev/reference/transaction-workflow-overview.md): This page is here to give you a general explanation of transactions lifecycle.
- [Payout Flow Overview](https://www.payretailers.dev/reference/payout-flow-overview.md): This page is here to give you a general explanation of payouts lifecycle.
- [Notifications](https://www.payretailers.dev/reference/notifications.md): On this page you will find more information about the notifications sent by our system.
- [Sandbox Environment](https://www.payretailers.dev/reference/sandbox-environment.md): Our sandbox is an isolated space for testing and experimentation. The sandbox is designed to provide developers, testers, and stakeholders with a controlled setting to explore and validate without the risks associated with production systems before going live.
- [Test Mode](https://www.payretailers.dev/reference/test-mode.md): The Payretailers API provides a sandbox environment for testing some of our [Payment Methods](https://payretailers.readme.io/reference/sandbox-environment#available-payment-methods-in-sandbox). <br><br>For testing once in the live enviroment, you may use the testMode parameter in your request to make the difference between real and test transactions. On this page you will find details about how you can test our payment solution when you need to.
- [Create Paywall](https://www.payretailers.dev/reference/create-paywall.md): Use this call to create a new paywall for your customers according to their country of residence and preferred payment methods.
- [Paywall Parameters](https://www.payretailers.dev/reference/paywall-parameters.md): Here you will find information about specific parameters of the **POST Create Paywall** request and their values.
- [Paywall Response](https://www.payretailers.dev/reference/paywall-response.md): Here you can find information about the response received after sending a **POST Create Paywall** request.
- [Get Paywall by trackingID](https://www.payretailers.dev/reference/get-paywall-by-trackingid.md): Use this call to retrieve the details of a Paywall previously created with the POST Paywall method.
- [Get Paywall by UID](https://www.payretailers.dev/reference/get-paywall-by-uid.md): Use this call to retrieve the details of a Paywall previously created with the POST Paywall method.
- [Create Transaction](https://www.payretailers.dev/reference/create-transaction.md): Use this method to create a new transaction / deposit and get paid by your customers!
- [Transaction Parameters](https://www.payretailers.dev/reference/transaction-parameters-1.md): On this page you will find information about the supported currencies per country for transactions.
- [Transaction Response](https://www.payretailers.dev/reference/transaction-response.md): Here you can find information about the response received after sending a **POST Create Transaction** request.
- [Transaction Error Messages](https://www.payretailers.dev/reference/transaction-error-messages.md): When creating a transaction, if the value of one of the mandatory fields of the request is wrong you will receive an error message in the response that will explain the reason of the error. This page lists the different possible errors you can get when creating transactions with their associated meaning.
- [Get Payment Methods](https://www.payretailers.dev/reference/get-payment-methods.md): Use this method to get a list of your active payment methods according to the filters you set.
- [Get Transaction by Tracking](https://www.payretailers.dev/reference/get-transaction-by-tracking.md): Use this call to get all of the details of one of your transactions.
- [Get Transaction by UID](https://www.payretailers.dev/reference/get-transaction-by-uid.md): Use this call to get all of the details of one of your transactions.
- [Get Landing Info](https://www.payretailers.dev/reference/get-landing-info.md): Use this call to get all the data you need to design your own checkout page.
- [Landing Info Response](https://www.payretailers.dev/reference/landing-info-response.md): Here you can find information about the response received after sending a **GET Landing Info** call.
- [Create Payout Quote](https://www.payretailers.dev/reference/createpayoutquote.md): Generate a fixed-rate FX quote for a payout transaction. Quote is valid for 5 minutes.
- [Create Payout](https://www.payretailers.dev/reference/create-payout.md): Use this call to create a payout and send money to your customers.
- [Payout Parameters](https://www.payretailers.dev/reference/payout-parameters.md): On this page you will find the possible values per country that can be used in your payout request.
- [Payout Error Messages](https://www.payretailers.dev/reference/payout-error-messages.md): When creating a payout, just like transactions, you will receive error messages when one of the required values is wrong or not formatted correctly. Here you can check the meaning of the errors you get and hopefully get help to fix those issues.
- [African Countries](https://www.payretailers.dev/reference/african-countries.md): On this page you will find the possible values per country that can be used in your payout request.
- [Get Payout Details](https://www.payretailers.dev/reference/get-payout-details.md): Use this call to retrieve the data of one of your payouts.
- [Create Customer](https://www.payretailers.dev/reference/create-customer.md)
- [Update Customer](https://www.payretailers.dev/reference/update-customer.md)
- [Get Customer](https://www.payretailers.dev/reference/get-customer.md)
- [Activate Customer](https://www.payretailers.dev/reference/activate-customer.md)
- [Deactivate Customer](https://www.payretailers.dev/reference/deactivate-customer.md)
- [Activate Virtual Account](https://www.payretailers.dev/reference/activate-virtual-account.md)
- [Deactivate Virtual Account](https://www.payretailers.dev/reference/deactivate-virtual-account.md)
- [Get Customer's Virtual Accounts](https://www.payretailers.dev/reference/get-customers-virtual-accounts.md)
- [Create a new subscription](https://www.payretailers.dev/reference/post_v1-subscriptions.md): Creates a new subscription for recurring payments. Supports two authorization journeys: BACKGROUND (push notification) and USER_INTERACTION (QR code scan).
- [Get subscription details](https://www.payretailers.dev/reference/get_v1-subscriptions-subscriptionid.md): Retrieves detailed information about a specific subscription.
- [Cancel a subscription](https://www.payretailers.dev/reference/delete_v1-subscriptions-subscriptionid.md): Cancels an active subscription.
- [Create a manual subscription payment](https://www.payretailers.dev/reference/post_v1-subscription-payments.md): Creates a manual payment for a subscription. Used when automatic scheduling is not enabled.
- [Get subscription payment details](https://www.payretailers.dev/reference/get_v1-subscription-payments-subscriptionpaymentid.md): Retrieves detailed information about a specific subscription payment.
- [Cancel a subscription payment](https://www.payretailers.dev/reference/delete_v1-subscription-payments-subscriptionpaymentid.md): Cancels a pending or scheduled subscription payment.
- [Create a subscription product](https://www.payretailers.dev/reference/post_v1-subscription-products.md): Creates a reusable subscription product template that can be used to create multiple subscriptions with the same configuration.
- [List subscription products](https://www.payretailers.dev/reference/get_v1-subscription-products.md): Retrieves a list of subscription products with optional filters.
- [Get subscription product details](https://www.payretailers.dev/reference/get_v1-subscription-products-subscriptionproductid.md): Retrieves detailed information about a specific subscription product.
- [Update a subscription product](https://www.payretailers.dev/reference/put_v1-subscription-products-subscriptionproductid.md): Updates an existing subscription product.
- [Deactivate a subscription product](https://www.payretailers.dev/reference/post_v1-subscription-products-subscriptionproductid-deactivate.md): Deactivates a subscription product, preventing new subscriptions from being created with it.
- [Activate a subscription product](https://www.payretailers.dev/reference/post_v1-subscription-products-subscriptionproductid-activate.md): Activates a previously deactivated subscription product.
- [Subscription webhook endpoint](https://www.payretailers.dev/reference/post_api-v1-subscription-events.md): This endpoint documents the webhook events that PayRetailers will send to your notificationUrl. You should implement this endpoint on your server to receive subscription and payment status updates.
- [GraphQL](https://www.payretailers.dev/reference/graphql.md): Use our GraphQL API to retrieve transaction data for Payins, Payouts and Claims.
- [Execute a GraphQL query](https://www.payretailers.dev/reference/executegraphqlquery.md): Single GraphQL endpoint serving all query operations: payins, payouts, claims, aggregations, ping, and currentMerchantId.  This is a read-only API. Only GraphQL `query` operations are supported; mutations are not available.  Your credentials are validated on every request. Your Shop ID is resolved to a merchant account, and all queries are automatically scoped to your data.
- [Get Merchant Balance](https://www.payretailers.dev/reference/get-merchant-balance.md): Use this call to retrieves your shop’s balance at any time.

## Recipes
- [Create Payout](https://www.payretailers.dev/recipes/create-payout.md)
- [Create Paywall](https://www.payretailers.dev/recipes/create-paywall.md)
- [Create Transaction](https://www.payretailers.dev/recipes/create-transaction.md)
- [Get Payment Methods](https://www.payretailers.dev/recipes/get-payment-methods.md)
- [Get Payout Details](https://www.payretailers.dev/recipes/get-payout-details.md)
- [Get Transaction by UID](https://www.payretailers.dev/recipes/get-transaction-by-uid.md)
- [List recent payins with date filter](https://www.payretailers.dev/recipes/list-recent-payins-with-date-filter.md)

## Changelog
- [New Third Party Payments Restriction for QR Payments (Argentina)](https://www.payretailers.dev/changelog/new-third-party-payments-restriction-for-qr-payments-argentina.md)
- [New Optional Feature: Payer Details Information in Callback for Khipu Payments](https://www.payretailers.dev/changelog/new-optional-feature-payer-details-information-in-callback-for-khipu-payments.md)
- [New error message due to PersonalID validation in Argentina](https://www.payretailers.dev/changelog/new-error-message-due-to-personalid-validation-in-argentina.md)
- [Sports Betting & Gambling Regulated Merchants in Brazil 2025](https://www.payretailers.dev/changelog/sports-betting-gambling-regulated-merchants-in-brazil-2025.md)
- [New Optional Feature PIX: Payer Account Number Information in Callback](https://www.payretailers.dev/changelog/new-optional-feature-pix-payer-account-number-information-in-callback.md)

## Integration Assistant
System prompt to configure any AI coding agent (Cursor, Claude, GPT, Windsurf, Devin) as a PayRetailers integration expert.
- [Integration Assistant Prompt](https://raw.githubusercontent.com/payretailers-dev/payretailers-ai-docs/main/INTEGRATION_PROMPT.md)

## Guides
End-to-end implementation tutorials that combine multiple Skills. Read a Guide first for broad integration questions.
- [Guides Index](https://raw.githubusercontent.com/payretailers-dev/payretailers-ai-docs/main/guides/README.md)
- [Testing in Sandbox](https://raw.githubusercontent.com/payretailers-dev/payretailers-ai-docs/main/guides/testing-in-sandbox.md)
- [Build a Checkout](https://raw.githubusercontent.com/payretailers-dev/payretailers-ai-docs/main/guides/build-a-checkout.md)
- [Integrate Card Payments](https://raw.githubusercontent.com/payretailers-dev/payretailers-ai-docs/main/guides/integrate-card-payments.md)
- [Integrate PIX](https://raw.githubusercontent.com/payretailers-dev/payretailers-ai-docs/main/guides/integrate-pix.md)
- [Integrate Payouts](https://raw.githubusercontent.com/payretailers-dev/payretailers-ai-docs/main/guides/integrate-payouts.md)
- [Build a Subscription Platform](https://raw.githubusercontent.com/payretailers-dev/payretailers-ai-docs/main/guides/build-a-subscription-platform.md)
- [Going Live](https://raw.githubusercontent.com/payretailers-dev/payretailers-ai-docs/main/guides/going-live.md)
- [Migrate from another PSP](https://raw.githubusercontent.com/payretailers-dev/payretailers-ai-docs/main/guides/migrate-from-another-psp.md)

## Skills
Developer workflows that combine multiple endpoints. Read a Skill before implementing an integration task.
- [Skills Index](https://raw.githubusercontent.com/payretailers-dev/payretailers-ai-docs/main/skills/README.md)
- [First Payin in Sandbox](https://raw.githubusercontent.com/payretailers-dev/payretailers-ai-docs/main/skills/sandbox-first-payin.md)
- [Paywall Checkout](https://raw.githubusercontent.com/payretailers-dev/payretailers-ai-docs/main/skills/paywall-checkout.md)
- [Hosted Payment Pages (Dynamic Checkout)](https://raw.githubusercontent.com/payretailers-dev/payretailers-ai-docs/main/skills/hpp-dynamic-checkout.md)
- [Direct API Payin Lifecycle](https://raw.githubusercontent.com/payretailers-dev/payretailers-ai-docs/main/skills/direct-api-payin-lifecycle.md)
- [Embedded Checkout with Landing Info](https://raw.githubusercontent.com/payretailers-dev/payretailers-ai-docs/main/skills/embedded-checkout-landing-info.md)
- [Mexico Credit Card — Backend + JavaScript Library](https://raw.githubusercontent.com/payretailers-dev/payretailers-ai-docs/main/skills/mexico-credit-card-js-library.md)
- [Payin Webhooks and Reconciliation](https://raw.githubusercontent.com/payretailers-dev/payretailers-ai-docs/main/skills/payin-webhooks-and-polling.md)
- [Payout Lifecycle](https://raw.githubusercontent.com/payretailers-dev/payretailers-ai-docs/main/skills/payout-lifecycle.md)
- [Payout with FX Quote](https://raw.githubusercontent.com/payretailers-dev/payretailers-ai-docs/main/skills/payout-fx-quote-flow.md)
- [Payin FX Control](https://raw.githubusercontent.com/payretailers-dev/payretailers-ai-docs/main/skills/payin-fx-control.md)
- [Customer Module — Onboarding and Virtual Accounts](https://raw.githubusercontent.com/payretailers-dev/payretailers-ai-docs/main/skills/customer-virtual-account-onboarding.md)
- [Mexico SPEI — CLABE per Customer](https://raw.githubusercontent.com/payretailers-dev/payretailers-ai-docs/main/skills/mexico-spei-clabe-per-customer.md)
- [Argentina Alias/CVU — Transaction Matching](https://raw.githubusercontent.com/payretailers-dev/payretailers-ai-docs/main/skills/argentina-alias-cvu-matching.md)
- [Argentina Alias/CVU — Push Payment](https://raw.githubusercontent.com/payretailers-dev/payretailers-ai-docs/main/skills/argentina-alias-cvu-push-payment.md)
- [Brazil PIX Payin](https://raw.githubusercontent.com/payretailers-dev/payretailers-ai-docs/main/skills/brazil-pix-payin.md)
- [Brazil PIX Payout and Account Validation](https://raw.githubusercontent.com/payretailers-dev/payretailers-ai-docs/main/skills/brazil-pix-payout-and-validation.md)
- [PIX Automático Subscription](https://raw.githubusercontent.com/payretailers-dev/payretailers-ai-docs/main/skills/pix-automatic-subscription.md)
- [Subscription Product Lifecycle](https://raw.githubusercontent.com/payretailers-dev/payretailers-ai-docs/main/skills/subscription-product-lifecycle.md)
- [Subscription Payments — Automatic and Manual](https://raw.githubusercontent.com/payretailers-dev/payretailers-ai-docs/main/skills/subscription-payments-manual-and-auto.md)
- [Subscription Webhooks](https://raw.githubusercontent.com/payretailers-dev/payretailers-ai-docs/main/skills/subscription-webhooks.md)
- [Colombia Bre-B Payin and Payout](https://raw.githubusercontent.com/payretailers-dev/payretailers-ai-docs/main/skills/colombia-breb-payin-payout.md)
- [Merchant Data API — Reporting and Reconciliation](https://raw.githubusercontent.com/payretailers-dev/payretailers-ai-docs/main/skills/merchant-data-api-reconciliation.md)