External API

Developer documentation

Integrate online and POS payments, query operations, and receive webhooks with the Avirato Payments external API.

Complete Examples

End-to-end integration flow examples with cURL. Replace the API key and webcode with your own.

---

Flow 1: Complete online payment (Live)

1.1 Create payment session

curl -X POST https://aviratopayments.com/external/v1/payment/session \
  -H "X-API-KEY: tu_api_key_live" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-12345-payment" \
  -d '{
    "webcode": "SHOP01",
    "amount": {
      "value": 25000,
      "currency": "EUR"
    },
    "urlOk": "https://tu-sistema.com/pago-ok",
    "urlKo": "https://tu-sistema.com/pago-error",
    "description": "Pedido #12345 - Servicio premium",
    "customReference": "ORD-2026-12345",
    "isPreAuth": false
  }'

Response (201 Created):

{
  "success": true,
  "data": {
    "sessionId": "SHOP01-EXT-17195000001234",
    "paymentUrl": "https://aviratopayments.com/pay-external/eyJhbGciOi...",
    "status": "pending",
    "amount": { "value": 25000, "currency": "EUR" },
    "description": "Pedido #12345 - Servicio premium",
    "customReference": "ORD-2026-12345",
    "isPreAuth": false,
    "createdAt": "2026-06-28 10:30:00"
  }
}

1.2 Redirect the customer

Redirect the customer to the returned paymentUrl. The customer will see the secure payment page and complete the transaction. After paying they will be redirected to urlOk (success) or urlKo (failure/cancellation).

1.3 Query payment status

Once the customer has been redirected back, query the session to get the result and paymentReference:

curl -X GET "https://aviratopayments.com/external/v1/payment/session/SHOP01-EXT-17195000001234?webcode=SHOP01" \
  -H "X-API-KEY: tu_api_key_live"

Response (200 OK):

{
  "success": true,
  "data": {
    "sessionId": "SHOP01-EXT-17195000001234",
    "status": "completed",
    "amount": { "value": 25000, "currency": "EUR" },
    "countryCode": "ES",
    "shopperLocale": "es-ES",
    "description": "Pedido #12345 - Servicio premium",
    "customReference": "ORD-2026-12345",
    "isPreAuth": false,
    "urlOk": "https://tu-sistema.com/pago-ok",
    "urlKo": "https://tu-sistema.com/pago-error",
    "createdAt": "2026-06-28 10:30:00",
    "paymentReference": "SHOP01-PXT-17195000005678",
    "completedAt": "2026-06-28 10:35:22",
    "paymentStatus": "AUTHORISED",
    "attempts": [
      {
        "paymentReference": "SHOP01-PXT-17195000005678",
        "status": "authorised",
        "createdAt": "2026-06-28 10:34:00"
      }
    ]
  }
}

The paymentReference (SHOP01-PXT-17195000005678) is what you will use for any subsequent modification.

---

Flow 2: Pre-authorization + capture (or cancellation)

2.1 Create pre-authorization

curl -X POST https://aviratopayments.com/external/v1/payment/session \
  -H "X-API-KEY: tu_api_key_live" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: preauth-order-67890" \
  -d '{
    "webcode": "SHOP01",
    "amount": {
      "value": 50000,
      "currency": "EUR"
    },
    "urlOk": "https://tu-sistema.com/pago-ok",
    "urlKo": "https://tu-sistema.com/pago-error",
    "description": "Deposito garantia - Servicio #67890",
    "customReference": "ORD-2026-67890",
    "isPreAuth": true
  }'

The customer completes the pre-authorization. Obtain paymentReference by querying the session as in Flow 1.

2.2 Capture the final amount (partial)

When the service completes, capture the actual amount (which may be less than pre-authorized):

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

Response (202 Accepted):

{
  "success": true,
  "data": {
    "captureReference": "SHOP01-CTX-17195100001234",
    "paymentReference": "SHOP01-PXT-17195000009876",
    "amount": { "value": 45000, "currency": "EUR" },
    "status": "received",
    "createdAt": "2026-06-29 11:00:00"
  }
}

