Skip to main content

Tiendas Y Farmacias

  POST https://api-sandbox.epag.io/tiendasyfarmacias/simple

Overview​

Tiendas Y Farmacias is a widely-used cash payment method in Mexico that enables customers to pay for online purchases at a large network of participating retail stores. When a customer selects Tiendas Y Farmacias at checkout, they receive a voucher with a unique reference number or barcode. The customer then takes this reference to any of the thousands of affiliated stores—including major pharmacies, convenience stores, and supermarkets—to complete the payment in cash. Tiendas Y Farmacias is a key payment method for reaching customers who are unbanked or prefer the security of paying in person. For merchants, transactions are secure and confirmed upon payment, and since they are cash-based and irreversible, they carry no risk of chargebacks.

Reference Checkout UI Tiendas Y Farmacias

Reference UI - Tiendas Y Farmacias - Part 1Reference UI - Tiendas Y Farmacias - Part 1

Tiendas Y Farmacias Generated​

Reference UI - Tiendas Y Farmacias - Part 2Reference UI - Tiendas Y Farmacias - Part 2

Reference Checkout UI Tiendas Y Farmacias Email​

Upon successful creation of a payment order via the API, an automated confirmation email is sent to the address provided in the person.email field of your request. This email contains a copy of the payment instructions for the user's convenience.

Reference UI - Tiendas Y Farmacias - Part 3 - EmailReference UI - Tiendas Y Farmacias - Part 3 - Email

Tiendas Y Farmacias Flow​

Request Body​

  • contract_id (required/string): Merchant's contract id.
  • reference_id (required/string/max 45 chars): External code created by the merchant to reference this payment (e.g. order number). Pattern is free and is used in reports and callbacks.
  • notification_url (required/string): URL to post callbacks to this payment.
  • ip_address (optional/string): Remote IP Address(IPv4/IPv6).
  • payment (required/object): The payment data:
    • amount (float/required): Total amount of the payment. Value must have a maximum of two decimal places.
    • asset (optional/string): Reference code for asset for the sale's amount. Default: MXN.
    • currency (required/string): Currency code in ISO-4217.
    • country (required/string): Country code in ISO 3166-2.
    • tiendas_y_farmacias (optional/object): The Tiendas Y Farmacias payment data:
      • expiration_date (optional/date/YYYY-MM-DD): Expiration date (if not informed system will assume 5 days of current date).
      • description (optional/string): This is a message that goes attached to the transaction and will show at the recipient's bank statement.
      • logo (optional/string): The HTTP/Data URL of your logo (must be JPG or PNG format and it is recommended to be proportional to 200 x 45 pixels). If omitted, no logo will be displayed.
  • person (required/object): The person data:
    • full_name (required/string): Person’s full name.
    • email (required/string): Person’s email provided to the merchant.
  • extra_data (optional/JSON): Any data pertinent to the merchant.

Response Body​

  • transaction_status (string): Current status of the payment.
  • payment_token (string): Unique payment identification for this payment.
  • reference_id (string): External code created by the merchant to reference this payment (e.g. order number).
  • barcode_png_gzip_base_64 (string): Base64 zipped PNG image representation of Tiendas Y Farmacias barcode.
  • pdf_gzip_base_64 (string): Payment confirmation in Base64 zipped PDF format.
  • barcode (string): Text string containing barcode to pay this payment.
  • amount (string): Amount of this payment.
  • refresh_token (string): Updated access token for future calls.
  • totals (object): The payment totals:
    • amount (float): Amount in default region asset.
    • asset (string): Asset used in this amount.
    • original_amount (float): Amount as informed by merchant.
    • original_asset (string): Asset used in this originalAmount.
    • customer_fees (float): Total calculated fee assigned to customer.
    • customer_amount (float): Total amount for customer (amount + customer_fees).
  • customer_fees (object): List of incident customer fees and respective values.

Authorization​

AUTHORIZATIONAPI Key
KeyX-Auth-Token
ValueMY_ACCESS_TOKEN

Body Raw(json)​

json
{
    "contract_id": "MY_CONTRACT_ID",
    "reference_id": "MY_REFERENCE_ID",
    "notification_url": "https://my.notification.url/callback/",
    "ip_address": "0.0.0.0",
    "payment": {
        "amount": 123.45,
        "asset": "MXN",
        "currency": "MXN",
        "country": "MX",
        "tiendas_y_farmacias": {
            "expiration_date": "2024-12-31",
            "description": "Payment via Tiendas Y Farmacias",
            "logo": "data:image/png;base64,BASE64_ENCODED_IMAGE"
        }
    },
    "person": {
        "full_name": "Alice Sonnentag",
        "email": "[email protected]"
    },
    "extra_data": {
        "my-conciliation-number": "xxxxxx"
    }
}

Example Request​

Example Request​

200 - Success
    curl --location 'https://api-sandbox.epag.io/tiendasyfarmacias/simple' \
    --header 'X-Auth-Token: MY_ACCESS_TOKEN' \
    --data-raw '{
        "contract_id": "MY_CONTRACT_ID",
        "reference_id": "MY_REFERENCE_ID",
        "notification_url": "https://my.notification.url/callback/",
        "ip_address": "0.0.0.0",
        "payment": {
            "amount": 123.45,
            "asset": "MXN",
            "currency": "MXN",
            "country": "MX",
            "tiendas_y_farmacias": {
                "expiration_date": "2024-12-31",
                "description": "Payment via Tiendas Y Farmacias",
                "logo": "data:image/png;base64,BASE64_ENCODED_IMAGE"
            }
        },
        "person": {
            "full_name": "Alice Sonnentag",
            "email": "[email protected]"
        },
        "extra_data": {
            "my-conciliation-number": "xxxxxx"
        }
    }'

Example Response​

Header
  Content-Type: application/json
Body
    {
      "transaction_status": "PROCESSING",
      "payment_token": "0196e128-c6c7-4249-9f20-21a4c2eb1506",
      "reference_id": "MY_REFERENCE_ID",
      "barcode_png_gzip_base_64": "BASE64_ZIPPED_PNG",
      "pdf_gzip_base_64": "BASE64_ZIPPED_PDF",
      "barcode": "64000012578123060900025032",
      "amount": "123.45",
      "refresh_token": "MY_ACCESS_TOKEN",
      "totals": {
        "amount": 123.45,
        "original_amount": 123.45,
        "original_asset": "MXN",
        "customer_fees": 0,
        "customer_amount": 123.45,
        "asset": "MXN"
      },
      "customer_fees": {}
    }