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

# Request refund

Refunds operation allows you to initiate a refund for asynchronous processing.

<Card title="Learn more!" icon="readme" href="/refunds" horizontal="true">
  See what the refund flow looks like with pawaPay.
</Card>

* This API call is <em>idempotent</em>, which means it is safe to submit a request with the same `refundId` multiple times.
* Duplicate requests with the same `refundId` will be ignored with the `DUPLICATE_IGNORED` status in the response.
* Since the request can be rejected, you must check the `status` code in the response for each submitted request. The `rejectionReason` in the response will contain information about the reason of the rejection.

Each request can get one of the statuses on initiation:

| Status              | <Tooltip tip="Will a callback be delivered after receiving this status on initiation?">Callback</Tooltip> | Description                                                                                                                         |
| ------------------- | --------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| `ACCEPTED`          | Yes                                                                                                       | The refund request has been **accepted** by pawaPay for processing.                                                                 |
| `REJECTED`          | No                                                                                                        | The refund request has been **rejected**. See `rejectionReason` for details.                                                        |
| `DUPLICATE_IGNORED` | No                                                                                                        | The refund request has been ignored as a duplicate of an already accepted refund request. Duplication logic relies upon `refundId`. |

### How to find out the final status of this refund?

As the pawaPay Merchant API is an [asynchronous API](/implementation#asynchronous-api), you can find out the final status of the `ACCEPTED` refund by either:

<CardGroup cols={2}>
  <Card title="Waiting for a callback" icon="webhook" href="/v1/api-reference/refunds/refund-callback" horizontal="true">
    If you have configured callbacks, just wait for it.
  </Card>

  <Card title="Checking the status" icon="code-compare" href="/v1/api-reference/refunds/check-refund-status" horizontal="true">
    Or poll the Check Refund Status endpoint.
  </Card>
</CardGroup>

<Info>Headers related to [signatures](/using_the_api#signatures) must only be included if you have enabled “Only accept signed requests”. Read more about it from the [pawaPay Dashboard documentation](/dashboard/other/system_conf/api_tokens#signed-requests).</Info>


## OpenAPI

````yaml openapi_v1 post /refunds
openapi: 3.0.0
info:
  title: pawaPay Merchant API v1
  description: Please find complete documentation from https://docs.pawapay.io/.
  version: v1
  x-logo:
    url: >-
      https://global-uploads.webflow.com/62824591015aa314fd308df1/6411b26596e3de3f52551c00_Logopawapay-p-500.png
    href: https://docs.pawapay.io/
    altText: pawaPay logo
servers:
  - url: https://api.sandbox.pawapay.io
    description: pawaPay Merchant API sandbox
  - url: https://api.pawapay.io
    description: pawaPay Merchant API production
security:
  - bearerAuth: []
tags:
  - name: payouts
    x-displayName: Payouts
  - name: deposits
    x-displayName: Deposits
  - name: refunds
    x-displayName: Refunds
  - name: payment-page
    x-displayName: Payment Page
  - name: toolkit
    x-displayName: Toolkit
  - name: wallet-balances
    x-displayName: Wallet balances
paths:
  /refunds:
    post:
      tags:
        - refunds
      summary: Request refund
      operationId: createRefund
      parameters:
        - in: header
          name: Content-Digest
          schema:
            type: string
            format: string
            description: SHA-256 or SHA-512 hash of the request body.
          required: false
        - in: header
          name: Signature
          schema:
            type: string
            format: string
            description: >-
              Signature of the request according to
              [RFC-9421](https://datatracker.ietf.org/doc/rfc9421/).
          required: false
        - in: header
          name: Signature-Input
          schema:
            type: string
            format: string
            description: >-
              Signature-Input according to
              [RFC-9421](https://datatracker.ietf.org/doc/rfc9421/).
          required: false
        - in: header
          name: Accept-Signature
          schema:
            type: string
            format: string
            description: >-
              Expected signature algorithm of the response according to
              [RFC-9421](https://datatracker.ietf.org/doc/rfc9421/).
          required: false
        - in: header
          name: Accept-Digest
          schema:
            type: string
            format: string
            description: >-
              Expected digest algorithm of the response according to
              [RFC-9421](https://datatracker.ietf.org/doc/rfc9421/).
          required: false
      requestBody:
        $ref: '#/components/requestBodies/RefundCreationRequest'
      responses:
        '200':
          description: Request has been accepted for processing by pawaPay
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RefundCreationResponse'
              examples:
                ACCEPTED:
                  value:
                    refundId: f4401bd2-1568-4140-bf2d-eb77d2b2b639
                    status: ACCEPTED
                    created: '2020-10-19T11:17:01Z'
                DUPLICATE_IGNORED:
                  value:
                    refundId: f4401bd2-1568-4140-bf2d-eb77d2b2b639
                    status: DUPLICATE_IGNORED
                    created: '2020-10-19T11:17:01Z'
                REJECTED:
                  value:
                    refundId: f4401bd2-1568-4140-bf2d-eb77d2b2b639
                    status: REJECTED
                    rejectionReason:
                      rejectionCode: AMOUNT_TOO_LARGE
                      rejectionMessage: Amount should not be greater than 1000
        '400':
          description: >-
            Request was rejected due to incompatibility with pawaPay API
            specification
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                Mandatory Field Missing:
                  value:
                    errorId: 4f0d5e13-7e88-4cc6-827c-8c0640dc2cd3
                    errorCode: 1
                    errorMessage: 'Invalid input: Missing required property ''amount'''
        '401':
          description: Authentication Failure. Please check your authentication token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                Authentication Failure:
                  value:
                    errorId: cad1529e-040b-4c9d-a21d-2ba3056ff750
                    errorCode: 2
                    errorMessage: Authentication error
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                System Error:
                  value:
                    errorId: d428a89e-fa8b-42b8-ba20-68be20d50af1
                    errorCode: 0
                    errorMessage: Internal error
components:
  requestBodies:
    RefundCreationRequest:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/RefundCreationRequest'
      required: true
  schemas:
    RefundCreationResponse:
      required:
        - refundId
        - status
      type: object
      properties:
        refundId:
          minLength: 36
          maxLength: 36
          type: string
          format: uuid
          description: The `refundId` of the refund transaction.
          example: f4401bd2-1568-4140-bf2d-eb77d2b2b639
        status:
          $ref: '#/components/schemas/RefundCreationStatus'
        created:
          type: string
          description: >-
            The timestamp of when the refund was created in the pawaPay
            platform. Format defined by 'date-time' in RFC3339 section 5.6 from
            [IETF](https://tools.ietf.org/html/rfc3339#section-5.6)
          format: date-time
          example: '2020-02-21T17:32:29Z'
        rejectionReason:
          $ref: '#/components/schemas/RefundRejectionReason'
    ErrorResponse:
      required:
        - errorId
        - errorCode
        - errorMessage
      type: object
      properties:
        errorId:
          maxLength: 36
          type: string
          description: A unique error ID in the pawaPay platform.
          example: 63743264-7292-11ea-bc55-0242ac130003
        errorCode:
          type: integer
          description: pawaPay internal error code.
          example: 1
        errorMessage:
          type: string
          description: Error message.
          example: Internal error
    RefundCreationRequest:
      required:
        - refundId
        - depositId
      type: object
      properties:
        refundId:
          minLength: 36
          maxLength: 36
          type: string
          format: uuid
          description: >-
            A UUIDv4 based ID specified by you, that uniquely identifies the
            refund.
          example: <INSERT_UUID_FOR_REFUND>
        depositId:
          minLength: 36
          maxLength: 36
          type: string
          format: uuid
          description: The `depositId` of the deposit to be refunded.
          example: <INSERT_UUID_OF_DEPOSIT_TO_REFUND>
        amount:
          $ref: '#/components/schemas/Amount'
        metadata:
          $ref: '#/components/schemas/TransactionMetadataRequest'
    RefundCreationStatus:
      type: string
      description: >
        Possible refund initiation statuses: 

        * `ACCEPTED` - The refund request has been **accepted** by pawaPay for
        processing. 

        * `REJECTED` - The refund request has been **rejected** by pawaPay. See
        `rejectionReason` for details. 

        * `DUPLICATE_IGNORED` - The refund request has been **ignored** as a
        duplicate of an already accepted refund request. Duplication logic
        relies upon refundId.
      enum:
        - ACCEPTED
        - REJECTED
        - DUPLICATE_IGNORED
    RefundRejectionReason:
      required:
        - rejectionReason
      type: object
      properties:
        rejectionCode:
          type: string
          description: >
            Possible refund rejection codes:  

            * `DEPOSIT_NOT_FOUND`- Requested deposit for refund has not been
            found.  

            * `DEPOSIT_NOT_COMPLETED`- Requested deposit was not completed.  

            * `ALREADY_REFUNDED`- Requested deposit has been already refunded.  

            * `IN_PROGRESS`- Another refund transaction is already in
            progress.  

            * `INVALID_AMOUNT`- The specified amount is not supported. 

            * `AMOUNT_TOO_SMALL` - The specified amount is smaller than the
            minimum allowed by the MMO specified as the correspondent. 

            * `AMOUNT_TOO_LARGE` - The specified amount is larger than the
            maximum allowed by the MMO specified as the correspondent. 

            * `INVALID_CURRENCY` - The specified currency is not supported by
            the MMO specified as the correspondent. 

            * `INVALID_COUNTRY` - The specified country is not supported for the
            MMO specified as the correspondent. 

            * `PARAMETER_INVALID` - One or more parameters are invalid. 

            * `INVALID_INPUT` - We were unable to parse the payload of the
            request. 

            * `REFUNDS_NOT_ALLOWED` - Refunds are not allowed for this merchant
            or the MMO specified as the correspondent.

            * `CORRESPONDENT_TEMPORARILY_UNAVAILABLE` - The MMO specified as the
            correspondent is currently experiencing an outage and processing of
            payments has been temporarily halted. Please refer to our [Status
            Page](https://status.pawapay.io) for live information about MMO
            availability.
          example: INVALID_AMOUNT
          enum:
            - DEPOSIT_NOT_FOUND
            - DEPOSIT_NOT_COMPLETED
            - ALREADY_REFUNDED
            - IN_PROGRESS
            - INVALID_AMOUNT
            - AMOUNT_TOO_SMALL
            - AMOUNT_TOO_LARGE
            - PARAMETER_INVALID
            - INVALID_INPUT
            - REFUNDS_NOT_ALLOWED
            - CORRESPONDENT_TEMPORARILY_UNAVAILABLE
        rejectionMessage:
          type: string
          description: Additional optional rejection message
          example: You don't have access to this correspondent (MMO)
    Amount:
      minLength: 1
      maxLength: 23
      type: string
      pattern: ^([0]|([1-9][0-9]{0,17}))([.][0-9]{0,3}[1-9])?$
      description: >
        The amount to be collected (deposit) or disbursed (payout or refund). 


        Amount must follow below requirements or the request will be
        **rejected**:

        * Between zero and two decimal places can be supplied, depending on what
        the specific MMO supports. Learn about all [MMO supported decimal
        places](/using_the_api#correspondents).

        * The minimum and maximum amount depends on the limits of the specific
        MMO. You can find them from the [Active
        Configuration](/v1/api-reference/toolkit/active-configuration) endpoint.

        * Leading zeroes are not permitted except where the value is less than
        1. For any value less than one, one and only one leading zero must be
        supplied.

        * Trailing zeroes are permitted.


        Valid examples:

        `5`, `5.0`, `5.00`, `5.5`, `5.55`, `5555555`, `0.5`


        Not valid examples:

        `5.`, `5.555`, `5555555555555555555`, `.5`, `-5.5`, `00.5`, `00.00`,
        `00001.32`
      example: '15'
    TransactionMetadataRequest:
      description: >
        A list of metadata that you can attach to the payment for providing
        additional context about the payment.

        For example, adding `orderId` to indicate for which order this payment
        was for or `customerId` to know which customer this payment pertains to.


        Metadata will not be visible to the customer that is party to this
        payment. 

        It will be visible in the pawaPay Dashboard on the payment details page
        and in your financial statements as a JSON object to support automated
        reconciliation.

        It is also possible to search for recent payments in the pawaPay
        Dashboard using global search based on the values of metadata.


        Up to 10 metadata fields can be attached to a payment. 
      type: array
      items:
        $ref: '#/components/schemas/TransactionMetadataRequestItem'
      example:
        - fieldName: orderId
          fieldValue: ORD-123456789
        - fieldName: customerId
          fieldValue: customer@email.com
          isPII: true
    TransactionMetadataRequestItem:
      required:
        - fieldName
        - fieldValue
      type: object
      properties:
        fieldName:
          type: string
          description: >-
            The name of the metadata that you are attaching to the payment. For
            example `orderId`.
          example: orderId
        fieldValue:
          type: string
          description: The value for this metadata field. For example `ORD-123456789`.
          example: ORD-123456789
        isPII:
          type: boolean
          default: false
          description: >-
            Indicates whether the field contains personally identifiable
            information. Used for enabling compliance with GDPR or other
            relevant data privacy laws.
          example: true
  securitySchemes:
    bearerAuth:
      type: http
      description: See [Authentication](/using_the_api#authentication).
      scheme: bearer
      bearerFormat: JWT

````