2.3 (Alternative) Cancel the pre-authorization

If the service is cancelled, release the funds:

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

Response (202 Accepted):

{
  "success": true,
  "data": {
    "cancelReference": "SHOP01-CAX-17195200001234",
    "paymentReference": "SHOP01-PXT-17195000009876",
    "status": "received",
    "createdAt": "2026-06-29 12:00:00"
  }
}

---

Flow 3: POS payment + refund (Live)

3.1 List available terminals

curl -X GET "https://aviratopayments.com/external/v1/pos/terminals?webcode=SHOP01" \
  -H "X-API-KEY: tu_api_key_live"

Response (200 OK):

{
  "success": true,
  "data": [
    {
      "poiId": "V400m-123456789",
      "status": "boarded",
      "name": "Mostrador Principal",
      "model": "V400m",
      "createdAt": "2026-01-15T10:00:00Z",
      "updatedAt": "2026-06-20T08:30:00Z"
    }
  ]
}

3.2 Send payment to terminal

curl -X POST https://aviratopayments.com/external/v1/pos/payment \
  -H "X-API-KEY: tu_api_key_live" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: pos-sale-11111" \
  -d '{
    "webcode": "SHOP01",
    "poiId": "V400m-123456789",
    "amount": {
      "value": 8500,
      "currency": "EUR"
    },
    "description": "Venta mostrador #205",
    "customReference": "VENTA-205-20260628"
  }'

Response (200 OK):

{
  "success": true,
  "data": {
    "posPaymentId": "SHOP01-POSX-17195300001234",
    "paymentReference": "SHOP01-POSX-17195300001234",
    "poiId": "V400m-123456789",
    "amount": { "value": 8500, "currency": "EUR" },
    "status": "success",
    "isPreAuth": false,
    "pspReference": "KVGQSN3K2SKFNVNS",
    "description": "Venta mostrador #205",
    "customReference": "VENTA-205-20260628",
    "createdAt": "2026-06-28 14:15:00"
  }
}

3.3 Partial refund of POS payment

The POS payment paymentReference is the posPaymentId:

curl -X POST https://aviratopayments.com/external/v1/payment/refund \
  -H "X-API-KEY: tu_api_key_live" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: refund-pos-11111" \
  -d '{
    "webcode": "SHOP01",
    "paymentReference": "SHOP01-POSX-17195300001234",
    "amount": {
      "value": 2000,
      "currency": "EUR"
    },
    "reason": "CUSTOMER REQUEST"
  }'

Response (202 Accepted):

{
  "success": true,
  "data": {
    "refundReference": "SHOP01-RFX-17195400001234",
    "paymentReference": "SHOP01-POSX-17195300001234",
    "amount": { "value": 2000, "currency": "EUR" },
    "status": "pending",
    "createdAt": "2026-06-28 15:00:00"
  }
}

---

Flow 4: List payments with pagination

4.1 First page

curl -X GET "https://aviratopayments.com/external/v1/payment/sessions?webcode=SHOP01&status=completed&take=5" \
  -H "X-API-KEY: tu_api_key_live"

Response:

{
  "success": true,
  "data": {
    "payments": [
      {
        "sessionId": "SHOP01-EXT-17195000001234",
        "status": "completed",
        "amount": { "value": 25000, "currency": "EUR" },
        "description": "Pedido #12345",
        "customReference": "ORD-2026-12345",
        "isPreAuth": false,
        "createdAt": "2026-06-28 10:30:00",
        "completedAt": "2026-06-28 10:35:22",
        "paymentReference": "SHOP01-PXT-17195000005678",
        "paymentStatus": "AUTHORISED"
      }
    ],
    "meta": {
      "cursor": "eyJpZCI6NX0=",
      "hasMore": true,
      "total": 23
    }
  }
}

4.2 Next page

Use the cursor from the previous response:

