> ## Documentation Index
> Fetch the complete documentation index at: https://docs.esimmu.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Request a refund

> Asks us to refund one eSIM. We check with the network, so the decision arrives later on your webhook as `esim.refunded` or `esim.refund_declined`.

Safe to repeat: an open or settled request comes back as it stands, and only a declined one is opened again, with the `reason` and `note` you send this time.

Asks us to refund one eSIM. We check with the network before deciding, so the
answer is not in this response: it arrives later on your webhook as
[`esim.refunded` or `esim.refund_declined`](https://docs.esimmu.com/endpoints/webhooks#refund-events).
The response says where the request stands now.

Only an eSIM that has been issued to you can be refunded, and in practice only
one that was never installed. Check `refundable` on [Get eSIM
status](https://docs.esimmu.com/endpoints/esim-status.md) first.

## Asking again

Safe to repeat:

* An open request (`requested`) comes back as it is.
* A settled one (`refunded`) comes back as it is.
* A `declined` one is opened again, with the `reason` and `note` you send this
  time.


## OpenAPI

````yaml POST /v1/api_partner/partner_order_items/{topup_id}/refund_request
openapi: 3.1.0
info:
  title: eSIMmu API
  version: 1.0.0
  summary: Order eSIMs from your own systems over HTTP.
  description: >-
    Server-to-server API for eSIMmu API partners.


    **Ordering is asynchronous.** `POST /v1/api_partner/orders` returns `201`
    with one `topup_id` per unit ordered; the eSIM activation data itself
    arrives later as one `esim.issued` webhook per unit. There is no endpoint to
    poll for it.


    **Every request is signed.** Three headers carry an HMAC-SHA256 proof; see
    the `esimmuAccessKey`, `esimmuSignature` and `esimmuTimestamp` security
    schemes, and the Authentication guide for the full recipe and a test vector.


    **The path you sign is not the path in this document.** Paths here are
    relative to the server URL, which already ends in `/api`. The signature
    covers the full request path *including* that prefix:
    `/api/v1/api_partner/orders`, not `/v1/api_partner/orders`.


    **Product IDs (`option_id`) come from `GET /v1/api_partner/products`**, the
    catalogue at your own price. Fetch it daily and cache it.


    **There is no sandbox yet.**
servers:
  - url: https://api.esimmu.com/api
    description: Production
security:
  - esimmuAccessKey: []
    esimmuSignature: []
    esimmuTimestamp: []
tags:
  - name: Products
  - name: Orders
  - name: Refunds
paths:
  /v1/api_partner/partner_order_items/{topup_id}/refund_request:
    post:
      tags:
        - Refunds
      summary: Request a refund
      description: >-
        Asks us to refund one eSIM. We check with the network, so the decision
        arrives later on your webhook as `esim.refunded` or
        `esim.refund_declined`.


        Safe to repeat: an open or settled request comes back as it stands, and
        only a declined one is opened again, with the `reason` and `note` you
        send this time.
      operationId: requestRefund
      parameters:
        - $ref: '#/components/parameters/TopupId'
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RefundRequestBody'
            example:
              reason: esim_not_working
              note: No signal on arrival in Tokyo
      responses:
        '200':
          description: Where the refund request stands now.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RefundRequest'
              example:
                topup_id: '202611161200000000000001'
                status: requested
                requested_at: '2026-11-20T03:00:00Z'
                refunded_at: null
                declined_at: null
                decline_reason: null
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          description: 'The eSIM cannot be refunded yet: it has not been issued to you.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorList'
              example:
                errors:
                  - Only an issued eSIM can be refunded
components:
  parameters:
    TopupId:
      name: topup_id
      in: path
      required: true
      description: The eSIM, as returned by Create an order and sent in `esim.issued`.
      schema:
        type: string
      example: '202611161200000000000001'
  schemas:
    RefundRequestBody:
      type: object
      properties:
        reason:
          type: string
          description: Why you are asking, in your own words or as a short code.
        note:
          type: string
          description: Anything that helps us check with the network.
    RefundRequest:
      type: object
      properties:
        topup_id:
          type: string
        status:
          type: string
          enum:
            - requested
            - refunded
            - declined
        requested_at:
          type:
            - string
            - 'null'
          format: date-time
        refunded_at:
          type:
            - string
            - 'null'
          format: date-time
        declined_at:
          type:
            - string
            - 'null'
          format: date-time
        decline_reason:
          type:
            - string
            - 'null'
    ErrorList:
      type: object
      properties:
        errors:
          type: array
          items:
            type: string
    AuthError:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              const: unauthorized
            message:
              type: string
  responses:
    Unauthorized:
      description: Signing failed. See Authentication for each message.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/AuthError'
          example:
            error:
              code: unauthorized
              message: Invalid signature.
    NotFound:
      description: No eSIM with that `topup_id` on your account.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorList'
          example:
            errors:
              - eSIM not found
  securitySchemes:
    esimmuAccessKey:
      type: apiKey
      in: header
      name: X-Esimmu-Access-Key
      description: Your partner access key. Identifies you on every request.
    esimmuSignature:
      type: apiKey
      in: header
      name: X-Esimmu-Signature
      description: >-
        Lowercase hex HMAC-SHA256 over the five-line string
        `{METHOD}\n{REQUEST_PATH}\n{TIMESTAMP}\n{ACCESS_KEY}\n{BODY_SHA256}`,
        keyed with your **Base64-decoded** secret key.


        `REQUEST_PATH` includes the `/api` prefix and excludes the domain and
        any query string. `BODY_SHA256` is the lowercase hex SHA-256 of the
        exact body bytes you send; for a request with no body, hash the empty
        string. The string always has five lines.
    esimmuTimestamp:
      type: apiKey
      in: header
      name: X-Esimmu-Timestamp
      description: Unix seconds (UTC), within 5 minutes of our clock.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.