Create a transaction

POST/api/wallet/transactions

Creates a pending transaction on behalf of the API key. The server sets origin_id, id, created_at, and the initial status; do not send these fields.

Transaction creation request body fields
Field	Type	Description
`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.

Example · cURL

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"
  }'

200 response · illustrative example

{
  "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"
}

This example charges 10 Azeitonas before the fee. Store the returned ID to build the payment URL and retrieve the result. Missing optional fields may be omitted or returned as empty/null values.