curl -X GET "https://aviratopayments.com/external/v1/payment/sessions?webcode=SHOP01&status=completed&take=5&cursor=eyJpZCI6NX0=" \
  -H "X-API-KEY: tu_api_key_live"

Repeat until meta.hasMore is false.

---

Flow 5: Verify modifications

5.1 List modifications for an online session

curl -X GET "https://aviratopayments.com/external/v1/payment/session/SHOP01-EXT-17195000001234/modifications?webcode=SHOP01" \
  -H "X-API-KEY: tu_api_key_live"

5.2 List modifications for a POS payment

curl -X GET "https://aviratopayments.com/external/v1/pos/payment/SHOP01-POSX-17195300001234/modifications?webcode=SHOP01" \
  -H "X-API-KEY: tu_api_key_live"

5.3 List all modifications with filters

curl -X GET "https://aviratopayments.com/external/v1/modifications?webcode=SHOP01&type=refund&status=success&take=10" \
  -H "X-API-KEY: tu_api_key_live"

Response (200 OK):

{
  "success": true,
  "data": {
    "modifications": [
      {
        "operationReference": "SHOP01-RFX-17195400001234",
        "operationType": "refund",
        "paymentReference": "SHOP01-POSX-17195300001234",
        "sessionId": "SHOP01-POSX-17195300001234",
        "status": "success",
        "requestedAt": "2026-06-28 15:00:00",
        "createdAt": "2026-06-28 15:00:00",
        "resolvedAt": "2026-06-28 15:00:05",
        "amount": { "value": 2000, "currency": "EUR" },
        "reason": "CUSTOMER REQUEST"
      }
    ],
    "meta": {
      "cursor": null,
      "hasMore": false,
      "total": 1
    }
  }
}

---

Flow 6: Complete online payment in TEST environment

This flow shows how to test the integration without real money.

6.1 Create payment session (Test)

curl -X POST https://aviratopayments.com/external/v1/test/payment/session \
  -H "X-API-KEY: tu_api_key_test" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: test-order-99999" \
  -d '{
    "webcode": "SHOP01",
    "amount": {
      "value": 10000,
      "currency": "EUR"
    },
    "urlOk": "https://tu-sistema.com/pago-ok",
    "urlKo": "https://tu-sistema.com/pago-error",
    "description": "Test - Pedido #99999",
    "customReference": "TEST-ORD-99999"
  }'

Response (201 Created):

{
  "success": true,
  "data": {
    "sessionId": "SHOP01-EXTT-17195500001234",
    "paymentUrl": "https://aviratopayments.com/pay-external-test/eyJhbGciOi...",
    "status": "pending",
    "amount": { "value": 10000, "currency": "EUR" },
    "description": "Test - Pedido #99999",
    "customReference": "TEST-ORD-99999",
    "isPreAuth": false,
    "createdAt": "2026-06-28 16:00:00"
  }
}

Note that sessionId has the -EXTT- infix and paymentUrl points to /pay-external-test/.

6.2 Simulate payment

Redirect the customer to paymentUrl. They will see a simulated payment form. For a successful payment, enter:

  • Number: 4111 1111 1111 1111
  • Expiry: 12/30
  • CVC: 737
  • Name: Test User (any name that is not a special value)

To simulate a decline, use cardholder name: DECLINED

6.3 Receive simulated webhook

Immediately after completing payment, you will receive a webhook at your configured URL:

{
  "event_code": "AUTHORISATION",
  "data": {
    "amount": 10000,
    "currency": "EUR",
    "paymentReference": "SHOP01-PXTT-17195500005678",
    "paymentStatus": "AUTHORISED",
    "description": "Test - Pedido #99999",
    "customReference": "TEST-ORD-99999",
    "paymentSource": "external_api"
  }
}

6.4 Query status (Test)

curl -X GET "https://aviratopayments.com/external/v1/test/payment/session/SHOP01-EXTT-17195500001234?webcode=SHOP01" \
  -H "X-API-KEY: tu_api_key_test"

The response will have status: "completed" with the test environment paymentReference.

