canonical: https://jentic.com/apis/payphone.app/payphone-api

# Payphone App PayPhone API

Jentic publishes the only available OpenAPI specification for PayPhone API, keeping it validated and agent-ready. PayPhone is an Ecuadorian mobile payment platform that enables merchants to create sales transactions, query transaction status by system ID, and look up transactions by client reference. The API serves the Latin American market with bearer token authentication and a focused 3-endpoint design for payment initiation and tracking.

## For AI agents

Create mobile payment transactions and check their status for Ecuadorian and Latin American commerce through PayPhone's payment gateway.

## Scope

Does not handle card tokenization, recurring billing, or multi-country payment routing - use for mobile payment transactions in Ecuador only.

## Capabilities

- Initiate mobile payment transactions with configurable amounts and metadata
- Query transaction status and details using the PayPhone system transaction ID
- Look up transactions by merchant-assigned client reference ID
- Process payments through Ecuador's PayPhone mobile payment network
- Track payment completion and settlement status in real time

## Use cases

### Mobile Commerce Payment in Ecuador

Accept payments from Ecuadorian customers through PayPhone's mobile payment network. The API initiates a sale transaction and returns a transaction ID for tracking. PayPhone handles the customer-facing payment flow including mobile wallet authorization, while the merchant polls for completion status.

Example prompt: Create a sale transaction for $25.00 USD via POST `/api/Sale` and then check the status using GET `/api/Sale/{transactionId}`

### Transaction Reconciliation

Reconcile payment records by looking up transactions using either the PayPhone system ID or the merchant's own client transaction reference. This supports automated bookkeeping workflows where agents need to match internal orders with PayPhone payment confirmations.

Example prompt: Look up a transaction by client reference ID using GET `/api/Sale/client/{clientTransactionId}` and extract the payment amount and status

### AI Agent Payment Processing

AI agents use the PayPhone API through Jentic to process mobile payments in Ecuador without managing bearer token refresh or transaction polling logic directly. Jentic provides operation discovery and credential isolation so agents can focus on business logic.

Example prompt: Search Jentic for 'create a mobile payment in Ecuador', load the PayPhone sale operation schema, and execute a transaction for $15.00 USD

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| POST | `/api/Sale` | Create a payment transaction |
| GET | `/api/Sale/{transactionId}` | Get transaction by system ID |
| GET | `/api/Sale/client/{clientTransactionId}` | Get transaction by client reference |

## Key resources

- **Sales** — Create payment transactions, query by system ID, and look up by client reference

## Why Jentic

- **Setup:** Wiring PayPhone by hand means learning its bearer token auth and coding calls against its Ecuadorian sale and lookup endpoints yourself. Through Jentic you install once, import PayPhone from the API Directory, store the token once, and your agent calls it.
- **Permission scoping:** PayPhone puts the transaction id in the URL path (`/api/Sale/{transactionId}`), so a rule can pin your agent to reading one sale by its transaction id. You choose the operations it may call, so creating new sales is not included unless you add it.
- **Credential handling:** Your PayPhone bearer token is stored once, encrypted, by your own Jentic One instance and injected at execution time. It never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'create a mobile payment in Ecuador' or 'look up a sale by transaction id', and Jentic returns the matching PayPhone operation with its input schema so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **PayPhone Card API** — Card-specific payment processing within the PayPhone ecosystem
- **PayRetailers API** — Broader Latin American payment gateway covering multiple countries
- **Stripe** — Global payment processor with Latin American market support

## FAQ

### Why is there no official OpenAPI spec for PayPhone API?

PayPhone does not publish an OpenAPI specification. Jentic generates and maintains this spec so that AI agents and developers can call PayPhone API via structured tooling. It is validated against the live API and kept up to date. Get started with Jentic One, the self-hosted execution layer.

### What authentication does the PayPhone API use?

The PayPhone API uses Bearer token authentication. You include your access token in the Authorization header as 'Bearer {token}' with every request. Through Jentic, bearer tokens are stored encrypted in your Jentic One instance and agents receive scoped access without handling raw credentials.

### Can I look up a PayPhone transaction by my own reference ID?

Yes. The GET `/api/Sale/client/{clientTransactionId}` endpoint allows you to retrieve transaction details using the merchant-assigned client reference ID that you provided when creating the sale. This is useful for reconciliation with your internal order system.

### How do I create a payment transaction through Jentic?

Use Jentic to search for the operation 'create a PayPhone sale', load the schema for POST `/api/Sale`, and execute with your transaction amount and client reference. The response includes the system transaction ID for status tracking.

### What currencies does the PayPhone API support?

The PayPhone API processes transactions in USD, which is the official currency of Ecuador. Transaction amounts are specified in cents (integer values) in the sale request body.

### Can I limit what my agent is allowed to do with the PayPhone API?

Yes. Because you run Jentic One yourself, your own rules decide which PayPhone operations and credentials the agent may use. Since PayPhone puts the transaction id in the URL path, you can pin the agent to reading a single sale through GET `/api/Sale/{transactionId}` or GET `/api/Sale/client/{clientTransactionId}` while keeping POST `/api/Sale` for creating new payments off the list unless you add it. The bearer token is held only by your instance and injected at execution time, so the agent calls only the endpoints you approve.