# York Wallet API

> Create transactions in your app and let users confirm payment in their York Wallet. Creating a transaction does not move funds.

API base URL: https://yorkonthe.net/api/wallet
All API responses are JSON. This documentation is public and written in English.

## Documentation

- [Overview](https://yorkonthe.net/api/wallet/reference): API overview and endpoint index.
- [Getting started](https://yorkonthe.net/api/wallet/reference/getting-started): Create a key and integrate the payment flow.
- [Authentication](https://yorkonthe.net/api/wallet/reference/authentication): API key headers, permissions, and key management.
- [Create a transaction](https://yorkonthe.net/api/wallet/reference/create): POST request fields and examples.
- [Retrieve a transaction](https://yorkonthe.net/api/wallet/reference/retrieve): GET requests and payment verification.
- [Cancel a transaction](https://yorkonthe.net/api/wallet/reference/cancel): DELETE requests for pending transactions.
- [Payment and statuses](https://yorkonthe.net/api/wallet/reference/payment): Confirmation, expiration, and fees.
- [Webhooks](https://yorkonthe.net/api/wallet/reference/webhooks): Payment notifications and delivery limitations.
- [Errors and best practices](https://yorkonthe.net/api/wallet/reference/errors): HTTP errors and reliable order fulfillment.

## Authentication

Create and manage Wallet API keys at https://yorkonthe.net/desenvolvedor/carteira.
Send x-api-key: YOUR_WALLET_API_KEY with every API request. For POST, also send Content-Type: application/json.
Wallet API keys are separate from general API keys. These endpoints do not require a Bearer token or a user session.
Default permission: transactions:azeitonas. The transactions:caroços permission is managed by administrators.
Keep the key on your server. Regenerating a key invalidates its previous secret. Disabled or suspended keys cannot access the API.

## Integration flow

1. Create a transaction on your server and store the returned transaction ID with your order.
2. Send the user to https://yorkonthe.net/carteira/pagar/TRANSACTION_ID to sign in and confirm payment.
3. Retrieve the transaction on your server using the key that created it.
4. Verify status=paid, recipient, payer, amount, currency, and order reference before fulfillment.
5. Fulfill atomically and only once per transaction ID. Reaching completion_url is not proof of payment.

## Endpoints

### POST /api/wallet/transactions

Creates a pending transaction and returns the transaction object with HTTP 200.
The server sets id, origin_id, created_at, and the initial status. Do not send these fields.

- receiver_id (`string` · required): The recipient’s York user ID. Use the ID, not the `@username`.
- amount (`integer` · required): Integer from 1 to 50000, excluding the fee. For Azeitonas, 100 = 1 Azeitona (maximum 500 Azeitonas). For Caroços, 100 = 100 Caroços (maximum 50000 Caroços).
- payer_id (`string` · optional): The payer’s user ID. When omitted, the user who confirms payment becomes the payer.
- currency (`string` · optional): Azeitonas (default) or Caroços. Send the lowercase API values: `azeitonas` or `caroços`, including the cedilla. Your key needs the corresponding permission.
- type (`string` · optional): `transfer` (default), `purchase`, `purchase_return`, or `reward`. `fee` is reserved for York. The `type` does not automatically confirm payment.
- external_id (`string` · optional): Your app’s order reference, up to 64 characters. This is not an idempotency key.
- metadata (`object` · optional): A JSON object containing additional data to correlate the transaction with your app.
- return_url (`string` · optional): URL used by the return button before payment or after an error. Up to 250 characters.
- completion_url (`string` · optional): URL used by the continue button after payment. Up to 250 characters.

```sh
curl -X POST "https://yorkonthe.net/api/wallet/transactions" \
  -H "x-api-key: YOUR_WALLET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "receiver_id": "RECIPIENT_USER_ID",
    "amount": 1000,
    "currency": "azeitonas",
    "type": "purchase",
    "external_id": "order-123",
    "metadata": { "order": "order-123" },
    "return_url": "https://your-app.example/orders/123",
    "completion_url": "https://your-app.example/orders/123/complete"
  }'
```

Illustrative response (optional fields may be omitted or empty/null):

```json
{
  "id": "TRANSACTION_ID",
  "receiver_id": "RECIPIENT_USER_ID",
  "amount": 1000,
  "currency": "azeitonas",
  "type": "purchase",
  "status": "pending",
  "origin_id": "API_KEY_ID",
  "external_id": "order-123",
  "metadata": {
    "order": "order-123"
  },
  "return_url": "https://your-app.example/orders/123",
  "completion_url": "https://your-app.example/orders/123/complete",
  "created_at": "2026-10-05T12:00:00.000Z"
}
```

### GET /api/wallet/transactions/{transactionID}

Returns the transaction object with HTTP 200. Use the key that created it; another app’s key receives 403.
After payment, status is paid, payer_id identifies the payer, and paid_at records the payment date.

```sh
curl "https://yorkonthe.net/api/wallet/transactions/TRANSACTION_ID" \
  -H "x-api-key: YOUR_WALLET_API_KEY"
```

### DELETE /api/wallet/transactions/{transactionID}

Changes pending to expired and returns the updated transaction with HTTP 200. The record remains in history.
Use the key that created it. Paid or already expired transactions return 400. This endpoint does not refund payments.

```sh
curl -X DELETE "https://yorkonthe.net/api/wallet/transactions/TRANSACTION_ID" \
  -H "x-api-key: YOUR_WALLET_API_KEY"
```

## Payment rules

- Statuses: pending (awaiting confirmation), paid (funds transferred), expired (cannot be paid).
- amount is an integer from 1 to 50000, excluding fees. For Azeitonas, it is in hundredths: 100 = 1 Azeitona (maximum 500 Azeitonas). For Caroços, it is in whole units: 100 = 100 Caroços (maximum 50000 Caroços).
- Currency names are Azeitonas and Caroços. In API requests, currency values are exactly `azeitonas` or `caroços` (lowercase, including the cedilla).
- Azeitonas fee, in hundredths: max(1, floor(amount * 0.069)). The payer covers amount plus fee; the recipient receives amount. For amount=1000, total=1069. Caroços have no fee.
- Payments are valid for 30 minutes after creation. Expiration is checked when payment is attempted; GET may still return pending after that window.
- If payer_id is provided, only that user can pay; otherwise the confirming user becomes the payer. The recipient cannot pay their own transaction.
- return_url is used before payment or after an error; completion_url is used after payment. Both fall back to /carteira.
- purchase_return is a new transaction type and still requires confirmation; it is not an automatic refund.

## Webhooks

Configure a webhook URL on the API key to receive POST JSON notifications containing event and data.
transactions.paid reports payment confirmation. Its data includes id, status, payer, paid_at, subtotal, fee, and total.
transactions.expired reports expiration with the transaction in data and status=expired. The current DELETE authentication path does not load the webhook URL, so do not rely on a cancellation notification.
Webhooks have no signature or retry guarantee. Treat them as a signal to retrieve and verify a transaction, not as proof of payment.

## Errors and reliability

Error response shape: { "message": "Error description" }.
- 400: Invalid JSON/fields, missing currency permission, reserved fee type, or cancellation of a non-pending transaction.
- 401: Missing x-api-key header.
- 403: Invalid, disabled, or suspended key, or a transaction created by another key.
- 404: Transaction ID not found.
Each POST can create a new transaction. external_id is a reference, not an idempotency key. Reconcile ambiguous creation timeouts before retrying.
These endpoints do not provide transaction listing, lookup by external_id, or public payment confirmation. Users confirm payments on York.