---

Flow 7: POS payment in TEST environment

7.1 List simulated terminals

curl -X GET "https://aviratopayments.com/external/v1/test/pos/terminals?webcode=SHOP01" \
  -H "X-API-KEY: tu_api_key_test"

Response (200 OK):

{
  "success": true,
  "data": [
    {
      "poiId": "V400m-TEST-000001",
      "status": "boarded",
      "name": "Terminal Test 1 - Mostrador",
      "model": "V400m",
      "createdAt": "2026-01-01T00:00:00Z",
      "updatedAt": "2026-01-01T00:00:00Z"
    },
    {
      "poiId": "S1F2-TEST-000002",
      "status": "boarded",
      "name": "Terminal Test 2 - Terraza",
      "model": "S1F2",
      "createdAt": "2026-01-01T00:00:00Z",
      "updatedAt": "2026-01-01T00:00:00Z"
    },
    {
      "poiId": "P400Plus-TEST-000003",
      "status": "boarded",
      "name": "Terminal Test 3 - Almacen",
      "model": "P400Plus",
      "createdAt": "2026-01-01T00:00:00Z",
      "updatedAt": "2026-01-01T00:00:00Z"
    }
  ]
}

With syncFromProvider=true only the 2 online terminals are returned (V400m-TEST-000001 and S1F2-TEST-000002).

7.2 Successful payment (amount does not end in 77, 99, or 55)

curl -X POST https://aviratopayments.com/external/v1/test/pos/payment \
  -H "X-API-KEY: tu_api_key_test" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: test-pos-001" \
  -d '{
    "webcode": "SHOP01",
    "poiId": "V400m-TEST-000001",
    "amount": {
      "value": 5000,
      "currency": "EUR"
    },
    "description": "Test POS - Venta #001",
    "customReference": "TEST-VENTA-001"
  }'

Response (200 OK) - Success (last 2 digits of 5000 are 00):

{
  "success": true,
  "data": {
    "posPaymentId": "SHOP01-POSXT-17195600001234",
    "paymentReference": "SHOP01-POSXT-17195600001234",
    "poiId": "V400m-TEST-000001",
    "amount": { "value": 5000, "currency": "EUR" },
    "status": "success",
    "isPreAuth": false,
    "pspReference": "test_psp_a1b2c3d4e5f67890",
    "description": "Test POS - Venta #001",
    "customReference": "TEST-VENTA-001",
    "createdAt": "2026-06-28 17:00:00"
  }
}

7.3 Declined payment (amount ends in 77)

curl -X POST https://aviratopayments.com/external/v1/test/pos/payment \
  -H "X-API-KEY: tu_api_key_test" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: test-pos-002" \
  -d '{
    "webcode": "SHOP01",
    "poiId": "V400m-TEST-000001",
    "amount": {
      "value": 10077,
      "currency": "EUR"
    },
    "description": "Test POS - Rechazo simulado"
  }'

Response (200 OK) - Declined:

{
  "success": true,
  "data": {
    "posPaymentId": "SHOP01-POSXT-17195600005678",
    "paymentReference": "SHOP01-POSXT-17195600005678",
    "poiId": "V400m-TEST-000001",
    "amount": { "value": 10077, "currency": "EUR" },
    "status": "failed",
    "isPreAuth": false,
    "pspReference": "test_psp_f8e7d6c5b4a39012",
    "errorMessage": "Card declined (test simulation)",
    "description": "Test POS - Rechazo simulado",
    "createdAt": "2026-06-28 17:05:00"
  }
}

7.4 Simulated timeout (amount ends in 99)

curl -X POST https://aviratopayments.com/external/v1/test/pos/payment \
  -H "X-API-KEY: tu_api_key_test" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: test-pos-003" \
  -d '{
    "webcode": "SHOP01",
    "poiId": "V400m-TEST-000001",
    "amount": {
      "value": 2599,
      "currency": "EUR"
    },
    "description": "Test POS - Timeout simulado"
  }'

