# /paymentmethods/checkout/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/checkout/v1/transactions/{transactionId}/refunds": {
      "post": {
        "tags": [
          "checkout"
        ],
        "operationId": "createCheckoutTransactionRefund",
        "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/CheckoutTransactionWithPayments"
          },
          "4XX": {
            "$ref": "#/components/responses/UserError"
          },
          "5XX": {
            "$ref": "#/components/responses/InternalError"
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Gender": {
        "type": "string",
        "format": "enum",
        "enum": [
          "m",
          "f",
          null
        ],
        "nullable": true,
        "default": null
      },
      "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"
      },
      "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
          }
        }
      },
      "MaxRetries": {
        "description": "Maximum number of retries allowed to pay the order",
        "type": "integer",
        "minimum": 0,
        "maximum": 255,
        "example": 10
      },
      "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"
      },
      "CheckoutPayment": {
        "type": "object",
        "required": [
          "id",
          "type",
          "status",
          "createdAt"
        ],
        "properties": {
          "id": {
            "$ref": "#/components/schemas/Uuid"
          },
          "type": {
            "description": "* `bancontact`\n* `creditcard`\n* `ideal`\n* `paypal`\n* `giropay`\n",
            "type": "string",
            "enum": [
              "bancontact",
              "creditcard",
              "ideal",
              "paypal",
              "giropay"
            ]
          },
          "status": {
            "$ref": "#/components/schemas/TransactionStatus"
          },
          "createdAt": {
            "$ref": "#/components/schemas/Datetime"
          }
        }
      },
      "CheckoutConsumer": {
        "description": "Customer details",
        "type": "object",
        "properties": {
          "givenName": {
            "type": "string",
            "minLength": 1,
            "maxLength": 35,
            "example": "John"
          },
          "middleName": {
            "type": "string",
            "minLength": 1,
            "maxLength": 35,
            "example": "",
            "default": ""
          },
          "familyName": {
            "type": "string",
            "minLength": 1,
            "maxLength": 35,
            "example": "Doe"
          },
          "email": {
            "type": "string",
            "format": "email",
            "example": "john.doe@email.tld"
          },
          "gender": {
            "$ref": "#/components/schemas/Gender"
          },
          "address": {
            "$ref": "#/components/schemas/CheckoutAddress"
          },
          "phone": {
            "type": "string",
            "example": "06-95613259"
          },
          "dateOfBirth": {
            "type": "string",
            "example": "1996-12-01"
          }
        }
      },
      "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
          }
        }
      },
      "CheckoutAddress": {
        "type": "object",
        "properties": {
          "street": {
            "type": "string",
            "maxLength": 100,
            "example": "Rustenburgerlaan"
          },
          "houseNumber": {
            "type": "string",
            "maxLength": 35,
            "example": "25"
          },
          "postalCode": {
            "type": "string",
            "maxLength": 35,
            "example": "2012AL"
          },
          "city": {
            "type": "string",
            "maxLength": 35,
            "example": "Haarlem"
          },
          "countryCode": {
            "type": "string",
            "format": "ISO 3166-1 alfa-2",
            "example": "NL"
          },
          "state": {
            "type": "string",
            "maxLength": 40,
            "example": "Noord-Holland"
          },
          "additionalData": {
            "type": "string",
            "maxLength": 35,
            "example": "Right-hand portal"
          }
        }
      },
      "Items": {
        "description": "Items included in the order. Required field for the following payment methods: Klarna.\nWe request both values 'vatAmount' and 'vatRate' to prevent errors.\n",
        "type": "array",
        "minItems": 1,
        "maxItems": 512,
        "items": {
          "type": "object",
          "required": [
            "code",
            "unitPrice",
            "quantity",
            "vatAmount",
            "vatRate"
          ],
          "properties": {
            "code": {
              "description": "A code that identifies the item. Each item code must be unique per transaction.",
              "type": "string",
              "minLength": 1,
              "maxLength": 50,
              "example": "SDC4/32GB-2ADP"
            },
            "name": {
              "description": "A human readable name for the item.",
              "type": "string",
              "minLength": 1,
              "maxLength": 50,
              "example": "Kingston microSD 32GB"
            },
            "description": {
              "description": "Additional item description.",
              "type": "string",
              "minLength": 1,
              "maxLength": 100,
              "example": "Best seller SD card"
            },
            "unitPrice": {
              "description": "Unit price (including VAT) of the item, specified in the smallest currency subunit, as for example eurocents.",
              "type": "integer",
              "minimum": 1,
              "maximum": 99999999,
              "example": 600
            },
            "quantity": {
              "description": "The number of items of this type.",
              "type": "integer",
              "minimum": 1,
              "maximum": 1000000000,
              "example": 2
            },
            "vatAmount": {
              "description": "VAT amount of one unit, specified in the smallest currency subunit, as for example eurocents.",
              "type": "integer",
              "minimum": 1,
              "maximum": 99999999,
              "example": 100
            },
            "vatRate": {
              "description": "Percentage of VAT applied.\nOnly the first decimal value will be taken into account, the rest will be ignored.\n",
              "type": "number",
              "minimum": 0,
              "maximum": 99.9,
              "example": 20,
              "multipleOf": 0.1
            }
          }
        }
      },
      "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": {
      "CheckoutTransactionWithPayments": {
        "description": "Checkout transaction details",
        "headers": {
          "Digest": {
            "$ref": "#/components/headers/Digest"
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "allOf": [
                {
                  "type": "object",
                  "required": [
                    "id",
                    "reference",
                    "amount",
                    "currency",
                    "merchantOrderReference",
                    "description",
                    "expiresAt",
                    "status",
                    "action",
                    "createdAt"
                  ],
                  "properties": {
                    "id": {
                      "$ref": "#/components/schemas/Uuid"
                    },
                    "reference": {
                      "$ref": "#/components/schemas/Reference"
                    },
                    "amount": {
                      "$ref": "#/components/schemas/Amount"
                    },
                    "currency": {
                      "$ref": "#/components/schemas/Currency"
                    },
                    "consumer": {
                      "$ref": "#/components/schemas/CheckoutConsumer"
                    },
                    "merchantOrderReference": {
                      "type": "string",
                      "example": "order123"
                    },
                    "description": {
                      "description": "Description of the order or reason of the payment. Is shown to the consumer.",
                      "type": "string",
                      "example": "Order at yourdomain.tld"
                    },
                    "paymentMethods": {
                      "description": "The merchant can set the payment methods for each checkout session, when the paymentMethods attribute is not given, the merchants default payment methods will be used.",
                      "type": "array",
                      "default": [],
                      "example": [
                        "ideal",
                        "bancontact",
                        "klarna"
                      ],
                      "items": {
                        "type": "string",
                        "enum": [
                          "bancontact",
                          "creditcard",
                          "ideal",
                          "maestro",
                          "belfius",
                          "wechat",
                          "alipay",
                          "pointofsale",
                          "paypal"
                        ]
                      }
                    },
                    "orderItems": {
                      "$ref": "#/components/schemas/Items"
                    },
                    "expiresAt": {
                      "$ref": "#/components/schemas/Datetime"
                    },
                    "language": {
                      "$ref": "#/components/schemas/Language"
                    },
                    "webhooks": {
                      "$ref": "#/components/schemas/TransactionRefundsWebhooks"
                    },
                    "maxRetries": {
                      "$ref": "#/components/schemas/MaxRetries"
                    },
                    "payments": {
                      "type": "array",
                      "items": {
                        "allOf": [
                          {
                            "$ref": "#/components/schemas/CheckoutPayment"
                          }
                        ]
                      }
                    },
                    "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": {
                        "redirect": {
                          "type": "object",
                          "properties": {
                            "url": {
                              "description": "URL where consumer should be redirected to by the merchant to perform the payment.",
                              "type": "string",
                              "format": "url",
                              "example": "https://checkout.cmpayments.com/?hostedCheckoutId=0863a7aadb99bf1c6ae770936db45eb33e61c917"
                            }
                          }
                        }
                      }
                    },
                    "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
    }
  }
}
```