--- title: "Initiate refund" method: POST path: "/v2/refunds" tags: ["refunds"] --- # Initiate refund `POST /v2/refunds` ## Headers - `Content-Digest` string, string — SHA-256 or SHA-512 hash of the request body. - `Signature` string, string — Signature of the request according to [RFC-9421](https://datatracker.ietf.org/doc/rfc9421/). - `Signature-Input` string, string — Signature input according to [RFC-9421](https://datatracker.ietf.org/doc/rfc9421/). - `Accept-Signature` string, string — Expected signature algorithm of the response according to [RFC-9421](https://datatracker.ietf.org/doc/rfc9421/). - `Accept-Digest` string, string — Expected digest algorithm of the response according to [RFC-9421](https://datatracker.ietf.org/doc/rfc9421/). ## Request body - RefundInitiationRequest - `refundId` string, uuid, required — A UUIDv4 based unique ID for this payment. We require you to provide the unique ID for all initiated payments to ensure you can always reconcile all payments. Please store this ID in your system before initiating the payment with PawaPay. - `depositId` string, uuid, required — The `depositId` of the deposit to be refunded. - `clientReferenceId` string — A reference to an entity in your system that this payment relates to. For example, an invoice ID, customer ID etc. - `amount` string, required — The amount of the payment. Amount must follow below requirements or the request will be **rejected**: * Not all providers support decimals. Find which ones do from [providers](/v2/docs/providers) or dynamically using [active configuration](/v2/api-reference/toolkit/active-configuration) endpoint. * Transaction limits apply. Find them from the [Active Configuration](/v2/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. - `currency` string, required — The currency in which the `amount` is specified. Format must be the ISO 4217 three character currency code in upper case. Read more from [Wikipedia](https://en.wikipedia.org/wiki/ISO_4217#Active_codes). Find the supported currencies for the [provider](/v2/docs/providers). The [active configuration](/v2/api-reference/toolkit/active-configuration) endpoint has all the providers configured for your account together with the supported currencies. - `metadata` TransactionMetadataRequestItem[] — A list of metadata that you can attach to the payment for providing additional context about the payment. For example, adding the channel from which the payment was initated, product ID or anything else that might help your operations team. Metadata will be included in: - In the dashboard on payment details pages - Financial statements as JSON object - Callbacks Metadata can be used when searching in the PawaPay Dashboard. Full value of the metadata field must be used for searches. Metadata will not be visible to the customer that is involved in this payment. Up to 10 metadata fields can be attached to a payment. - `additionalProperties` string — The metadata that you are attaching to the payment. For example `"orderId":"ORD-123456789"`. - `isPII` boolean — Indicates whether the field contains personally identifiable information. Used for compliance with GDPR or other relevant data privacy laws. ## Response `200` Request has been accepted for processing by PawaPay - RefundCreationResponse - `refundId` string, uuid, required — The unique ID for this payment in PawaPay as specified by you during initiation. - `status` 'ACCEPTED' | 'REJECTED' | 'DUPLICATE_IGNORED', required — Possible refund initiation statuses: * `ACCEPTED` - The refund has been **accepted** by PawaPay for processing. * `REJECTED` - The refund has been **rejected** by PawaPay. See `failureReason` for details. * `DUPLICATE_IGNORED` - The refund has been **ignored** as a duplicate of an already accepted refund. Duplication logic relies upon `refundId`. - `created` string, date-time — The timestamp of when the payment 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) - `failureReason` RefundInitiationFailureReason - `failureCode` 'NO_AUTHENTICATION' | 'AUTHENTICATION_ERROR' | 'AUTHORISATION_ERROR' | 'HTTP_SIGNATURE_ERROR' | 'INVALID_INPUT' | 'MISSING_PARAMETER' | 'UNSUPPORTED_PARAMETER' | 'INVALID_PARAMETER' | 'DUPLICATE_METADATA_FIELD' | 'REFUNDS_NOT_ALLOWED' | 'INVALID_PHONE_NUMBER' | 'INVALID_AMOUNT' | 'AMOUNT_OUT_OF_BOUNDS' | 'PAWAPAY_WALLET_OUT_OF_FUNDS' | 'INVALID_CURRENCY' | 'INVALID_PROVIDER' | 'NOT_FOUND' | 'INVALID_STATE' | 'UNKNOWN_ERROR' — Reason for the failure: * `NO_AUTHENTICATION` - The API token was not found in the request headers. * `AUTHENTICATION_ERROR` - The API token in the request headers is not valid. * `AUTHORISATION_ERROR` - The API Token in the request header is not authorised to make this request. * `HTTP_SIGNATURE_ERROR` - The signature you have passed with the request did not pass verification. * `INVALID_INPUT` - We were unable to parse the payload of the request. * `MISSING_PARAMETER` - A mandatory parameter was missing from the request body. * `UNSUPPORTED_PARAMETER` - An unsupported parameter was found in the request body. * `INVALID_PARAMETER` - A parameter had an incorrect value. * `DUPLICATE_METADATA_FIELD` - A duplicate field was found in payment metadata. * `REFUNDS_NOT_ALLOWED` - Refunds are not enabled with the provider on your PawaPay account. * `INVALID_PHONE_NUMBER` - The phone number provided is in the wrong format. * `INVALID_AMOUNT` - The amount contains decimals which is not supported by the provider. * `INVALID_CURRENCY` - The currency is not supported by the provider. * `INVALID_PROVIDER` - The provider is not valid for this request. * `PROVIDER_TEMPORARILY_UNAVAILABLE` - The provider is not currently not able to accept payments. * `NOT_FOUND` - The deposit to refund was not found. * `INVALID_STATE` - The deposit to refund is not in 'COMPLETED' status or has already been refunded. * `UNKNOWN_ERROR` - The provider is not valid for this request. - `failureMessage` string — A description of the failure ## Other responses - `400` — Request was rejected due to incompatibility with PawaPay API specification - `401` — Authentication failed. Make sure you have added the API token into the header. If using signatures, make sure they are valid. - `403` — Authorization failure. Please check your authentication token. - `500` — An unknown failure has occurred. --- [API](https://skmtc.net/pawapay/apis/pawapay-merchant-api-v2.md) · [All operations](https://skmtc.net/pawapay/apis/pawapay-merchant-api-v2/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/pawapay/pawapay-merchant-api-v2/versions/ce13c31e9746/schema)