Response (200 OK) - Timeout:

{
  "success": true,
  "data": {
    "posPaymentId": "SHOP01-POSXT-17195600009012",
    "paymentReference": "SHOP01-POSXT-17195600009012",
    "poiId": "V400m-TEST-000001",
    "amount": { "value": 2599, "currency": "EUR" },
    "status": "timeout",
    "isPreAuth": false,
    "errorMessage": "POS payment timeout. The payment may still be processed asynchronously via webhook.",
    "description": "Test POS - Timeout simulado",
    "createdAt": "2026-06-28 17:10:00"
  }
}

7.5 Offline terminal (502 error)

curl -X POST https://aviratopayments.com/external/v1/test/pos/payment \
  -H "X-API-KEY: tu_api_key_test" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: test-pos-004" \
  -d '{
    "webcode": "SHOP01",
    "poiId": "P400Plus-TEST-000003",
    "amount": {
      "value": 5000,
      "currency": "EUR"
    },
    "description": "Test POS - Terminal offline"
  }'

Response (502) - Terminal error:

{
  "success": false,
  "error": {
    "message": "Error in POS payment response: Reject",
    "code": 13004,
    "statusCode": 502,
    "traceId": "abc123def456..."
  }
}

7.6 Terminal busy (amount ends in 55)

curl -X POST https://aviratopayments.com/external/v1/test/pos/payment \
  -H "X-API-KEY: tu_api_key_test" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: test-pos-005" \
  -d '{
    "webcode": "SHOP01",
    "poiId": "V400m-TEST-000001",
    "amount": {
      "value": 1055,
      "currency": "EUR"
    },
    "description": "Test POS - Terminal ocupado"
  }'

Response (409) - Terminal busy:

{
  "success": false,
  "error": {
    "message": "Terminal busy (test simulation)",
    "code": 13005,
    "statusCode": 409,
    "traceId": "abc123def456..."
  }
}

7.7 Invalid poiId (400 error)

curl -X POST https://aviratopayments.com/external/v1/test/pos/payment \
  -H "X-API-KEY: tu_api_key_test" \
  -H "Content-Type: application/json" \
  -d '{
    "webcode": "SHOP01",
    "poiId": "TERMINAL-INVENTADO-123",
    "amount": {
      "value": 1000,
      "currency": "EUR"
    }
  }'

Response (400) - Invalid terminal:

{
  "success": false,
  "error": {
    "message": "The specified terminal is not valid: device not found",
    "code": 12001,
    "statusCode": 400,
    "traceId": "abc123def456..."
  }
}

---

Flow 8: Modification in TEST environment + webhook

8.1 Refund in Test

curl -X POST https://aviratopayments.com/external/v1/test/payment/refund \
  -H "X-API-KEY: tu_api_key_test" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: test-refund-001" \
  -d '{
    "webcode": "SHOP01",
    "paymentReference": "SHOP01-PXTT-17195500005678",
    "amount": {
      "value": 3000,
      "currency": "EUR"
    },
    "reason": "CUSTOMER REQUEST"
  }'

Response (202 Accepted):

{
  "success": true,
  "data": {
    "refundReference": "SHOP01-RFXT-17195700001234",
    "paymentReference": "SHOP01-PXTT-17195500005678",
    "amount": { "value": 3000, "currency": "EUR" },
    "status": "pending",
    "createdAt": "2026-06-28 18:00:00"
  }
}

8.2 Simulated webhook you will receive

Immediately (< 1 second) you will receive at your webhook URL:

{
  "event_code": "REFUND",
  "data": {
    "amount": 3000,
    "currency": "EUR",
    "paymentReference": "SHOP01-PXTT-17195500005678",
    "refundReason": "CUSTOMER REQUEST",
    "refundReference": "SHOP01-RFXT-17195700001234",
    "status": "success",
    "customReference": "TEST-ORD-99999",
    "paymentSource": "external_api"
  }
}

In Test, modification webhooks are generated and sent automatically after the request, without waiting for the processor.