---
updatedAt: 2026-06-04T16:54:59.000Z
agentTools:
projectIndex: https://doc.fintecture.com/llms.txt
---
# Create a refund
This endpoint gives merchants the possibility to initiate a refund.
A refund can either be full or partial. By default it will be done to the original payment account but one can specify a payout account if needed.
💡 Note
Some examples can be viewed using the example dropdown
# OpenAPI definition
```json
{
"openapi": "3.0.3",
"info": {
"title": "API EXPLORER",
"version": "3.0.0",
"description": "Public API\n",
"contact": {
"name": "Support",
"email": "noelia.rodriguez@fintecture.com"
}
},
"x-readme": {
"explorer-enabled": false,
"proxy-enabled": false,
"samples-languages": [
"curl",
"javascript",
"ruby"
]
},
"servers": [
{
"url": "https://api.sandbox.fintecture.com",
"description": "Sandbox server"
},
{
"url": "https://api.fintecture.com",
"description": "Production server"
}
],
"paths": {
"/pis/v2/refund": {
"post": {
"security": [
{
"OAuth2Pis": [
"pis"
]
}
],
"requestBody": {
"$ref": "#/components/requestBodies/PisV2RefundRequest"
},
"tags": [
"payments"
],
"parameters": [
{
"$ref": "#/components/parameters/Header-digest-req"
}
],
"responses": {
"201": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PisV2Refund"
}
}
},
"description": "successful operation"
},
"400": {
"$ref": "#/components/responses/400-BadRequest"
},
"401": {
"$ref": "#/components/responses/401-Unauthorized"
},
"403": {
"$ref": "#/components/responses/403-Forbidden"
},
"500": {
"$ref": "#/components/responses/500-InternalServerError"
}
},
"operationId": "createPisV2Refund",
"summary": "Create a refund",
"description": "This endpoint gives merchants the possibility to initiate a refund.
\nA refund can either be full or partial. By default it will be done to the original payment account but one can specify a payout account if needed.
\n💡 Note
Some examples can be viewed using the example dropdown
\n"
},
"parameters": [
{
"$ref": "#/components/parameters/Header-signature-req"
},
{
"$ref": "#/components/parameters/Header-date-req"
},
{
"$ref": "#/components/parameters/Header-xRequestId-req"
}
]
}
},
"components": {
"parameters": {
"Header-date-req": {
"name": "date",
"description": "RFC2822 formatted date.",
"schema": {
"$ref": "#/components/schemas/DateRfc2822"
},
"in": "header",
"required": true
},
"Header-signature-req": {
"name": "signature",
"description": "Signature is used to enforce security by signing request.
Related documentation can be found by clicking [here](https://doc.fintecture.com/docs/api-http-signature)",
"schema": {
"type": "string"
},
"in": "header",
"required": true
},
"Header-digest-req": {
"name": "digest",
"description": "Sha-256 base64 encoded digest.
Related documentation can be found by clicking [here](https://doc.fintecture.com/docs/api-http-signature)",
"schema": {
"type": "string"
},
"in": "header",
"required": true
},
"Header-xRequestId-req": {
"name": "x-request-id",
"description": "uuid v4. Required in Redirect mode.",
"schema": {
"$ref": "#/components/schemas/IdentifierUuidV4"
},
"in": "header",
"required": true
}
},
"requestBodies": {
"PisV2RefundRequest": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PisV2RefundRequest"
},
"examples": {
"Full Refund Request": {
"value": {
"meta": {
"session_id": "ecec9f13407f4c2cb5f1591255e8f815"
}
}
},
"Partial Refund Request": {
"value": {
"meta": {
"session_id": "ecec9f13407f4c2cb5f1591255e8f815"
},
"data": {
"attributes": {
"amount": "149.30"
}
}
}
},
"Refund with Payout account": {
"value": {
"meta": {
"session_id": "ecec9f13407f4c2cb5f1591255e8f815"
},
"data": {
"attributes": {
"debtor": {
"bank_account_id": "dc5b0048-2a80-4a22-b2f9-fad7d72f074d"
}
}
}
}
}
}
}
},
"required": true
}
},
"responses": {
"400-BadRequest": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/APIResponse400"
}
}
},
"description": "bad request"
},
"401-Unauthorized": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/APIResponse401"
}
}
},
"description": "unauthorized"
},
"403-Forbidden": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/APIResponse403"
}
}
},
"description": "forbidden"
},
"500-InternalServerError": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/APIResponse500"
}
}
},
"description": "internal server error"
}
},
"schemas": {
"Address": {
"title": "Address",
"description": "Description of an address",
"type": "object",
"required": [
"street",
"city",
"zip",
"country"
],
"properties": {
"street": {
"description": "the street name",
"maxLength": 255,
"minLength": 1,
"type": "string",
"example": "rue Marie Stuart"
},
"number": {
"description": "the street number",
"maxLength": 20,
"minLength": 0,
"type": "string",
"example": "2"
},
"complement": {
"description": "extra information regarding address",
"maxLength": 255,
"minLength": 1,
"type": "string",
"example": "A"
},
"city": {
"description": "the city",
"maxLength": 255,
"minLength": 1,
"type": "string",
"example": "PARIS"
},
"zip": {
"description": "the zip code",
"maxLength": 255,
"minLength": 1,
"type": "string",
"example": "75002"
},
"country": {
"$ref": "#/components/schemas/CountryCode"
}
}
},
"Amount": {
"title": "Amount",
"description": "Description of an amount @Fintecture",
"type": "string",
"pattern": "^[0-9]+(\\.[0-9]{1,2})?$",
"example": "273.00"
},
"APIResponse400": {
"title": "400 API Response",
"description": "Definition of the standard API reponse when a 400",
"type": "object",
"properties": {
"status": {
"format": "int32",
"description": "HTTP status code",
"type": "integer",
"example": 400
},
"code": {
"type": "string",
"enum": [
"bad_request",
"provider_error"
],
"example": "bad_request"
},
"log_id": {
"allOf": [
{
"$ref": "#/components/schemas/IdentifierUuidV4"
},
{
"description": "Log unique identifier"
}
]
},
"errors": {
"description": "Errors returned",
"type": "array",
"items": {
"$ref": "#/components/schemas/APIResponse400Error"
}
}
}
},
"APIResponse400Error": {
"title": "API Response 400 Error",
"description": "API Response 400 Error description",
"type": "object",
"properties": {
"code": {
"type": "string",
"enum": [
"bad_request",
"customer_unknown",
"account_unknown",
"session_id_invalid_or_expired",
"invalid_field",
"mandatory_field_missing",
"invalid_debited_account"
],
"example": "bad_request"
},
"title": {
"description": "Title message",
"type": "string",
"example": "Bad request"
},
"message": {
"description": "Error message",
"type": "string",
"example": "Invalid parameters or malformed syntax."
}
}
},
"APIResponse401": {
"title": "401 API Response",
"description": "Definition of the standard API reponse when a 401",
"type": "object",
"properties": {
"status": {
"format": "int32",
"description": "HTTP status code",
"type": "integer",
"example": 401
},
"code": {
"type": "string",
"enum": [
"unauthorized"
],
"example": "unauthorized"
},
"log_id": {
"allOf": [
{
"$ref": "#/components/schemas/IdentifierUuidV4"
},
{
"description": "Log unique identifier"
}
]
},
"errors": {
"description": "Errors returned",
"type": "array",
"items": {
"$ref": "#/components/schemas/APIResponse401Error"
}
}
}
},
"APIResponse401Error": {
"title": "API Response 401 Error",
"description": "API Response 401 Error description",
"type": "object",
"properties": {
"code": {
"type": "string",
"enum": [
"invalid_token",
"invalid_scopes",
"invalid_code",
"invalid_app_id",
"invalid_app_url"
],
"example": "bad_request"
},
"title": {
"description": "Title message",
"type": "string",
"example": "Invalid token"
},
"message": {
"description": "Error message",
"type": "string",
"example": "The token is either invalid or expired."
}
}
},
"APIResponse403": {
"title": "403 API Response",
"description": "Definition of the standard API reponse when a 403",
"type": "object",
"properties": {
"status": {
"format": "int32",
"description": "HTTP status code",
"type": "integer",
"example": 403
},
"code": {
"type": "string",
"enum": [
"forbidden"
],
"example": "forbidden"
},
"log_id": {
"allOf": [
{
"$ref": "#/components/schemas/IdentifierUuidV4"
},
{
"description": "Log unique identifier"
}
]
},
"errors": {
"description": "Errors returned",
"type": "array",
"items": {
"$ref": "#/components/schemas/APIResponse403Error"
}
}
}
},
"APIResponse403Error": {
"title": "API Response 403 Error",
"description": "API Response 403 Error description",
"type": "object",
"properties": {
"code": {
"type": "string",
"enum": [
"forbidden"
],
"example": "forbidden"
},
"title": {
"description": "Title message",
"type": "string",
"example": "Forbidden"
},
"message": {
"description": "Error message",
"type": "string",
"example": "Access Forbidden."
}
}
},
"APIResponse500": {
"title": "500 API Response",
"description": "Definition of the standard API reponse when a 500",
"type": "object",
"properties": {
"status": {
"format": "int32",
"description": "HTTP status code",
"type": "integer",
"example": 500
},
"code": {
"type": "string",
"enum": [
"internal_server_error"
],
"example": "internal_server_error"
},
"log_id": {
"allOf": [
{
"$ref": "#/components/schemas/IdentifierUuidV4"
},
{
"description": "Log unique identifier"
}
]
},
"errors": {
"description": "Errors returned",
"type": "array",
"items": {
"$ref": "#/components/schemas/APIResponse500Error"
}
}
}
},
"APIResponse500Error": {
"title": "API Response 500 Error",
"description": "API Response 500 Error description",
"type": "object",
"properties": {
"code": {
"type": "string",
"enum": [
"internal_server_error"
],
"example": "internal_server_error"
},
"title": {
"description": "Title message",
"type": "string",
"example": "Internal Server Error"
},
"message": {
"description": "Error message",
"type": "string",
"example": "An internal error has occurred. If the error persists, please contact our support."
}
}
},
"BankIban": {
"title": "Bank IBAN",
"description": "IBAN of bank",
"type": "string",
"example": "FR1420041010050500013M02606",
"pattern": "^AL\\d{10}[0-9A-Z]{16}$|^AD\\d{10}[0-9A-Z]{12}$|^AT\\d{18}$|^BH\\d{2}[A-Z]{4}[0-9A-Z]{14}$|^BE\\d{14}$|^BA\\d{18}$|^BG\\d{2}[A-Z]{4}\\d{6}[0-9A-Z]{8}$|^HR\\d{19}$|^CY\\d{10}[0-9A-Z]{16}$|^CZ\\d{22}$|^DK\\d{16}$|^FO\\d{16}$|^GL\\d{16}$|^DO\\d{2}[0-9A-Z]{4}\\d{20}$|^EE\\d{18}$|^FI\\d{16}$|^FR\\d{12}[0-9A-Z]{11}\\d{2}$|^GE\\d{2}[A-Z]{2}\\d{16}$|^DE\\d{20}$|^GI\\d{2}[A-Z]{4}[0-9A-Z]{15}$|^GR\\d{9}[0-9A-Z]{16}$|^HU\\d{26}$|^IS\\d{24}$|^IE\\d{2}[A-Z]{4}\\d{14}$|^IL\\d{21}$|^IT\\d{2}[A-Z]\\d{10}[0-9A-Z]{12}$|^[A-Z]{2}\\d{5}[0-9A-Z]{13}$|^KW\\d{2}[A-Z]{4}22!$|^LV\\d{2}[A-Z]{4}[0-9A-Z]{13}$|^LB\\d{6}[0-9A-Z]{20}$|^LI\\d{7}[0-9A-Z]{12}$|^LT\\d{18}$|^LU\\d{5}[0-9A-Z]{13}$|^MK\\d{5}[0-9A-Z]{10}\\d{2}$|^MT\\d{2}[A-Z]{4}\\d{5}[0-9A-Z]{18}$|^MR13\\d{23}$|^MU\\d{2}[A-Z]{4}\\d{19}[A-Z]{3}$|^MC\\d{12}[0-9A-Z]{11}\\d{2}$|^ME\\d{20}$|^NL\\d{2}[A-Z]{4}\\d{10}$|^NO\\d{13}$|^PL\\d{10}[0-9A-Z]{,16}n$|^PT\\d{23}$|^RO\\d{2}[A-Z]{4}[0-9A-Z]{16}$|^SM\\d{2}[A-Z]\\d{10}[0-9A-Z]{12}$|^SA\\d{4}[0-9A-Z]{18}$|^RS\\d{20}$|^SK\\d{22}$|^SI\\d{17}$|^ES\\d{22}$|^SE\\d{22}$|^CH\\d{7}[0-9A-Z]{12}$|^TN59\\d{20}$|^TR\\d{7}[0-9A-Z]{17}$|^AE\\d{21}$|^GB\\d{2}[A-Z]{4}\\d{14}$"
},
"BankRib": {
"title": "Bank account identification",
"description": "Account identification of a bank",
"type": "object",
"required": [
"iban",
"swift_bic"
],
"properties": {
"iban": {
"$ref": "#/components/schemas/BankIban"
},
"swift_bic": {
"$ref": "#/components/schemas/BankSwiftBic"
},
"bank_name": {
"description": "Name of the bank",
"type": "string",
"readOnly": true,
"example": "myBank"
},
"type": {
"description": "Type of account",
"enum": [
"internal_acquiring"
],
"example": "internal_acquiring",
"readOnly": true
},
"is_isct_supported": {
"description": "Indicates if Instant Sepa Credit Transfer is allowed",
"readOnly": true,
"example": true
}
}
},
"BankSwiftBic": {
"title": "Bank Switt BIC",
"description": "swift/bic associated to the bank",
"type": "string",
"maxLength": 50,
"pattern": "^[A-Z]{6,6}[A-Z2-9][A-NP-Z0-9]([A-Z0-9]{3,3}){0,1}$",
"example": "BANKFRXXXXX"
},
"Beneficiary": {
"title": "Beneficiary",
"description": "Description of a beneficiary",
"type": "object",
"oneOf": [
{
"$ref": "#/components/schemas/BeneficiaryCompany"
}
]
},
"BeneficiaryCompany": {
"title": "Beneficiary (Legal Person)",
"description": "Beneficiary specific information when a company",
"type": "object",
"allOf": [
{
"type": "object",
"required": [
"name",
"form",
"incorporation"
],
"properties": {
"id": {
"allOf": [
{
"$ref": "#/components/schemas/IdentifierUuidV4"
},
{
"readOnly": true
}
]
},
"name": {
"description": "the name of the beneficiary",
"type": "string",
"example": "Fintecture"
},
"form": {
"description": "The incorporation form (ex: SARL)",
"type": "string",
"example": "SAS"
},
"incorporation": {
"description": "The incorporation number",
"type": "string",
"example": "Incorporation"
}
}
},
{
"$ref": "#/components/schemas/Address"
},
{
"$ref": "#/components/schemas/BankRib"
}
]
},
"CountryCode": {
"title": "Country code",
"description": "country code like described in the ISO 3166-1 alpha-2 ",
"maxLength": 2,
"minLength": 2,
"type": "string",
"example": "FR"
},
"CurrencyCode": {
"title": "Currency",
"description": "Currency like described in ISO 4217",
"maxLength": 3,
"minLength": 3,
"pattern": "^[A-Z]{3,3}$",
"type": "string",
"example": "EUR"
},
"Date": {
"title": "Date",
"description": "Simple date",
"format": "date",
"type": "string",
"pattern": "^([12]\\d{3}-(0[1-9]|1[0-2])-(0[1-9]|[12]\\d|3[01]))$",
"example": "2022-08-02T00:00:00.000Z"
},
"DateRfc2822": {
"title": "Date in rfc 2822 format",
"description": "Date as described in rfc 2822 format",
"type": "string",
"example": "Thu, 18 Jun 2020 18:14:15 GMT"
},
"IdentifierEndToEnd": {
"title": "End to End identifier",
"description": "The End to End ID used in payment, also useful for idempotency check. By default, session_id will be used",
"maxLength": 255,
"minLength": 1,
"pattern": "^[a-zA-Z0-9]{1,35}$",
"type": "string",
"example": "123456789"
},
"SessionId": {
"title": "Unique session_id identifier",
"description": "Unique session_id identifier",
"type": "string",
"minLength": 32,
"maxLength": 32,
"pattern": "^[0-9a-f]{32}$",
"example": "ecec9f13407f4c2cb5f1591255e8f815"
},
"IdentifierUuidV4": {
"title": "UUID V4 identifier",
"description": "UUID V4 identifier",
"pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$",
"type": "string",
"example": "dc5b0048-2a80-4a22-b2f9-fad7d72f074d"
},
"PaymentCommunication": {
"title": "Payment Communication",
"description": "Additional information to be provided during payment.\n\n**Currency-specific limit**: when the payment currency or the beneficiary\ncurrency is `SEK`, the underlying domestic rail caps this field at\n**12 characters**. Requests exceeding that length are rejected with\n`406 invalid_field`.\n",
"type": "string",
"pattern": "^[-a-zA-Z0-9 éèêëçâùûôî.,;:/!?$%_=+()*°@#ÂÇÉÈÊËÎÔÙÛ]{0,140}$",
"minLength": 1,
"maxLength": 140,
"example": "B34970692"
},
"PaymentRejectedReason": {
"title": "Payment Rejected Reason (Enum)",
"description": "The below table shows the different payment transfer rejected reasons. The list is not exhaustive",
"enum": [
"insufficient_funds",
"incorrect_account_number",
"closed_account",
"blocked_account",
"transaction_forbidden",
"too_many_transactions",
"invalid_execution_date",
"customer",
"cancelled",
"fraudulent_originated",
"no_answer",
"regulatory_reason"
],
"type": "string",
"example": "no_answer"
},
"PaymentTransferState": {
"title": "Payment Transfer State (Enum)",
"description": "While a immediate payment initiate should return `payment_created` or `payment_unsuccessful`, there are some exceptional cases when banks can't confirm immediately the payment status and will result to a `payment_pending` status. (this field might sometimes not be returned)",
"enum": [
"accepted",
"authorized",
"completed",
"insufficient",
"overpaid",
"pending",
"processing",
"received",
"rejected",
"sent",
"returned"
],
"type": "string",
"example": "completed"
},
"PisV2PaymentSessionDataAttributes": {
"title": "Payment Data Attributes",
"description": "Payment Data Attributes",
"type": "object",
"properties": {
"amount": {
"$ref": "#/components/schemas/Amount"
},
"currency": {
"$ref": "#/components/schemas/CurrencyCode"
},
"execution_date": {
"$ref": "#/components/schemas/Date"
},
"beneficiary": {
"$ref": "#/components/schemas/Beneficiary"
},
"communication": {
"$ref": "#/components/schemas/PaymentCommunication"
},
"end_to_end_id": {
"$ref": "#/components/schemas/IdentifierEndToEnd"
},
"transfer_state": {
"allOf": [
{
"$ref": "#/components/schemas/PaymentTransferState"
}
]
},
"transfer_reason": {
"$ref": "#/components/schemas/PaymentRejectedReason"
},
"scheme": {
"type": "string",
"example": "SEPA"
}
}
},
"PisV2Refund": {
"title": "PIS Refund",
"description": "PIS Refund",
"type": "object",
"required": [
"meta"
],
"properties": {
"meta": {
"type": "object",
"required": [
"status",
"code",
"message",
"session_id"
],
"properties": {
"status": {
"$ref": "#/components/schemas/RefundStatus"
},
"code": {
"type": "integer",
"description": "HTTP status code of the refund request",
"example": 201
},
"message": {
"type": "string",
"example": "Refund initiated successfully."
},
"session_id": {
"$ref": "#/components/schemas/SessionId"
},
"refunded_session_id": {
"allOf": [
{
"$ref": "#/components/schemas/SessionId"
},
{
"description": "Payment session id of the original payment to which this refund relates. This is a different session from the refund `session_id`."
},
{
"example": "251a92937b8c4d5e9f0a1b2c3d4e5f6a"
}
]
}
}
},
"data": {
"type": "object",
"properties": {
"id": {
"allOf": [
{
"$ref": "#/components/schemas/SessionId"
},
{
"example": "e784ee59a1b24c3d8e5f6a7b8c9d0e1f"
}
]
},
"type": {
"type": "string",
"enum": [
"payments"
],
"example": "payments"
},
"attributes": {
"$ref": "#/components/schemas/PisV2PaymentSessionDataAttributes"
}
}
}
}
},
"PisV2RefundRequest": {
"title": "PIS Refund Request",
"description": "PIS Refund request",
"type": "object",
"required": [
"meta"
],
"properties": {
"meta": {
"required": [
"session_id"
],
"type": "object",
"properties": {
"session_id": {
"$ref": "#/components/schemas/SessionId"
}
}
},
"data": {
"required": [
"attributes"
],
"type": "object",
"properties": {
"attributes": {
"type": "object",
"properties": {
"amount": {
"allOf": [
{
"description": "The amount in case of partial refund. By default, the full amount of the original payment is used."
},
{
"$ref": "#/components/schemas/Amount"
}
]
},
"communication": {
"allOf": [
{
"description": "The communication to use for the refund payment. By default it will append \"REFUND\" to the original communication."
},
{
"$ref": "#/components/schemas/PaymentCommunication"
}
]
},
"debtor": {
"required": [
"bank_account_id"
],
"type": "object",
"description": "Object containing the attributes related to the debtor account to be used if different from the original payment beneficiary account",
"properties": {
"bank_account_id": {
"$ref": "#/components/schemas/IdentifierUuidV4"
}
}
}
}
}
}
}
}
},
"RefundStatus": {
"title": "Refund status (Enum)",
"enum": [
"refund_initiated",
"refund_accepted",
"refund_pending",
"refund_created",
"refund_waiting",
"refund_partial",
"auto_refund_waiting"
],
"type": "string",
"example": "refund_accepted"
}
},
"securitySchemes": {
"OAuth2Pis": {
"type": "oauth2",
"description": "OAuth2 flow server to server purposes (client credentials)",
"x-default": "",
"flows": {
"clientCredentials": {
"tokenUrl": "https://api.fintecture.com/oauth/accesstoken",
"scopes": {
"pis": "Grants access to payment initiation services",
"payout": "Grants access to payout services",
"customers": "Grants access to customers",
"documents": "Grants access to documents",
"e-mandates": "Grants access to e-mandates"
}
}
}
}
}
},
"tags": [
{
"name": "payments",
"description": "Payment related endpoints",
"x-displayName": "Payment"
}
]
}
```