Payment Modifications

Modifications let you operate on payments that are already completed (both online and POS). All modification endpoints return HTTP 202 Accepted because the operation is processed asynchronously by the payment processor.

Session vs Payment: important reminder

Modifications do not operate on the session (sessionId), but on the payment (paymentReference). The session is the container created when you call POST /payment/session; the payment is the real transaction created when the customer pays successfully. Once the session is completed, it no longer changes: what matters from that point on is the payment.

For more detail on this distinction, see Session vs Payment.

How to obtain paymentReference

All modifications require a paymentReference that identifies the real payment:

• For online payments: query the session with GET /payment/session/{sessionId}. When the session is completed, the paymentReference field contains the authorized payment reference
• For POS payments: it is the paymentReference returned directly in the POST /pos/payment response (matches posPaymentId)

Both reference types work interchangeably on all modification endpoints.

---

Refund

Refunds all or part of the amount of a completed payment.

Live: POST https://aviratopayments.com/external/v1/payment/refund
Test: POST https://aviratopayments.com/external/v1/test/payment/refund

Body parameters

Allowed values for reason

Important: Values are case-sensitive and include a space in CUSTOMER REQUEST. Sending customer request or Customer Request will produce a 400 error.

Example

curl -X POST https://aviratopayments.com/external/v1/payment/refund \
  -H "X-API-KEY: your_live_api_key" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: refund-order-12345" \
  -d '{
    "webcode": "SHOP01",
    "paymentReference": "SHOP01-PXT-17195123456789",
    "amount": {
      "value": 5000,
      "currency": "EUR"
    },
    "reason": "CUSTOMER REQUEST"
  }'

Response (202)

{
  "success": true,
  "data": {
    "refundReference": "SHOP01-RFX-17195234567890",
    "paymentReference": "SHOP01-PXT-17195123456789",
    "amount": {
      "value": 5000,
      "currency": "EUR"
    },
    "status": "pending",
    "createdAt": "2026-06-29 14:00:00"
  }
}

The refundReference (format {webcode}-RFX-{timestamp} in Live, {webcode}-RFXT-{timestamp} in Test) identifies this refund operation. Use it for tracking in the modification listing.

Partial vs full refund

You can refund any amount less than or equal to the original payment amount. If you need multiple partial refunds on the same payment, you can do so as long as the total sum does not exceed the original amount.

---

Capture

Captures all or part of a pre-authorization (payment created with isPreAuth: true).

Live: POST https://aviratopayments.com/external/v1/payment/capture
Test: POST https://aviratopayments.com/external/v1/test/payment/capture

Body parameters

Example

curl -X POST https://aviratopayments.com/external/v1/payment/capture \
  -H "X-API-KEY: your_live_api_key" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: capture-preauth-67890" \
  -d '{
    "webcode": "SHOP01",
    "paymentReference": "SHOP01-PXT-17195123456789",
    "amount": {
      "value": 15000,
      "currency": "EUR"
    }
  }'

Response (202)

{
  "success": true,
  "data": {
    "captureReference": "SHOP01-CTX-17195345678901",
    "paymentReference": "SHOP01-PXT-17195123456789",
    "amount": {
      "value": 15000,
      "currency": "EUR"
    },
    "status": "received",
    "createdAt": "2026-06-29 15:00:00"
  }
}

The captureReference (format {webcode}-CTX-{timestamp} in Live, {webcode}-CTXT-{timestamp} in Test) identifies this capture operation.

Partial capture

If you pre-authorized 500 EUR but the final service amount was 450 EUR, you can capture only 45000 cents. The difference is released automatically.

Excess capture

If you try to capture an amount greater than pre-authorized, the request is accepted (HTTP 202) but the processor will reject the operation. You will receive a webhook with result: "failure" indicating that the amount exceeds what was authorized.

---

Cancellation (Cancel)

Cancels a pre-authorization before it is captured. Releases funds held on the customer's card.

Live: POST https://aviratopayments.com/external/v1/payment/cancel
Test: POST https://aviratopayments.com/external/v1/test/payment/cancel

Body parameters

Example

curl -X POST https://aviratopayments.com/external/v1/payment/cancel \
  -H "X-API-KEY: your_live_api_key" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: cancel-preauth-11111" \
  -d '{
    "webcode": "SHOP01",
    "paymentReference": "SHOP01-PXT-17195123456789"
  }'

Response (202)

{
  "success": true,
  "data": {
    "cancelReference": "SHOP01-CAX-17195456789012",
    "paymentReference": "SHOP01-PXT-17195123456789",
    "status": "received",
    "createdAt": "2026-06-29 16:00:00"
  }
}

The cancelReference (format {webcode}-CAX-{timestamp} in Live, {webcode}-CAXT-{timestamp} in Test) identifies this cancellation operation.

---

Extension (Extend)

Extends the validity period of a pre-authorization before it expires. Pre-authorizations have limited validity (usually 7-28 days depending on the issuing bank). If you need more time, you can extend it. The extension adds 28 additional days counting from the moment it is requested.

Live: POST https://aviratopayments.com/external/v1/payment/extend
Test: POST https://aviratopayments.com/external/v1/test/payment/extend

Body parameters

No amount or currency needs to be sent: the extension keeps the original amount.

Example

curl -X POST https://aviratopayments.com/external/v1/payment/extend \
  -H "X-API-KEY: your_live_api_key" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: extend-preauth-22222" \
  -d '{
    "webcode": "SHOP01",
    "paymentReference": "SHOP01-PXT-17195123456789"
  }'

Response (202)

{
  "success": true,
  "data": {
    "updateReference": "SHOP01-UPX-17195567890123",
    "paymentReference": "SHOP01-PXT-17195123456789",
    "amount": {
      "value": 15000,
      "currency": "EUR"
    },
    "status": "received",
    "createdAt": "2026-06-29 17:00:00"
  }
}

The updateReference (format {webcode}-UPX-{timestamp} in Live, {webcode}-UPXT-{timestamp} in Test) identifies this extension operation. The returned amount is the original payment amount.

---

Modification status

Modifications are processed asynchronously. The status returned in the initial response depends on the operation and evolves as the processor confirms:

Note on initial statuses: Refund operations return pending because refunds may take time to process. Capture, cancel, and extend return received because processor confirmation is faster. In both cases, the final status will be success or failed.

How to know when a modification completes:

1. Webhooks (recommended): You will receive an automatic webhook when the processor confirms the operation. See Webhooks for format details and examples
2. Query: You can check the updated status with List modifications

---

Modifications in the Test environment

In the Test environment, modifications are processed in a simulated and immediate way. No real processor is contacted. The backend generates a simulated webhook with the result (success or failed) that is sent to your webhook URL within seconds.

Simulated behavior by type

Important: In Test, the confirmation webhook is generated automatically at request time. In Live, the webhook arrives when the real processor confirms the operation (seconds to minutes).

---

Quick reference marker guide

Each modification type generates a reference with an identifying prefix:

Common modification errors