# /paymentmethods/bancontact/v1/transactions/{transactionId}/refunds

# OpenAPI definition

```json
{
  "openapi": "3.0.3",
  "info": {
    "title": "Payments Gateway",
    "description": "Common payments API",
    "version": "1.23.0"
  },
  "security": [
    {
      "oAuth2ClientCredentials": []
    }
  ],
  "servers": [
    {
      "url": "/api/v1/"
    }
  ],
  "paths": {
    "/paymentmethods/bancontact/v1/transactions/{transactionId}/refunds": {
      "post": {
        "tags": [
          "bancontact"
        ],
        "operationId": "createBanContactPaymentRefund",
        "parameters": [
          {
            "name": "transactionId",
            "in": "path",
            "required": true,
            "schema": {
              "$ref": "#/components/schemas/Uuid"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/Refund"
              }
            }
          }
        },
        "responses": {
          "201": {
            "$ref": "#/components/responses/BanContactTransaction"
          },
          "4XX": {
            "$ref": "#/components/responses/UserError"
          },
          "5XX": {
            "$ref": "#/components/responses/InternalError"
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "ReturnUrl": {
        "oneOf": [
          {
            "required": [
              "returnUrls"
            ],
            "type": "object",
            "properties": {
              "returnUrls": {
                "type": "object",
                "required": [
                  "success",
                  "cancelled",
                  "expired",
                  "failed"
                ],
                "properties": {
                  "success": {
                    "type": "string",
                    "format": "url",
                    "maxLength": 2000,
                    "example": "https://yourdomain.tld/order/payment-success.html"
                  },
                  "cancelled": {
                    "type": "string",
                    "format": "url",
                    "maxLength": 2000,
                    "example": "https://yourdomain.tld/order/payment-cancelled.html"
                  },
                  "expired": {
                    "type": "string",
                    "format": "url",
                    "maxLength": 2000,
                    "example": "https://yourdomain.tld/order/payment-expired.html"
                  },
                  "failed": {
                    "type": "string",
                    "format": "url",
                    "maxLength": 2000,
                    "example": "https://yourdomain.tld/order/payment-failed.html"
                  }
                }
              }
            }
          },
          {
            "required": [
              "returnUrl"
            ],
            "type": "object",
            "properties": {
              "returnUrl": {
                "type": "string",
                "format": "url",
                "maxLength": 2000,
                "example": "https://yourdomain.tld/order/return?orderID=order123"
              }
            }
          }
        ]
      },
      "Uuid": {
        "description": "Unique identifier",
        "type": "string",
        "format": "uuid",
        "minLength": 36,
        "maxLength": 36,
        "example": "8db1e7fa-ba8a-4189-92fd-67a20217443d"
      },
      "Reference": {
        "description": "Identifier from client. This value will be sent in the webhook payload alongside the ID you receive as part of the response of a transaction.",
        "type": "string",
        "minLength": 1,
        "maxLength": 255,
        "example": 20210623130413,
        "default": ""
      },
      "Datetime": {
        "description": "ISO 8601 date and time",
        "type": "string",
        "format": "date-time",
        "minLength": 20,
        "example": "2006-01-02T15:04:05Z"
      },
      "Amount": {
        "description": "Denomination in the smallest currency subunit, as for example eurocents.",
        "type": "integer",
        "minimum": 1,
        "maximum": 99999999,
        "example": 1200
      },
      "Currency": {
        "description": "ISO 4217 currency code",
        "type": "string",
        "minLength": 3,
        "maxLength": 3,
        "default": "EUR",
        "example": "EUR"
      },
      "Language": {
        "description": "Preferred language of the user interface",
        "type": "string",
        "example": "nl"
      },
      "Country": {
        "description": "Country of the consumer (ISO-3166)",
        "type": "string",
        "example": "NL",
        "minLength": 2,
        "maxLength": 2
      },
      "Refunds": {
        "description": "Details of refunds for a transaction",
        "type": "object",
        "required": [
          "refundedAmount",
          "refundedPendingAmount"
        ],
        "properties": {
          "refundedAmount": {
            "description": "Amount in the smallest currency subunit, as for example eurocents, that has already been refunded.",
            "type": "integer",
            "minimum": 0,
            "maximum": 99999999,
            "example": 300
          },
          "refundedPendingAmount": {
            "description": "Amount in the smallest currency subunit, as for example eurocents, that has been requested to be refunded.",
            "type": "integer",
            "minimum": 1,
            "maximum": 99999999,
            "example": 100
          }
        }
      },
      "TransactionRefundsWebhooks": {
        "description": "Webhooks enable receiving a web request once a given event occurs. \nWe won't do preventive rate-limiting in order to have the highest throughput possible. \nHowever, we will honor 429 (Too-many-requests) responses per callback. \nWe use the Retry-After header to retry after a certain period. If the header was not set we use our default exponential delay implementation.\n",
        "type": "array",
        "items": {
          "type": "object",
          "required": [
            "url",
            "events"
          ],
          "properties": {
            "url": {
              "description": "The URL the request must be send to.",
              "type": "string",
              "format": "url",
              "example": "https://yourdomain.tld/webhooks?purchaseId=order123"
            },
            "events": {
              "description": "The events when this URL must be requested.",
              "type": "array",
              "minItems": 1,
              "items": {
                "$ref": "#/components/schemas/TransactionRefundsWebhookEvent"
              }
            }
          }
        },
        "example": [
          {
            "url": "https://yourdomain.tld/order-webhooks?purchaseId=order123",
            "events": [
              "FINALSTATUS"
            ]
          },
          {
            "url": "https://yourdomain.tld/payment-webhooks?purchaseId=order123",
            "events": [
              "REFUND_STATUS"
            ]
          },
          {
            "url": "https://yourdomain.tld/payment-webhooks?purchaseId=order123",
            "events": [
              "STATUS_CHANGE"
            ]
          }
        ]
      },
      "TransactionRefundsWebhookEvent": {
        "description": "* `FINALSTATUS` - When the status of the transaction becomes final; it is no longer `OPEN`.\n* `STATUS_CHANGE` - When the status of the transaction changes to another value.\n* `REFUND_STATUS` - When a transaction receives an update on its requested refunds.\n",
        "type": "string",
        "enum": [
          "FINALSTATUS",
          "STATUS_CHANGE",
          "REFUND_STATUS"
        ],
        "example": "FINALSTATUS"
      },
      "Digest": {
        "description": "Digest of whole message body",
        "type": "string",
        "example": "sha-256=OWM5MDc3ODYwNzdjYjE5NjU0Y2NjMDM4MzEyYzMxZTA5MTAzMDBjYWM1Y2I1ODM4NTdlMDU2MzhiMzE1ZDhjNw==",
        "externalDocs": {
          "description": "Instance Digests in HTTP",
          "url": "https://datatracker.ietf.org/doc/html/rfc3230"
        }
      },
      "Refund": {
        "description": "Refund an already successfully processed payment.",
        "type": "object",
        "properties": {
          "amount": {
            "allOf": [
              {
                "$ref": "#/components/schemas/Amount"
              },
              {
                "description": "Denomination in the smallest currency subunit, as for example eurocents.\nIf empty, the refund amount will be the remaining available amount of the transaction\n(i.e., total payment amount minus already refunded amounts minus the amounts of the pending refund requests).\n"
              }
            ]
          },
          "reason": {
            "description": "The description for the refund.\n",
            "type": "string",
            "example": "Refund required by customer.",
            "maxLength": 255
          }
        }
      },
      "TransactionStatus": {
        "description": "* `OPEN`       - Payment has been created. This is the initial status.\n* `SUCCESS`    - Payment has succeeded.\n* `CANCELLED`  - Payment has not succeeded; cancelled by the consumer.\n* `EXPIRED`    - Payment has not succeeded; expired.\n* `FAILURE`    - Payment has not succeeded; unknown reason.\n* `AUTHORIZED` - Payment is authorized.\n* `PENDING`    - Payment could not be completed yet; waiting for something.\n* `CHARGEBACK` - Payment chargeback was created.\n",
        "type": "string",
        "enum": [
          "OPEN",
          "SUCCESS",
          "CANCELLED",
          "EXPIRED",
          "FAILURE",
          "AUTHORIZED",
          "PENDING",
          "CHARGEBACK"
        ],
        "example": "OPEN"
      }
    },
    "responses": {
      "BanContactTransaction": {
        "description": "BanContact transaction details",
        "headers": {
          "Digest": {
            "$ref": "#/components/headers/Digest"
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "allOf": [
                {
                  "type": "object",
                  "required": [
                    "id",
                    "orderId",
                    "reference",
                    "amount",
                    "currency",
                    "description",
                    "expiresAt",
                    "language",
                    "country",
                    "status",
                    "createdAt",
                    "action"
                  ],
                  "properties": {
                    "id": {
                      "$ref": "#/components/schemas/Uuid"
                    },
                    "orderId": {
                      "$ref": "#/components/schemas/Uuid"
                    },
                    "reference": {
                      "$ref": "#/components/schemas/Reference"
                    },
                    "amount": {
                      "$ref": "#/components/schemas/Amount"
                    },
                    "currency": {
                      "$ref": "#/components/schemas/Currency"
                    },
                    "description": {
                      "type": "string",
                      "example": "Order at yourdomain.tld"
                    },
                    "expiresAt": {
                      "$ref": "#/components/schemas/Datetime"
                    },
                    "language": {
                      "$ref": "#/components/schemas/Language"
                    },
                    "country": {
                      "allOf": [
                        {
                          "$ref": "#/components/schemas/Country"
                        },
                        {
                          "example": "BE"
                        }
                      ]
                    },
                    "webhooks": {
                      "$ref": "#/components/schemas/TransactionRefundsWebhooks"
                    },
                    "status": {
                      "$ref": "#/components/schemas/TransactionStatus"
                    },
                    "action": {
                      "description": "Next action to be performed by merchant (or consumer) to complete the payment.",
                      "type": "object",
                      "nullable": true,
                      "properties": {
                        "qrcode": {
                          "type": "object",
                          "nullable": true,
                          "properties": {
                            "url": {
                              "description": "URL to QR code image to be scanned by consumer to perform the payment. Unavailable when a payment using the card details was started.",
                              "type": "string",
                              "format": "url",
                              "example": "https://qrbackend.tld/images/213981209381209390821.png"
                            }
                          }
                        },
                        "intent": {
                          "type": "object",
                          "nullable": true,
                          "properties": {
                            "url": {
                              "description": "URL to the Intent URL which can be opened by the BanContact application on mobile devices. Unavailable when a payment using the card details was started.",
                              "type": "string",
                              "format": "url",
                              "example": "https://docdata.tld/pay?order=123"
                            }
                          }
                        },
                        "redirect": {
                          "type": "object",
                          "nullable": true,
                          "properties": {
                            "url": {
                              "description": "URL where consumer should be redirected to by the merchant to perform the payment. This url is only available when a card payment has been started",
                              "type": "string",
                              "format": "url",
                              "example": "https://checkout.tld/3ds/bancontact/v1/123"
                            }
                          }
                        }
                      }
                    },
                    "createdAt": {
                      "$ref": "#/components/schemas/Datetime"
                    },
                    "refunds": {
                      "$ref": "#/components/schemas/Refunds"
                    }
                  }
                },
                {
                  "$ref": "#/components/schemas/ReturnUrl"
                }
              ]
            }
          }
        }
      },
      "InternalError": {
        "description": "Internal server error. This can be caused by an unresponsive backend",
        "content": {
          "application/json": {
            "schema": {
              "type": "object",
              "required": [
                "id",
                "message"
              ],
              "properties": {
                "id": {
                  "$ref": "#/components/schemas/Uuid"
                },
                "message": {
                  "type": "string",
                  "example": "Service Unavailable"
                }
              }
            }
          }
        }
      },
      "UserError": {
        "description": "The user input was incorrect or something illegal was attempted (eg. using a service without having that service configured for the user, or not being authorized)",
        "content": {
          "application/json": {
            "schema": {
              "type": "object",
              "required": [
                "id",
                "message"
              ],
              "properties": {
                "id": {
                  "$ref": "#/components/schemas/Uuid"
                },
                "message": {
                  "type": "string",
                  "example": "no authorization methods provided"
                }
              }
            }
          }
        }
      }
    },
    "headers": {
      "Digest": {
        "description": "Digest of whole message body",
        "schema": {
          "$ref": "#/components/schemas/Digest"
        }
      }
    },
    "securitySchemes": {
      "oAuth2ClientCredentials": {
        "type": "oauth2",
        "flows": {
          "clientCredentials": {
            "tokenUrl": "/api/v1/authorization/oauth2/token",
            "scopes": {}
          }
        }
      }
    }
  },
  "x-readme": {
    "explorer-enabled": true,
    "proxy-enabled": true
  },
  "_id": {
    "buffer": {
      "0": 103,
      "1": 234,
      "2": 76,
      "3": 191,
      "4": 145,
      "5": 198,
      "6": 48,
      "7": 79,
      "8": 46,
      "9": 249,
      "10": 185,
      "11": 249
    }
  }
}
```