Payments (Pay In)

This module allows Payment Providers to process deposit or payment requests initiated by Pago46 users. Like withdrawals, this flow uses a locking mechanism to prevent the same order from being charged twice by different providers simultaneously.

Base Endpoint

All routes described below are relative to the API base URL: /api/v1

Payment Network Registration

Before processing transactions, providers must register the payment networks they use. Each network must have a unique identifier (provider_network_id) that will be used in all state transitions.

Example Network IDs:

• 01
• oxxo_network
• seven_eleven_mx
• farmacia_abc
• network_123

Contact

To register your payment networks, contact the Pago46 integration team. The IDs you provide will be the ones you must use in payment requests.

Order Lifecycle

The process ensures that money is collected and reconciled correctly before releasing the service to the end user.

1. Check: The provider scans or enters the user's code to see the amount to collect and validate that the status is READY.
2. Lock (Start Payment): The provider "takes" the order. The status changes to PAYMENT_STARTED. This ensures collection intent.
3. Confirmation (Confirm Payment): Once the user delivers the cash and it enters the cash register, the provider confirms the transaction (COMPLETED status).

---

1. Verify Order

When the customer approaches the cashier to pay, you must query the code to report the exact amount to collect.

Endpoint: GET /providers/orders/pay-in/{code}/

Parameter	Location	Description
code	Path	The payment code generated by the user (numeric or QR).

Request

curl -X GET "https://api.sandbox.pago46.io/api/v1/providers/orders/pay-in/9876543210/" \
  -H "Provider-Key: <YOUR_PROVIDER_KEY>" \
  -H "Message-Date: <TIMESTAMP>" \
  -H "Message-Hash: <HMAC_SIGNATURE>"

Response (200 OK) - Order Ready

{
  "order_type": "LocalCurrencyOrder",
  "price": "500.00",
  "price_currency": "MXN",
  "created": "2023-11-25T14:00:00Z",
  "status": "READY",
  "expiry": "2023-11-26T14:00:00Z",
  "description": "Purchase at Market 46"
}

Status Validation

Always verify that the status is READY. If the order is EXPIRED or COMPLETED, you should not receive money from the user.

---

2. Start Collection (Lock)

Before receiving the money, you must inform Pago46 that you are processing this order. This prevents the user from attempting to pay the same code at another provider simultaneously.

Endpoint: POST /providers/orders/pay-in/{code}/start-payment/

Request

curl -X POST "https://api.sandbox.pago46.io/api/v1/providers/orders/pay-in/9876543210/start-payment/" \
  -H "Provider-Key: <YOUR_PROVIDER_KEY>" \
  -H "Message-Date: <TIMESTAMP>" \
  -H "Message-Hash: <HMAC_SIGNATURE>" \
  -H "Content-Type: application/json" \
  -d '{
    "order_type": "LocalCurrencyOrder",
    "provider_network_id": "network_123",
    "price": "500.00",
    "price_currency": "MXN"
  }'

Response (200 OK)

{
  "order_type": "LocalCurrencyOrder",
  "price": "500.00",
  "price_currency": "MXN",
  "status": "PAYMENT_STARTED",
  "modified": "2023-11-25T14:05:00Z"
}

Error (403 Forbidden) - Order Already In Progress

{
    "detail": "You do not have permission to perform this action."
}

Field	Type	Description
order_type	string	Order type (LocalCurrencyOrder or ForeignCurrencyOrder).
provider_network_id	string	ID of the payment network used by the provider. Required for LocalCurrencyOrder orders.
price	string	Exact amount being collected. Must match the order's price. Required for LocalCurrencyOrder orders.
price_currency	string	Currency code (e.g., MXN, USD). Must match the order's price_currency. Required for LocalCurrencyOrder orders.

Subnetworks for Providers

As a provider, you must supply the provider_network_id that identifies the specific network used to process this transaction. This allows Pago46 to maintain a detailed record of which network processed each payment and provide this information to the end user.

Collection Moment

Once you receive the PAYMENT_STARTED status, you can safely proceed to request and receive the customer's money.

---

3. Confirm Collection (Finalization)

Once the money is secure in your cash register, confirm the transaction. At this point, Pago46 will notify the original merchant to release the product or service to the user.

Endpoint: POST /providers/orders/pay-in/{code}/confirm-payment/

Request

curl -X POST "https://api.sandbox.pago46.io/api/v1/providers/orders/pay-in/9876543210/confirm-payment/" \
  -H "Provider-Key: <YOUR_PROVIDER_KEY>" \
  -H "Message-Date: <TIMESTAMP>" \
  -H "Message-Hash: <HMAC_SIGNATURE>" \
  -H "Content-Type: application/json" \
  -d '{
    "order_type": "LocalCurrencyOrder",
    "provider_network_id": "network_123",
    "price": "500.00",
    "price_currency": "MXN"
  }'

Response (200 OK)

{
  "order_type": "LocalCurrencyOrder",
  "price": "500.00",
  "price_currency": "MXN",
  "status": "COMPLETED",
  "paid": "2023-11-25T14:06:00Z"
}

---

Cancellation

If the user decides not to pay at the last moment or there is a problem with the cash, you must release the order so it becomes available again (or is canceled definitively, according to the order's expiration rules).

Endpoint: POST /providers/orders/pay-in/{code}/cancel-payment/

curl -X POST "https://api.sandbox.pago46.io/api/v1/providers/orders/pay-in/9876543210/cancel-payment/" \
  -H "Provider-Key: <YOUR_PROVIDER_KEY>" \
  -H "Message-Date: <TIMESTAMP>" \
  -H "Message-Hash: <HMAC_SIGNATURE>" \
  -H "Content-Type: application/json" \
  -d '{
    "order_type": "LocalCurrencyOrder",
    "provider_network_id": "network_123",
    "price": "500.00",
    "price_currency": "MXN"
  }'

Status Summary

Status	Description	Required Provider Action
READY	The order is pending payment.	Verify amount and call start-payment.
PAYMENT_STARTED	The order is being collected.	Receive money and call confirm-payment.
COMPLETED	Money was successfully collected.	Provide receipt to user.
CANCELLED	The order was cancelled.	Do not receive money.