POST /v1/payments

Create a payment

Creates a new payment using the specified provider. Azoryx handles routing, provider communication, and returns a unified response regardless of the underlying payment method.

Request Body

Field	Type	Required	Description
amount	integer	yes	Amount in cents (e.g. 2990 = R$29.90)
currency	string	yes	ISO 4217 currency code. Supported: `BRL`, `MXN`, `COP`, `USD`
provider	string	yes	Payment provider slug. Options: `pix`, `oxxo`, `mercadopago`, `paypal`
description	string	optional	A description or order reference for the payment
metadata	object	optional	Custom key-value pairs for your own reference

Example Request

          cURL
          Node.js
          Python
        
curl https://api.azoryx.com/v1/payments \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
  "amount": 2990,
  "currency": "BRL",
  "provider": "pix",
  "description": "Payment #1234",
  "metadata": {
    "order_id": "ORD-5678"
  }
}'

Responses

201 Created

Payment created successfully

The payment has been initiated. Check the status field for the current state.

{
  "id": "pay_abc123",
  "amount": 2990,
  "currency": "BRL",
  "provider": "pix",
  "status": "pending",
  "qr_code": "00020126580014br.gov.bcb...",
  "expires_at": "2026-07-22T18:30:00Z",
  "created_at": "2026-07-22T18:00:00Z"
}

400 Bad Request

Invalid parameters

The request could not be processed due to invalid or missing parameters.

{
  "error": "validation_error",
  "message": "amount must be a positive integer",
  "field": "amount"
}

GET /v1/payments

List payments

Returns a paginated list of payments. Results are sorted by creation date, newest first. Use the query parameters to filter by status, provider, or date range.

Query Parameters

Field	Type	Required	Description
status	string	optional	Filter by status: `pending`, `completed`, `failed`, `refunded`
provider	string	optional	Filter by provider slug: `pix`, `oxxo`, `mercadopago`, `paypal`
page	integer	optional	Page number for pagination. Defaults to `1`.
per_page	integer	optional	Results per page. Defaults to `20`, max `100`.

Example Request

          cURL
        
curl https://api.azoryx.com/v1/payments?status=completed&page=1 \
  -H "Authorization: Bearer sk_live_..."

Responses

200 OK

List of payments

Returns a paginated array of payment objects.

{
  "data": [
    {
      "id": "pay_abc123",
      "amount": 2990,
      "currency": "BRL",
      "provider": "pix",
      "status": "completed",
      "created_at": "2026-07-22T18:00:00Z"
    }
  ],
  "page": 1,
  "per_page": 20,
  "total": 42
}

GET /v1/payments/:id

Retrieve a payment

Returns the details of a single payment by its unique identifier. Use this endpoint to check the current status of a payment or retrieve provider-specific metadata.

Path Parameters

Field	Type	Required	Description
id	string	yes	The unique identifier of the payment (e.g. `pay_abc123`)

Example Request

          cURL
        
curl https://api.azoryx.com/v1/payments/pay_abc123 \
  -H "Authorization: Bearer sk_live_..."

Responses

200 OK

Payment details

Returns the full payment object with provider-specific details.

{
  "id": "pay_abc123",
  "amount": 2990,
  "currency": "BRL",
  "provider": "pix",
  "status": "completed",
  "description": "Payment #1234",
  "metadata": {
    "order_id": "ORD-5678"
  },
  "created_at": "2026-07-22T18:00:00Z",
  "updated_at": "2026-07-22T18:10:00Z"
}

404 Not Found

Payment not found

The specified payment ID does not exist or has been deleted.

{
  "error": "not_found",
  "message": "Payment pay_abc123 not found"
}

PUT /v1/payments/:id/confirm

Confirm a payment

Confirms a pending payment. Some providers require explicit confirmation to capture the funds after the customer authorizes the payment.

Request Body

Field	Type	Required	Description
amount	integer	optional	Partial amount to capture (in cents). Defaults to full amount.

Example Request

          cURL
        
curl -X PUT https://api.azoryx.com/v1/payments/pay_abc123/confirm \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
  "amount": 2990
}'

Responses

200 OK

Payment confirmed

The payment has been confirmed and captured.

{
  "id": "pay_abc123",
  "status": "completed",
  "captured_amount": 2990,
  "confirmed_at": "2026-07-22T18:10:00Z"
}

GET /v1/payment-methods?market=:market

List payment methods

Returns the available payment methods for a given market. Use the market query parameter to filter by country or region.

Query Parameters

Field	Type	Required	Description
market	string	yes	Market code. Options: `br`, `mx`, `co`, `us`

Example Request

          cURL
        
curl https://api.azoryx.com/v1/payment-methods?market=br \
  -H "Authorization: Bearer sk_live_..."

Responses

200 OK

Available payment methods

Returns the list of active payment methods for the specified market.

{
  "market": "br",
  "methods": [
    {
      "provider": "pix",
      "type": "instant",
      "fee": "0.033%"
    },
    {
      "provider": "mercadopago",
      "type": "wallet",
      "fee": "0.050%"
    }
  ]
}

Webhooks

When a payment status changes, azoryx sends a webhook to the URL configured in your dashboard. All webhooks include a signature header for verification.

// POST /webhooks/azoryx
{
  "type": "payment.completed",
  "data": {
    "id": "pay_abc123",
    "status": "completed",
    "amount": 2990,
    "currency": "BRL"
  },
  "timestamp": "2026-07-22T18:05:00Z"
}