publicapi_spec.json

{
  "openapi" : "3.0.1",
  "info" : {
    "description" : "The GOV.UK Pay REST API. Read [our documentation](https://docs.payments.service.gov.uk/) for more details.",
    "title" : "GOV.UK Pay API",
    "version" : "1.0.3"
  },
  "servers" : [ {
    "url" : "https://publicapi.payments.service.gov.uk"
  } ],
  "tags" : [ {
    "name" : "Agreements"
  }, {
    "name" : "Card payments"
  }, {
    "name" : "Refunding card payments"
  } ],
  "paths" : {
    "/v1/agreements" : {
      "get" : {
        "description" : "You can use this endpoint to search for recurring payments agreements. The agreements are sorted by date, with the most recently-created agreements appearing first.",
        "operationId" : "Search agreements",
        "parameters" : [ {
          "description" : "Returns agreements with a `reference` that exactly matches the value you sent. This parameter is not case sensitive. A `reference` was associated with the agreement when that agreement was created.",
          "example" : "CT-22-23-0001",
          "in" : "query",
          "name" : "reference",
          "schema" : {
            "type" : "string"
          }
        }, {
          "description" : "Returns agreements in a matching `status`. `status` reflects where an agreement is in its lifecycle. You can [read more about the meanings of the different agreement status values](https://docs.payments.service.gov.uk/recurring_payments/#understanding-agreement-status).",
          "in" : "query",
          "name" : "status",
          "schema" : {
            "type" : "string",
            "enum" : [ "created", "active", "cancelled", "inactive" ]
          }
        }, {
          "description" : "Returns a specific page of results. Defaults to `1`. You can [read about search pagination](https://docs.payments.service.gov.uk/api_reference/#pagination)",
          "example" : 1,
          "in" : "query",
          "name" : "page",
          "schema" : {
            "type" : "string"
          }
        }, {
          "description" : "The number of agreements returned per results page. Defaults to `500`. Maximum value is `500`. You can [read about search pagination](https://docs.payments.service.gov.uk/api_reference/#pagination)",
          "example" : 50,
          "in" : "query",
          "name" : "display_size",
          "schema" : {
            "type" : "string"
          }
        } ],
        "responses" : {
          "200" : {
            "content" : {
              "application/json" : {
                "schema" : {
                  "$ref" : "#/components/schemas/AgreementSearchResults"
                }
              }
            },
            "description" : "OK - your request was successful."
          },
          "401" : {
            "description" : "Your API key is missing or invalid. Read more about [authenticating GOV.UK Pay API requests](https://docs.payments.service.gov.uk/api_reference/#authentication)"
          },
          "404" : {
            "content" : {
              "application/json" : {
                "schema" : {
                  "$ref" : "#/components/schemas/RequestError"
                }
              }
            },
            "description" : "Not found"
          },
          "422" : {
            "content" : {
              "application/json" : {
                "schema" : {
                  "$ref" : "#/components/schemas/RequestError"
                }
              }
            },
            "description" : "Your request failed. Check the `code` and `description` in the response to find out why your request failed."
          },
          "429" : {
            "content" : {
              "application/json" : {
                "schema" : {
                  "$ref" : "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description" : "Too many requests"
          },
          "500" : {
            "content" : {
              "application/json" : {
                "schema" : {
                  "$ref" : "#/components/schemas/RequestError"
                }
              }
            },
            "description" : "Downstream system error"
          }
        },
        "security" : [ {
          "BearerAuth" : [ ]
        } ],
        "summary" : "Search agreements for recurring payments",
        "tags" : [ "Agreements" ]
      },
      "post" : {
        "description" : "You can use this endpoint to create a new agreement.",
        "operationId" : "Create an agreement",
        "requestBody" : {
          "content" : {
            "application/json" : {
              "schema" : {
                "$ref" : "#/components/schemas/CreateAgreementRequest"
              }
            }
          },
          "description" : "requestPayload",
          "required" : true
        },
        "responses" : {
          "201" : {
            "content" : {
              "application/json" : {
                "schema" : {
                  "$ref" : "#/components/schemas/Agreement"
                }
              }
            },
            "description" : "Created"
          },
          "400" : {
            "content" : {
              "application/json" : {
                "schema" : {
                  "$ref" : "#/components/schemas/RequestError"
                }
              }
            },
            "description" : "Bad request"
          },
          "401" : {
            "description" : "Your API key is missing or invalid. Read more about [authenticating GOV.UK Pay API requests](https://docs.payments.service.gov.uk/api_reference/#authentication)"
          },
          "422" : {
            "content" : {
              "application/json" : {
                "schema" : {
                  "$ref" : "#/components/schemas/RequestError"
                }
              }
            },
            "description" : "Your request failed. Check the `code` and `description` in the response to find out why your request failed."
          },
          "429" : {
            "content" : {
              "application/json" : {
                "schema" : {
                  "$ref" : "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description" : "Too many requests"
          },
          "500" : {
            "content" : {
              "application/json" : {
                "schema" : {
                  "$ref" : "#/components/schemas/RequestError"
                }
              }
            },
            "description" : "Downstream system error"
          }
        },
        "security" : [ {
          "BearerAuth" : [ ]
        } ],
        "summary" : "Create an agreement for recurring payments",
        "tags" : [ "Agreements" ]
      }
    },
    "/v1/agreements/{agreementId}" : {
      "get" : {
        "description" : "You can use this endpoint to get information about a single recurring payments agreement.",
        "operationId" : "Get an agreement",
        "parameters" : [ {
          "description" : "Returns the agreement with the matching `agreement_id`. GOV.UK Pay generated an `agreement_id` when you created the agreement.",
          "example" : "cgc1ocvh0pt9fqs0ma67r42l58",
          "in" : "path",
          "name" : "agreementId",
          "required" : true,
          "schema" : {
            "type" : "string"
          }
        } ],
        "responses" : {
          "200" : {
            "content" : {
              "application/json" : {
                "schema" : {
                  "$ref" : "#/components/schemas/Agreement"
                }
              }
            },
            "description" : "OK - your request was successful."
          },
          "401" : {
            "description" : "Your API key is missing or invalid. Read more about [authenticating GOV.UK Pay API requests](https://docs.payments.service.gov.uk/api_reference/#authentication)"
          },
          "404" : {
            "content" : {
              "application/json" : {
                "schema" : {
                  "$ref" : "#/components/schemas/RequestError"
                }
              }
            },
            "description" : "Not found"
          },
          "429" : {
            "content" : {
              "application/json" : {
                "schema" : {
                  "$ref" : "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description" : "Too many requests"
          },
          "500" : {
            "content" : {
              "application/json" : {
                "schema" : {
                  "$ref" : "#/components/schemas/RequestError"
                }
              }
            },
            "description" : "Downstream system error"
          }
        },
        "security" : [ {
          "BearerAuth" : [ ]
        } ],
        "summary" : "Get information about a single agreement for recurring payments",
        "tags" : [ "Agreements" ]
      }
    },
    "/v1/agreements/{agreementId}/cancel" : {
      "post" : {
        "description" : "You can use this endpoint to cancel a recurring payments agreement in the `active` status.",
        "operationId" : "Cancel an agreement",
        "parameters" : [ {
          "description" : "The `agreement_id` of the agreement you are cancelling",
          "example" : "cgc1ocvh0pt9fqs0ma67r42l58",
          "in" : "path",
          "name" : "agreementId",
          "required" : true,
          "schema" : {
            "type" : "string"
          }
        } ],
        "responses" : {
          "204" : {
            "description" : "No Content"
          },
          "400" : {
            "content" : {
              "application/json" : {
                "schema" : {
                  "$ref" : "#/components/schemas/RequestError"
                }
              }
            },
            "description" : "Cancellation of agreement failed"
          },
          "401" : {
            "description" : "Your API key is missing or invalid. Read more about [authenticating GOV.UK Pay API requests](https://docs.payments.service.gov.uk/api_reference/#authentication)"
          },
          "404" : {
            "content" : {
              "application/json" : {
                "schema" : {
                  "$ref" : "#/components/schemas/RequestError"
                }
              }
            },
            "description" : "Not found"
          },
          "429" : {
            "content" : {
              "application/json" : {
                "schema" : {
                  "$ref" : "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description" : "Too many requests"
          },
          "500" : {
            "content" : {
              "application/json" : {
                "schema" : {
                  "$ref" : "#/components/schemas/RequestError"
                }
              }
            },
            "description" : "Downstream system error"
          }
        },
        "security" : [ {
          "BearerAuth" : [ ]
        } ],
        "summary" : "Cancel an agreement for recurring payments",
        "tags" : [ "Agreements" ]
      }
    },
    "/v1/auth" : {
      "post" : {
        "description" : "You can use this endpoint to [authorise payments](https://docs.payments.service.gov.uk/moto_payments/moto_send_card_details_api/) you have created with `authorisation_mode` set to `moto_api`.",
        "operationId" : "Authorise a MOTO payment",
        "requestBody" : {
          "content" : {
            "application/json" : {
              "schema" : {
                "$ref" : "#/components/schemas/AuthorisationRequest"
              }
            }
          },
          "required" : true
        },
        "responses" : {
          "204" : {
            "description" : "Your authorisation request was successful."
          },
          "400" : {
            "content" : {
              "application/json" : {
                "schema" : {
                  "$ref" : "#/components/schemas/RequestError"
                }
              }
            },
            "description" : "Your request is invalid. Check the `code` and `description` in the response to find out why your request failed."
          },
          "402" : {
            "content" : {
              "application/json" : {
                "schema" : {
                  "$ref" : "#/components/schemas/RequestError"
                }
              }
            },
            "description" : "The `card_number` you sent is not a valid card number or you chose not to accept this card type. Check the `code` and `description` fields in the response to find out why your request failed."
          },
          "422" : {
            "content" : {
              "application/json" : {
                "schema" : {
                  "$ref" : "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description" : "A value you sent is invalid or missing. Check the `code` and `description` in the response to find out why your request failed."
          },
          "500" : {
            "content" : {
              "application/json" : {
                "schema" : {
                  "$ref" : "#/components/schemas/RequestError"
                }
              }
            },
            "description" : "There is something wrong with GOV.UK Pay. If there are no issues on our status page (https://payments.statuspage.io), you can contact us with your error code and we'll investigate."
          }
        },
        "summary" : "Send card details to authorise a MOTO payment",
        "tags" : [ "Authorise card payments" ]
      }
    },
    "/v1/disputes" : {
      "get" : {
        "description" : "You can use this endpoint to search disputes. A dispute is when [a paying user challenges a completed payment through their bank](https://docs.payments.service.gov.uk/disputes/).",
        "operationId" : "Search disputes",
        "parameters" : [ {
          "description" : "Returns disputes raised on or after the `from_date`. Date and time must be coordinated Universal Time (UTC) and ISO 8601 format to second-level accuracy - `YYYY-MM-DDThh:mm:ssZ`.",
          "example" : "2015-08-13T12:35:00Z",
          "in" : "query",
          "name" : "from_date",
          "schema" : {
            "type" : "string"
          }
        }, {
          "description" : "Returns disputes raised before the `to_date`. Date and time must be coordinated Universal Time (UTC) and ISO 8601 format to second-level accuracy - `YYYY-MM-DDThh:mm:ssZ`.",
          "example" : "2015-08-13T12:35:00Z",
          "in" : "query",
          "name" : "to_date",
          "schema" : {
            "type" : "string"
          }
        }, {
          "description" : "Returns disputes settled on or after the `from_settled_date`. Date must be in ISO 8601 format to date-level accuracy - `YYYY-MM-DD`. Disputes are settled when your payment service provider takes the disputed amount from a payout to your bank account.",
          "in" : "query",
          "name" : "from_settled_date",
          "schema" : {
            "type" : "string"
          }
        }, {
          "description" : "Returns disputes settled before the `to_settled_date`. Date must be in ISO 8601 format to date-level accuracy - `YYYY-MM-DD`. Disputes are settled when your payment service provider takes the disputed amount from a payout to your bank account.",
          "in" : "query",
          "name" : "to_settled_date",
          "schema" : {
            "type" : "string"
          }
        }, {
          "description" : "Returns disputes with a matching `status`. `status` reflects what stage of the dispute process a dispute is at. You can [read more about the meanings of the different status values](https://docs.payments.service.gov.uk/disputes/#dispute-status)",
          "example" : "won",
          "in" : "query",
          "name" : "status",
          "schema" : {
            "type" : "string",
            "enum" : [ "needs_response", "under_review", "lost", "won" ]
          }
        }, {
          "description" : "Returns a specific page of results. Defaults to `1`.",
          "in" : "query",
          "name" : "page",
          "schema" : {
            "type" : "string"
          }
        }, {
          "description" : "The number of disputes returned per results page. Defaults to `500`. Maximum value is `500`.",
          "in" : "query",
          "name" : "display_size",
          "schema" : {
            "type" : "string"
          }
        } ],
        "responses" : {
          "200" : {
            "content" : {
              "application/json" : {
                "schema" : {
                  "$ref" : "#/components/schemas/DisputesSearchResults"
                }
              }
            },
            "description" : "OK - your request was successful."
          },
          "401" : {
            "description" : "Your API key is missing or invalid. Read more about [authenticating GOV.UK Pay API requests](https://docs.payments.service.gov.uk/api_reference/#authentication)"
          },
          "422" : {
            "content" : {
              "application/json" : {
                "schema" : {
                  "$ref" : "#/components/schemas/RequestError"
                }
              }
            },
            "description" : "Invalid parameters: from_date, to_date, from_settled_date, to_settled_date, status, display_size. See Public API documentation for the correct data formats"
          },
          "429" : {
            "content" : {
              "application/json" : {
                "schema" : {
                  "$ref" : "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description" : "Too many requests"
          },
          "500" : {
            "content" : {
              "application/json" : {
                "schema" : {
                  "$ref" : "#/components/schemas/RequestError"
                }
              }
            },
            "description" : "Downstream system error"
          }
        },
        "security" : [ {
          "BearerAuth" : [ ]
        } ],
        "summary" : "Search disputes",
        "tags" : [ "Disputes" ]
      }
    },
    "/v1/payments" : {
      "get" : {
        "description" : "You can use this endpoint to [search for payments you’ve previously created](https://docs.payments.service.gov.uk/reporting/#search-payments/). Payments are sorted by date, with the most recently-created payment appearing first.",
        "operationId" : "Search payments",
        "parameters" : [ {
          "description" : "Returns payments with `reference` values exactly matching your specified value.",
          "in" : "query",
          "name" : "reference",
          "schema" : {
            "type" : "string"
          }
        }, {
          "description" : "Returns payments with matching `email` values. You can send full or partial email addresses. `email` is the paying user’s email address.",
          "in" : "query",
          "name" : "email",
          "schema" : {
            "type" : "string"
          }
        }, {
          "description" : "Returns payments in a matching `state`. `state` reflects where a payment is in the [payment status lifecycle](https://docs.payments.service.gov.uk/api_reference/#payment-status-lifecycle).",
          "example" : "success",
          "in" : "query",
          "name" : "state",
          "schema" : {
            "type" : "string",
            "enum" : [ "created", "started", "submitted", "success", "failed", "cancelled", "error" ]
          }
        }, {
          "description" : "Returns payments paid with a particular card brand.",
          "in" : "query",
          "name" : "card_brand",
          "schema" : {
            "type" : "string"
          }
        }, {
          "description" : "Returns payments created on or after the `from_date`. Date and time must be coordinated Universal Time (UTC) and ISO 8601 format to second-level accuracy - `YYYY-MM-DDThh:mm:ssZ`.",
          "example" : "2015-08-13T12:35:00Z",
          "in" : "query",
          "name" : "from_date",
          "schema" : {
            "type" : "string"
          }
        }, {
          "description" : "Returns payments created before the `to_date`. Date and time must be coordinated Universal Time (UTC) and ISO 8601 format to second-level accuracy - `YYYY-MM-DDThh:mm:ssZ`.",
          "example" : "2015-08-13T12:35:00Z",
          "in" : "query",
          "name" : "to_date",
          "schema" : {
            "type" : "string"
          }
        }, {
          "description" : "Returns a [specific page of results](https://docs.payments.service.gov.uk/api_reference/#pagination). Defaults to `1`.",
          "in" : "query",
          "name" : "page",
          "schema" : {
            "type" : "string"
          }
        }, {
          "description" : "The number of payments returned [per results page](https://docs.payments.service.gov.uk/api_reference/#pagination). Defaults to `500`. Maximum value is `500`.",
          "in" : "query",
          "name" : "display_size",
          "schema" : {
            "type" : "string"
          }
        }, {
          "description" : "Returns payments paid with cards under this cardholder name.",
          "in" : "query",
          "name" : "cardholder_name",
          "schema" : {
            "type" : "string"
          }
        }, {
          "description" : "Returns payments paid by cards beginning with the `first_digits_card_number` value. `first_digits_card_number` value must be 6 digits.",
          "in" : "query",
          "name" : "first_digits_card_number",
          "schema" : {
            "type" : "string"
          }
        }, {
          "description" : "Returns payments paid by cards ending with the `last_digits_card_number` value. `last_digits_card_number` value must be 4 digits.",
          "in" : "query",
          "name" : "last_digits_card_number",
          "schema" : {
            "type" : "string"
          }
        }, {
          "description" : "Returns payments settled on or after the `from_settled_date` value. You can only search by settled date if your payment service provider is Stripe. Date must be in ISO 8601 format to date-level accuracy - `YYYY-MM-DD`. Payments are settled when your payment service provider sends funds to your bank account.",
          "in" : "query",
          "name" : "from_settled_date",
          "schema" : {
            "type" : "string"
          }
        }, {
          "description" : "Returns payments settled before the `to_settled_date` value. You can only search by settled date if your payment service provider is Stripe. Date must be in ISO 8601 format to date-level accuracy - `YYYY-MM-DD`. Payments are settled when your payment service provider sends funds to your bank account.",
          "in" : "query",
          "name" : "to_settled_date",
          "schema" : {
            "type" : "string"
          }
        }, {
          "description" : "Returns payments that were authorised using the agreement with this `agreement_id`. Must be an exact match.",
          "example" : "abcefghjklmnopqr1234567890",
          "in" : "query",
          "name" : "agreement_id",
          "schema" : {
            "type" : "string"
          }
        } ],
        "responses" : {
          "200" : {
            "content" : {
              "application/json" : {
                "schema" : {
                  "$ref" : "#/components/schemas/PaymentSearchResults"
                }
              }
            },
            "description" : "OK - your request was successful."
          },
          "401" : {
            "description" : "Your API key is missing or invalid. Read more about [authenticating GOV.UK Pay API requests](https://docs.payments.service.gov.uk/api_reference/#authentication)"
          },
          "422" : {
            "content" : {
              "application/json" : {
                "schema" : {
                  "$ref" : "#/components/schemas/RequestError"
                }
              }
            },
            "description" : "Invalid parameters: from_date, to_date, status, display_size. See Public API documentation for the correct data formats"
          },
          "429" : {
            "content" : {
              "application/json" : {
                "schema" : {
                  "$ref" : "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description" : "Too many requests"
          },
          "500" : {
            "content" : {
              "application/json" : {
                "schema" : {
                  "$ref" : "#/components/schemas/RequestError"
                }
              }
            },
            "description" : "Downstream system error"
          }
        },
        "security" : [ {
          "BearerAuth" : [ ]
        } ],
        "summary" : "Search payments",
        "tags" : [ "Card payments" ]
      },
      "post" : {
        "description" : "You can use this endpoint to [create a new payment](https://docs.payments.service.gov.uk/making_payments/).",
        "operationId" : "Create a payment",
        "parameters" : [ {
          "in" : "header",
          "name" : "Idempotency-Key",
          "schema" : {
            "type" : "string",
            "pattern" : "^$|^[a-zA-Z0-9-]+$"
          }
        } ],
        "requestBody" : {
          "content" : {
            "application/json" : {
              "schema" : {
                "$ref" : "#/components/schemas/CreateCardPaymentRequest"
              }
            }
          },
          "description" : "requestPayload",
          "required" : true
        },
        "responses" : {
          "201" : {
            "content" : {
              "application/json" : {
                "schema" : {
                  "$ref" : "#/components/schemas/CreatePaymentResult"
                }
              }
            },
            "description" : "Created"
          },
          "400" : {
            "content" : {
              "application/json" : {
                "schema" : {
                  "$ref" : "#/components/schemas/RequestError"
                }
              }
            },
            "description" : "Bad request"
          },
          "401" : {
            "description" : "Your API key is missing or invalid. Read more about [authenticating GOV.UK Pay API requests](https://docs.payments.service.gov.uk/api_reference/#authentication)"
          },
          "422" : {
            "content" : {
              "application/json" : {
                "schema" : {
                  "$ref" : "#/components/schemas/RequestError"
                }
              }
            },
            "description" : "Your request failed. Check the `code` and `description` in the response to find out why your request failed."
          },
          "429" : {
            "content" : {
              "application/json" : {
                "schema" : {
                  "$ref" : "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description" : "Too many requests"
          },
          "500" : {
            "content" : {
              "application/json" : {
                "schema" : {
                  "$ref" : "#/components/schemas/RequestError"
                }
              }
            },
            "description" : "Downstream system error"
          }
        },
        "security" : [ {
          "BearerAuth" : [ ]
        } ],
        "summary" : "Create a payment",
        "tags" : [ "Card payments" ]
      }
    },
    "/v1/payments/{paymentId}" : {
      "get" : {
        "description" : "You can use this endpoint to [get details about a single payment you’ve previously created](https://docs.payments.service.gov.uk/reporting/#get-information-about-a-single-payment).",
        "operationId" : "Get a payment",
        "parameters" : [ {
          "description" : "Returns the payment with the matching `payment_id`.",
          "example" : "hu20sqlact5260q2nanm0q8u93",
          "in" : "path",
          "name" : "paymentId",
          "required" : true,
          "schema" : {
            "type" : "string"
          }
        } ],
        "responses" : {
          "200" : {
            "content" : {
              "application/json" : {
                "schema" : {
                  "$ref" : "#/components/schemas/PaymentWithAllLinks"
                }
              }
            },
            "description" : "OK - your request was successful."
          },
          "401" : {
            "description" : "Your API key is missing or invalid. Read more about [authenticating GOV.UK Pay API requests](https://docs.payments.service.gov.uk/api_reference/#authentication)"
          },
          "404" : {
            "content" : {
              "application/json" : {
                "schema" : {
                  "$ref" : "#/components/schemas/RequestError"
                }
              }
            },
            "description" : "Not found"
          },
          "429" : {
            "content" : {
              "application/json" : {
                "schema" : {
                  "$ref" : "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description" : "Too many requests"
          },
          "500" : {
            "content" : {
              "application/json" : {
                "schema" : {
                  "$ref" : "#/components/schemas/RequestError"
                }
              }
            },
            "description" : "Downstream system error"
          }
        },
        "security" : [ {
          "BearerAuth" : [ ]
        } ],
        "summary" : "Get information about a single payment",
        "tags" : [ "Card payments" ]
      }
    },
    "/v1/payments/{paymentId}/cancel" : {
      "post" : {
        "description" : "You can use this endpoint [to cancel an unfinished payment](https://docs.payments.service.gov.uk/making_payments/#cancel-a-payment-that-s-in-progress).",
        "operationId" : "Cancel a payment",
        "parameters" : [ {
          "description" : "The `payment_id` of the payment you’re cancelling.",
          "example" : "hu20sqlact5260q2nanm0q8u93",
          "in" : "path",
          "name" : "paymentId",
          "required" : true,
          "schema" : {
            "type" : "string"
          }
        } ],
        "responses" : {
          "204" : {
            "description" : "No Content"
          },
          "400" : {
            "content" : {
              "application/json" : {
                "schema" : {
                  "$ref" : "#/components/schemas/RequestError"
                }
              }
            },
            "description" : "Cancellation of payment failed"
          },
          "401" : {
            "description" : "Your API key is missing or invalid. Read more about [authenticating GOV.UK Pay API requests](https://docs.payments.service.gov.uk/api_reference/#authentication)"
          },
          "404" : {
            "content" : {
              "application/json" : {
                "schema" : {
                  "$ref" : "#/components/schemas/RequestError"
                }
              }
            },
            "description" : "Not found"
          },
          "409" : {
            "content" : {
              "application/json" : {
                "schema" : {
                  "$ref" : "#/components/schemas/RequestError"
                }
              }
            },
            "description" : "Conflict"
          },
          "429" : {
            "content" : {
              "application/json" : {
                "schema" : {
                  "$ref" : "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description" : "Too many requests"
          },
          "500" : {
            "content" : {
              "application/json" : {
                "schema" : {
                  "$ref" : "#/components/schemas/RequestError"
                }
              }
            },
            "description" : "Downstream system error"
          }
        },
        "security" : [ {
          "BearerAuth" : [ ]
        } ],
        "summary" : "Cancel payment",
        "tags" : [ "Card payments" ]
      }
    },
    "/v1/payments/{paymentId}/capture" : {
      "post" : {
        "description" : "You can use this endpoint to [take (‘capture’) a delayed payment from the paying user’s bank account](https://docs.payments.service.gov.uk/delayed_capture/).",
        "operationId" : "Capture a payment",
        "parameters" : [ {
          "description" : "The `payment_id` of the payment you’re capturing.",
          "example" : "hu20sqlact5260q2nanm0q8u93",
          "in" : "path",
          "name" : "paymentId",
          "required" : true,
          "schema" : {
            "type" : "string"
          }
        } ],
        "responses" : {
          "204" : {
            "description" : "No Content"
          },
          "400" : {
            "content" : {
              "application/json" : {
                "schema" : {
                  "$ref" : "#/components/schemas/RequestError"
                }
              }
            },
            "description" : "Capture of payment failed"
          },
          "401" : {
            "description" : "Your API key is missing or invalid. Read more about [authenticating GOV.UK Pay API requests](https://docs.payments.service.gov.uk/api_reference/#authentication)"
          },
          "404" : {
            "content" : {
              "application/json" : {
                "schema" : {
                  "$ref" : "#/components/schemas/RequestError"
                }
              }
            },
            "description" : "Not found"
          },
          "409" : {
            "content" : {
              "application/json" : {
                "schema" : {
                  "$ref" : "#/components/schemas/RequestError"
                }
              }
            },
            "description" : "Conflict"
          },
          "429" : {
            "content" : {
              "application/json" : {
                "schema" : {
                  "$ref" : "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description" : "Too many requests"
          },
          "500" : {
            "content" : {
              "application/json" : {
                "schema" : {
                  "$ref" : "#/components/schemas/RequestError"
                }
              }
            },
            "description" : "Downstream system error"
          }
        },
        "security" : [ {
          "BearerAuth" : [ ]
        } ],
        "summary" : "Take a delayed payment",
        "tags" : [ "Card payments" ]
      }
    },
    "/v1/payments/{paymentId}/events" : {
      "get" : {
        "description" : "You can use this endpoint to [get a list of a payment’s events](https://docs.payments.service.gov.uk/reporting/#get-a-payment-s-events). A payment event is when a payment’s `state` changes, such as when the payment is created, or when the paying user submits their details.",
        "operationId" : "Get events for a payment",
        "parameters" : [ {
          "description" : "Payment identifier",
          "example" : "hu20sqlact5260q2nanm0q8u93",
          "in" : "path",
          "name" : "paymentId",
          "required" : true,
          "schema" : {
            "type" : "string"
          }
        } ],
        "responses" : {
          "200" : {
            "content" : {
              "application/json" : {
                "schema" : {
                  "$ref" : "#/components/schemas/PaymentEvents"
                }
              }
            },
            "description" : "OK - your request was successful."
          },
          "401" : {
            "description" : "Your API key is missing or invalid. Read more about [authenticating GOV.UK Pay API requests](https://docs.payments.service.gov.uk/api_reference/#authentication)"
          },
          "404" : {
            "content" : {
              "application/json" : {
                "schema" : {
                  "$ref" : "#/components/schemas/RequestError"
                }
              }
            },
            "description" : "Not found"
          },
          "429" : {
            "content" : {
              "application/json" : {
                "schema" : {
                  "$ref" : "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description" : "Too many requests"
          },
          "500" : {
            "content" : {
              "application/json" : {
                "schema" : {
                  "$ref" : "#/components/schemas/RequestError"
                }
              }
            },
            "description" : "Downstream system error"
          }
        },
        "security" : [ {
          "BearerAuth" : [ ]
        } ],
        "summary" : "Get a payment's events",
        "tags" : [ "Card payments" ]
      }
    },
    "/v1/payments/{paymentId}/refunds" : {
      "get" : {
        "description" : "You can use this endpoint to [get a list of refunds for a payment](https://docs.payments.service.gov.uk/refunding_payments/#get-all-refunds-for-a-single-payment).",
        "operationId" : "Get all refunds for a payment",
        "parameters" : [ {
          "description" : "The unique `payment_id` of the payment you want a list of refunds for.",
          "in" : "path",
          "name" : "paymentId",
          "required" : true,
          "schema" : {
            "type" : "string"
          }
        } ],
        "responses" : {
          "200" : {
            "content" : {
              "application/json" : {
                "schema" : {
                  "$ref" : "#/components/schemas/RefundForSearchResult"
                }
              }
            },
            "description" : "OK - your request was successful."
          },
          "401" : {
            "description" : "Your API key is missing or invalid. Read more about [authenticating GOV.UK Pay API requests](https://docs.payments.service.gov.uk/api_reference/#authentication)"
          },
          "404" : {
            "content" : {
              "application/json" : {
                "schema" : {
                  "$ref" : "#/components/schemas/RequestError"
                }
              }
            },
            "description" : "Not found"
          },
          "429" : {
            "content" : {
              "application/json" : {
                "schema" : {
                  "$ref" : "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description" : "Too many requests"
          },
          "500" : {
            "content" : {
              "application/json" : {
                "schema" : {
                  "$ref" : "#/components/schemas/RequestError"
                }
              }
            },
            "description" : "Downstream system error"
          }
        },
        "security" : [ {
          "BearerAuth" : [ ]
        } ],
        "summary" : "Get information about a payment’s refunds",
        "tags" : [ "Refunding card payments" ]
      },
      "post" : {
        "description" : "You can use this endpoint to [fully or partially refund a payment](https://docs.payments.service.gov.uk/refunding_payments).",
        "operationId" : "Submit a refund for a payment",
        "parameters" : [ {
          "description" : "The unique `payment_id` of the payment you want to refund.",
          "in" : "path",
          "name" : "paymentId",
          "required" : true,
          "schema" : {
            "type" : "string"
          }
        } ],
        "requestBody" : {
          "content" : {
            "application/json" : {
              "schema" : {
                "$ref" : "#/components/schemas/PaymentRefundRequest"
              }
            }
          },
          "description" : "requestPayload",
          "required" : true
        },
        "responses" : {
          "200" : {
            "content" : {
              "application/json" : {
                "schema" : {
                  "$ref" : "#/components/schemas/Refund"
                }
              }
            },
            "description" : "successful operation"
          },
          "202" : {
            "description" : "ACCEPTED"
          },
          "401" : {
            "description" : "Your API key is missing or invalid. Read more about [authenticating GOV.UK Pay API requests](https://docs.payments.service.gov.uk/api_reference/#authentication)"
          },
          "404" : {
            "content" : {
              "application/json" : {
                "schema" : {
                  "$ref" : "#/components/schemas/RequestError"
                }
              }
            },
            "description" : "Not found"
          },
          "412" : {
            "description" : "Refund amount available mismatch"
          },
          "429" : {
            "content" : {
              "application/json" : {
                "schema" : {
                  "$ref" : "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description" : "Too many requests"
          },
          "500" : {
            "content" : {
              "application/json" : {
                "schema" : {
                  "$ref" : "#/components/schemas/RequestError"
                }
              }
            },
            "description" : "Downstream system error"
          }
        },
        "security" : [ {
          "BearerAuth" : [ ]
        } ],
        "summary" : "Refund a payment",
        "tags" : [ "Refunding card payments" ]
      }
    },
    "/v1/payments/{paymentId}/refunds/{refundId}" : {
      "get" : {
        "description" : "You can use this endpoint to [get details about an individual refund](https://docs.payments.service.gov.uk/refunding_payments/#checking-the-status-of-a-refund).",
        "operationId" : "Get a payment refund",
        "parameters" : [ {
          "description" : "The unique `payment_id` of the payment you want to view a refund of.",
          "in" : "path",
          "name" : "paymentId",
          "required" : true,
          "schema" : {
            "type" : "string"
          }
        }, {
          "description" : "The unique `refund_id` of the refund you want to view. If one payment has multiple refunds, each refund has a different `refund_id`.",
          "in" : "path",
          "name" : "refundId",
          "required" : true,
          "schema" : {
            "type" : "string"
          }
        } ],
        "responses" : {
          "200" : {
            "content" : {
              "application/json" : {
                "schema" : {
                  "$ref" : "#/components/schemas/Refund"
                }
              }
            },
            "description" : "OK - your request was successful."
          },
          "401" : {
            "description" : "Your API key is missing or invalid. Read more about [authenticating GOV.UK Pay API requests](https://docs.payments.service.gov.uk/api_reference/#authentication)"
          },
          "404" : {
            "content" : {
              "application/json" : {
                "schema" : {
                  "$ref" : "#/components/schemas/RequestError"
                }
              }
            },
            "description" : "Not found"
          },
          "429" : {
            "content" : {
              "application/json" : {
                "schema" : {
                  "$ref" : "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description" : "Too many requests"
          },
          "500" : {
            "content" : {
              "application/json" : {
                "schema" : {
                  "$ref" : "#/components/schemas/RequestError"
                }
              }
            },
            "description" : "Downstream system error"
          }
        },
        "security" : [ {
          "BearerAuth" : [ ]
        } ],
        "summary" : "Check the status of a refund",
        "tags" : [ "Refunding card payments" ]
      }
    },
    "/v1/refunds" : {
      "get" : {
        "description" : "You can use this endpoint to [search refunds you’ve previously created](https://docs.payments.service.gov.uk/refunding_payments/#searching-refunds). The refunds are sorted by date, with the most recently created refunds appearing first.",
        "operationId" : "Search refunds",
        "parameters" : [ {
          "description" : "Returns refunds created on or after the `from_date`. Date and time must use Coordinated Universal Time (UTC) and ISO 8601 format to second-level accuracy - `YYYY-MM-DDThh:mm:ssZ`.",
          "example" : "2015-08-13T12:35:00Z",
          "in" : "query",
          "name" : "from_date",
          "schema" : {
            "type" : "string"
          }
        }, {
          "description" : "Returns refunds created before the `to_date`. Date and time must use Coordinated Universal Time (UTC) and ISO 8601 format to second-level accuracy - `YYYY-MM-DDThh:mm:ssZ`.",
          "example" : "2015-08-13T12:35:00Z",
          "in" : "query",
          "name" : "to_date",
          "schema" : {
            "type" : "string"
          }
        }, {
          "description" : "Returns refunds settled on or after the `from_settled_date` value. You can only use `from_settled_date` if your payment service provider is Stripe. Date must use ISO 8601 format to date-level accuracy - `YYYY-MM-DD`. Refunds are settled when Stripe takes the refund from your account balance.",
          "example" : "2022-08-13",
          "in" : "query",
          "name" : "from_settled_date",
          "schema" : {
            "type" : "string"
          }
        }, {
          "description" : "Returns refunds settled before the `to_settled_date` value. You can only use `to_settled_date` if your payment service provider is Stripe. Date must use ISO 8601 format to date-level accuracy - `YYYY-MM-DD`. Refunds are settled when Stripe takes the refund from your account balance.",
          "example" : "2022-08-13",
          "in" : "query",
          "name" : "to_settled_date",
          "schema" : {
            "type" : "string"
          }
        }, {
          "description" : "Returns a [specific page of results](https://docs.payments.service.gov.uk/api_reference/#pagination). Defaults to `1`.",
          "in" : "query",
          "name" : "page",
          "schema" : {
            "type" : "string"
          }
        }, {
          "description" : "The number of refunds returned [per results page](https://docs.payments.service.gov.uk/api_reference/#pagination). Defaults to `500`. Maximum value is `500`.",
          "in" : "query",
          "name" : "display_size",
          "schema" : {
            "type" : "string"
          }
        } ],
        "responses" : {
          "200" : {
            "content" : {
              "application/json" : {
                "schema" : {
                  "$ref" : "#/components/schemas/RefundSearchResults"
                }
              }
            },
            "description" : "OK - your request was successful."
          },
          "401" : {
            "description" : "Your API key is missing or invalid. Read more about [authenticating GOV.UK Pay API requests](https://docs.payments.service.gov.uk/api_reference/#authentication)"
          },
          "422" : {
            "content" : {
              "application/json" : {
                "schema" : {
                  "$ref" : "#/components/schemas/RequestError"
                }
              }
            },
            "description" : "Invalid parameters. See Public API documentation for the correct data formats"
          },
          "500" : {
            "content" : {
              "application/json" : {
                "schema" : {
                  "$ref" : "#/components/schemas/RequestError"
                }
              }
            },
            "description" : "Downstream system error"
          }
        },
        "security" : [ {
          "BearerAuth" : [ ]
        } ],
        "summary" : "Search refunds",
        "tags" : [ "Refunding card payments" ]
      }
    }
  },
  "components" : {
    "schemas" : {
      "Address" : {
        "type" : "object",
        "description" : "A structure representing the billing address of a card",
        "properties" : {
          "city" : {
            "type" : "string",
            "description" : "The paying user's city.",
            "example" : "address city",
            "maxLength" : 255,
            "minLength" : 0
          },
          "country" : {
            "type" : "string",
            "description" : "The paying user’s country, displayed as a 2-character ISO-3166-1-alpha-2 code.",
            "example" : "GB"
          },
          "line1" : {
            "type" : "string",
            "description" : "The first line of the paying user’s address.",
            "example" : "address line 1",
            "maxLength" : 255,
            "minLength" : 0
          },
          "line2" : {
            "type" : "string",
            "description" : "The second line of the paying user’s address.",
            "example" : "address line 2",
            "maxLength" : 255,
            "minLength" : 0
          },
          "postcode" : {
            "type" : "string",
            "description" : "The paying user's postcode.",
            "example" : "AB1 2CD",
            "maxLength" : 25,
            "minLength" : 0
          }
        }
      },
      "Agreement" : {
        "type" : "object",
        "description" : "Contains information about a user's agreement for recurring payments. An agreement represents an understanding between you and your paying user that you'll use their card to make ongoing payments for a service.",
        "properties" : {
          "agreement_id" : {
            "type" : "string",
            "description" : "The unique ID GOV.UK Pay automatically associated with this agreement when you created it.",
            "example" : "cgc1ocvh0pt9fqs0ma67r42l58"
          },
          "cancelled_date" : {
            "type" : "string",
            "description" : "The date and time this agreement was cancelled. This value uses Coordinated Universal Time (UTC) and ISO 8601 format – `YYYY-MM-DDThh:mm:ss.sssZ`.",
            "example" : "2022-07-08T14:33:00.000Z"
          },
          "created_date" : {
            "type" : "string",
            "description" : "The date and time you created this agreement. This value uses Coordinated Universal Time (UTC) and ISO 8601 format – `YYYY-MM-DDThh:mm:ss.sssZ`.",
            "example" : "2022-07-08T14:33:00.000Z"
          },
          "description" : {
            "type" : "string",
            "description" : "The description you sent when creating this agreement.",
            "example" : "Dorset Council 2022/23 council tax subscription."
          },
          "payment_instrument" : {
            "$ref" : "#/components/schemas/PaymentInstrument"
          },
          "reference" : {
            "type" : "string",
            "description" : "The reference you sent when creating this agreement.",
            "example" : "CT-22-23-0001"
          },
          "status" : {
            "type" : "string",
            "description" : "The status of this agreement. You can [read more about the meanings of each agreement status.](https://docs.payments.service.gov.uk/recurring_payments/#understanding-agreement-status)",
            "enum" : [ "created", "active", "cancelled", "inactive" ]
          },
          "user_identifier" : {
            "type" : "string",
            "description" : "The identifier you sent when creating this agreement. `user_identifier` helps you identify users in your records.",
            "example" : "user-3fb81107-76b7-4910"
          }
        }
      },
      "AgreementSearchResults" : {
        "type" : "object",
        "properties" : {
          "_links" : {
            "$ref" : "#/components/schemas/SearchNavigationLinks"
          },
          "count" : {
            "type" : "integer",
            "format" : "int32",
            "description" : "Number of agreements on the current page of search results.",
            "example" : 20
          },
          "page" : {
            "type" : "integer",
            "format" : "int32",
            "description" : "The [page of agreements you’re viewing](https://docs.payments.service.gov.uk/api_reference/#pagination). To view other pages, make this request again using the `page` parameter.",
            "example" : 1
          },
          "results" : {
            "type" : "array",
            "description" : "Contains agreements matching your search criteria.",
            "items" : {
              "$ref" : "#/components/schemas/Agreement"
            }
          },
          "total" : {
            "type" : "integer",
            "format" : "int32",
            "description" : "Total number of agreements matching your search criteria.",
            "example" : 100
          }
        }
      },
      "AuthorisationRequest" : {
        "type" : "object",
        "description" : "Contains the user's payment information. This information will be sent to the payment service provider to authorise the payment.",
        "properties" : {
          "card_number" : {
            "type" : "string",
            "description" : "The full card number from the paying user's card.",
            "example" : "4242424242424242",
            "maxLength" : 19,
            "minLength" : 12
          },
          "cardholder_name" : {
            "type" : "string",
            "description" : "The name on the paying user's card.",
            "example" : "J. Citizen",
            "maxLength" : 255,
            "minLength" : 0
          },
          "cvc" : {
            "type" : "string",
            "description" : "The card verification code (CVC) or card verification value (CVV) on the paying user's card.",
            "example" : "123",
            "maxLength" : 4,
            "minLength" : 3
          },
          "expiry_date" : {
            "type" : "string",
            "description" : "The expiry date of the paying user's card. This value must be in `MM/YY` format.",
            "example" : "09/22",
            "maxLength" : 5,
            "minLength" : 5
          },
          "one_time_token" : {
            "type" : "string",
            "description" : "This single use token authorises your request and matches it to a payment. GOV.UK Pay generated the `one_time_token` when the payment was created.",
            "example" : "12345-edsfr-6789-gtyu"
          }
        },
        "required" : [ "card_number", "cardholder_name", "cvc", "expiry_date", "one_time_token" ]
      },
      "AuthorisationSummary" : {
        "type" : "object",
        "description" : "Object containing information about the authentication of the payment.",
        "properties" : {
          "three_d_secure" : {
            "$ref" : "#/components/schemas/ThreeDSecure"
          }
        }
      },
      "CardDetails" : {
        "type" : "object",
        "description" : "A structure representing the payment card",
        "properties" : {
          "billing_address" : {
            "$ref" : "#/components/schemas/Address"
          },
          "card_brand" : {
            "type" : "string",
            "description" : "The brand of card the user paid with.",
            "example" : "Visa",
            "readOnly" : true
          },
          "card_type" : {
            "type" : "string",
            "description" : "The type of card the user paid with.`null` means your user paid with Google Pay or we did not recognise which type of card they paid with.",
            "enum" : [ "debit", "credit", "null" ],
            "example" : "debit",
            "readOnly" : true
          },
          "cardholder_name" : {
            "type" : "string",
            "example" : "Mr. Card holder"
          },
          "expiry_date" : {
            "type" : "string",
            "description" : "The expiry date of the card the user paid with in `MM/YY` format.",
            "example" : "04/24",
            "readOnly" : true
          },
          "first_digits_card_number" : {
            "type" : "string",
            "example" : "123456",
            "readOnly" : true
          },
          "last_digits_card_number" : {
            "type" : "string",
            "example" : "1234",
            "readOnly" : true
          },
          "wallet_type" : {
            "type" : "string",
            "description" : "The digital wallet type that the user paid with",
            "enum" : [ "Apple Pay", "Google Pay" ],
            "example" : "Apple Pay"
          }
        }
      },
      "CardDetailsFromResponse" : {
        "type" : "object",
        "properties" : {
          "billing_address" : {
            "$ref" : "#/components/schemas/Address"
          },
          "card_brand" : {
            "type" : "string"
          },
          "card_type" : {
            "type" : "string"
          },
          "cardholder_name" : {
            "type" : "string"
          },
          "expiry_date" : {
            "type" : "string"
          },
          "first_digits_card_number" : {
            "type" : "string"
          },
          "last_digits_card_number" : {
            "type" : "string"
          }
        }
      },
      "CreateAgreementRequest" : {
        "type" : "object",
        "description" : "The Agreement Request Payload",
        "properties" : {
          "description" : {
            "type" : "string",
            "description" : "A human-readable description of the purpose of the agreement for recurring payments. We’ll show the description to your user when they make their first payment to activate this agreement. Limited to 255 characters.",
            "example" : "Dorset Council 2022/23 council tax subscription.",
            "maxLength" : 255,
            "minLength" : 1
          },
          "reference" : {
            "type" : "string",
            "description" : "Associate a reference with this agreement to help you identify it. Limited to 255 characters.",
            "example" : "CT-22-23-0001",
            "maxLength" : 255,
            "minLength" : 1
          },
          "user_identifier" : {
            "type" : "string",
            "description" : "Associate an identifier with the user who will enter into this agreement with your service.user_identifier is not unique – multiple agreements can have identical user_identifier values.You should not include personal data in user_identifier.",
            "example" : "user-3fb81107-76b7-4910",
            "maxLength" : 255,
            "minLength" : 1
          }
        }
      },
      "CreateCardPaymentRequest" : {
        "type" : "object",
        "description" : "The create payment request body",
        "properties" : {
          "agreement_id" : {
            "type" : "string",
            "description" : "The unique ID GOV.UK Pay automatically associated with a recurring payments agreement. Including `agreement_id` in your request tells the API to take this payment using the card details that are associated with this agreement. `agreement_id` must match an active agreement ID. You must set `authorisation_mode` to `agreement` for the API to accept `agreement_id`.",
            "example" : "abcefghjklmnopqr1234567890",
            "maxLength" : 26,
            "minLength" : 26
          },
          "amount" : {
            "type" : "integer",
            "format" : "int32",
            "description" : "Sets the amount the user will pay, in pence.",
            "example" : 12000,
            "maximum" : 10000000,
            "minimum" : 0
          },
          "authorisation_mode" : {
            "type" : "string",
            "description" : "Sets how you intend to authorise the payment. Defaults to `web`. Payments created with `web` mode follow the [standard GOV.UK Pay payment journey](https://docs.payments.service.gov.uk/payment_flow/). Paying users visit the `next_url` in the response to complete their payment. Payments created with `agreement` mode are authorised with an agreement for recurring payments. If you create an `agreement` payment, you must also send an active `agreement_id`. You must not send `return_url`, `email`, or `prefilled_cardholder_details` or your request will fail. Payments created with `moto_api` mode return an `auth_url_post` object and a `one_time_token`. You can use `auth_url_post` and `one_time_token` to send the paying user’s card details through the API and complete the payment. If you create a `moto_api` payment, do not send a `return_url` in your request.",
            "enum" : [ "web", "agreement", "moto_api" ]
          },
          "delayed_capture" : {
            "type" : "boolean",
            "description" : "You can use this parameter to [delay taking a payment from the paying user’s bank account](https://docs.payments.service.gov.uk/delayed_capture/#delay-taking-a-payment). For example, you might want to do your own anti-fraud checks on payments, or check that users are eligible for your service. Defaults to `false`.",
            "example" : false
          },
          "description" : {
            "type" : "string",
            "description" : "A human-readable description of the payment you’re creating. Paying users see this description on the payment pages. Service staff see the description in the GOV.UK Pay admin tool",
            "example" : "New passport application",
            "maxLength" : 255,
            "minLength" : 0
          },
          "email" : {
            "type" : "string",
            "description" : "email",
            "example" : "Joe.Bogs@example.org"
          },
          "language" : {
            "type" : "string",
            "description" : "[Sets the language of the user’s payment page](https://docs.payments.service.gov.uk/optional_features/welsh_language) with an ISO-6391 Alpha-2 code of a supported language.",
            "enum" : [ "en", "cy" ],
            "example" : "en"
          },
          "metadata" : {
            "$ref" : "#/components/schemas/ExternalMetadata"
          },
          "moto" : {
            "type" : "boolean",
            "description" : "You can use this parameter to [designate a payment as a Mail Order / Telephone Order (MOTO) payment](https://docs.payments.service.gov.uk/moto_payments).",
            "example" : false
          },
          "prefilled_cardholder_details" : {
            "$ref" : "#/components/schemas/PrefilledCardholderDetails"
          },
          "reference" : {
            "type" : "string",
            "description" : "Associate a reference with this payment. `reference` is not unique - multiple payments can have identical `reference` values.",
            "example" : "12345",
            "maxLength" : 255,
            "minLength" : 0
          },
          "return_url" : {
            "type" : "string",
            "description" : "The URL [the paying user is directed to after their payment journey on GOV.UK Pay ends](https://docs.payments.service.gov.uk/making_payments/#choose-the-return-url-and-match-your-users-to-payments).",
            "example" : "https://service-name.gov.uk/transactions/12345",
            "maxLength" : 2000,
            "minLength" : 0
          },
          "set_up_agreement" : {
            "type" : "string",
            "description" : "Use this parameter to set up an existing agreement for recurring payments. The `set_up_agreement` value you send must be a valid `agreement_id`.",
            "example" : "abcefghjklmnopqr1234567890",
            "maxLength" : 26,
            "minLength" : 26
          }
        },
        "required" : [ "amount", "description", "reference", "return_url" ]
      },
      "CreatePaymentResult" : {
        "type" : "object",
        "properties" : {
          "_links" : {
            "$ref" : "#/components/schemas/PaymentLinks"
          },
          "amount" : {
            "type" : "integer",
            "format" : "int64",
            "description" : "The amount, in pence, the user has paid or will pay. `amount` will match the value you sent in the request body.",
            "example" : 1200
          },
          "card_details" : {
            "$ref" : "#/components/schemas/CardDetailsFromResponse"
          },
          "created_date" : {
            "type" : "string",
            "description" : "The date you created the payment.",
            "example" : "2016-01-21T17:15:00.000Z"
          },
          "delayed_capture" : {
            "type" : "boolean",
            "description" : "`delayed_capture` is `true` if you’re controlling [when GOV.UK Pay takes (‘captures’) the payment from the paying user’s bank account](https://docs.payments.service.gov.uk/delayed_capture).",
            "example" : false,
            "readOnly" : true
          },
          "description" : {
            "type" : "string",
            "description" : "The description you sent in the request body when creating this payment.",
            "example" : "New passport application"
          },
          "email" : {
            "type" : "string",
            "description" : "The paying user’s email address. The paying user’s email field will be prefilled with this value when they make their payment. `email` does not appear if you did not include it in the request body.",
            "example" : "citizen@example.org"
          },
          "language" : {
            "type" : "string",
            "description" : "The language of the user’s payment page.",
            "enum" : [ "en", "cy" ],
            "example" : "en"
          },
          "metadata" : {
            "$ref" : "#/components/schemas/ExternalMetadata"
          },
          "moto" : {
            "type" : "boolean",
            "description" : "Indicates if this payment is a [Mail Order / Telephone Order (MOTO) payment](https://docs.payments.service.gov.uk/moto_payments).",
            "example" : false
          },
          "payment_id" : {
            "type" : "string",
            "description" : "The unique ID GOV.UK Pay automatically associated with this payment when you created it.",
            "example" : "hu20sqlact5260q2nanm0q8u93"
          },
          "payment_provider" : {
            "type" : "string",
            "example" : "worldpay"
          },
          "provider_id" : {
            "type" : "string",
            "description" : "The reference number your payment service provider associated with the payment.",
            "example" : "null"
          },
          "reference" : {
            "type" : "string",
            "description" : "The reference number you associated with this payment.",
            "example" : "12345"
          },
          "refund_summary" : {
            "$ref" : "#/components/schemas/RefundSummary"
          },
          "return_url" : {
            "type" : "string",
            "description" : "The URL you direct the paying user to after their payment journey on GOV.UK Pay ends.",
            "example" : "https://service-name.gov.uk/transactions/12345"
          },
          "settlement_summary" : {
            "$ref" : "#/components/schemas/PaymentSettlementSummary"
          },
          "state" : {
            "$ref" : "#/components/schemas/PaymentState"
          }
        }
      },
      "DisputeDetailForSearch" : {
        "type" : "object",
        "description" : "Contains disputes matching your search criteria.",
        "properties" : {
          "_links" : {
            "$ref" : "#/components/schemas/DisputeLinksForSearch"
          },
          "amount" : {
            "type" : "integer",
            "format" : "int64",
            "description" : "The disputed amount in pence.",
            "example" : 1200,
            "readOnly" : true
          },
          "created_date" : {
            "type" : "string",
            "description" : "The date and time the user's bank told GOV.UK Pay about this dispute.",
            "example" : "2022-07-28T16:43:00.000Z",
            "readOnly" : true
          },
          "dispute_id" : {
            "type" : "string",
            "description" : "The unique ID GOV.UK Pay automatically associated with this dispute when the paying user disputed the payment.",
            "example" : "hu20sqlact5260q2nanm0q8u93",
            "readOnly" : true
          },
          "evidence_due_date" : {
            "type" : "string",
            "description" : "The deadline for submitting your supporting evidence. This value uses Coordinated Universal Time (UTC) and ISO 8601 format",
            "example" : "2022-07-28T16:43:00.000Z",
            "readOnly" : true
          },
          "fee" : {
            "type" : "integer",
            "format" : "int64",
            "description" : "The payment service provider’s dispute fee, in pence.",
            "example" : 1200,
            "readOnly" : true
          },
          "net_amount" : {
            "type" : "integer",
            "format" : "int64",
            "description" : "The amount, in pence, your payment service provider will take for a lost dispute. 'net_amount' is deducted from your payout after you lose the dispute. For example, a 'net_amount' of '-1500' means your PSP will take £15.00 from your next payout into your bank account. 'net_amount' is always a negative value. 'net_amount' only appears if you lose the dispute.",
            "example" : -2400,
            "readOnly" : true
          },
          "payment_id" : {
            "type" : "string",
            "description" : "The unique ID GOV.UK Pay automatically associated with this payment when you created it.",
            "example" : "hu20sqlact5260q2nanm0q8u93",
            "readOnly" : true
          },
          "reason" : {
            "type" : "string",
            "description" : "The reason the paying user gave for disputing this payment. Possible values are: 'credit_not_processed', 'duplicate', 'fraudulent', 'general', 'product_not_received', 'product_unacceptable', 'unrecognised', 'subscription_cancelled', >'other'",
            "example" : "fraudulent",
            "readOnly" : true
          },
          "settlement_summary" : {
            "$ref" : "#/components/schemas/SettlementSummary"
          },
          "status" : {
            "type" : "string",
            "description" : "The current status of the dispute. Possible values are: 'needs_response', 'won', 'lost', 'under_review'",
            "example" : "under_review",
            "readOnly" : true
          }
        }
      },
      "DisputeLinksForSearch" : {
        "type" : "object",
        "description" : "links for search dispute resource",
        "properties" : {
          "payment" : {
            "$ref" : "#/components/schemas/Link"
          }
        }
      },
      "DisputesSearchResults" : {
        "type" : "object",
        "properties" : {
          "count" : {
            "type" : "integer",
            "format" : "int32",
            "description" : "Number of disputes on the current page of search results.",
            "example" : 20
          },
          "links" : {
            "$ref" : "#/components/schemas/SearchNavigationLinks"
          },
          "page" : {
            "type" : "integer",
            "format" : "int32",
            "description" : "The page of results you’re viewing. To view other pages, make this request again using the 'page' parameter.",
            "example" : 1
          },
          "results" : {
            "type" : "array",
            "description" : "Contains disputes matching your search criteria.",
            "items" : {
              "$ref" : "#/components/schemas/DisputeDetailForSearch"
            }
          },
          "total" : {
            "type" : "integer",
            "format" : "int32",
            "description" : "Number of total disputes matching your search criteria.",
            "example" : 100
          }
        }
      },
      "EmbeddedRefunds" : {
        "type" : "object",
        "properties" : {
          "refunds" : {
            "type" : "array",
            "items" : {
              "$ref" : "#/components/schemas/Refund"
            }
          }
        }
      },
      "ErrorResponse" : {
        "type" : "object",
        "description" : "An error response",
        "properties" : {
          "code" : {
            "type" : "string",
            "description" : "A GOV.UK Pay API error code. You can [find out more about this code in our documentation](https://docs.payments.service.gov.uk/api_reference/#gov-uk-pay-api-error-codes).",
            "example" : "P0900"
          },
          "description" : {
            "type" : "string",
            "description" : "Additional details about the error",
            "example" : "Too many requests"
          }
        }
      },
      "Exemption" : {
        "type" : "object",
        "description" : "A structure representing that 3DS exemption was requested and the outcome of the exemption, if applicable.",
        "properties" : {
          "outcome" : {
            "$ref" : "#/components/schemas/Outcome"
          },
          "requested" : {
            "type" : "boolean",
            "description" : "Indicates whether an exemption was requested for the given payment.",
            "example" : true,
            "readOnly" : true
          },
          "type" : {
            "type" : "string",
            "description" : "Indicates the type of exemption. Only present for corporate exemption",
            "example" : "corporate",
            "readOnly" : true
          }
        }
      },
      "ExternalMetadata" : {
        "type" : "object",
        "example" : "{\"property1\": \"value1\", \"property2\": \"value2\"}\"",
        "properties" : {
          "metadata" : {
            "type" : "object",
            "additionalProperties" : {
              "type" : "object"
            }
          }
        }
      },
      "Link" : {
        "type" : "object",
        "description" : "A link related to a payment",
        "properties" : {
          "href" : {
            "type" : "string",
            "description" : "A URL that lets you perform additional actions to this payment when combined with the associated `method`.",
            "example" : "https://an.example.link/from/payment/platform",
            "readOnly" : true
          },
          "method" : {
            "type" : "string",
            "description" : "An API method that lets you perform additional actions to this paymentwhen combined with the associated `href`.",
            "example" : "GET",
            "readOnly" : true
          }
        }
      },
      "Outcome" : {
        "type" : "object",
        "description" : "A structure representing the outcome of a 3DS exemption, if known.",
        "properties" : {
          "result" : {
            "type" : "string",
            "description" : "The outcome of the requested exemption",
            "example" : "honoured",
            "readOnly" : true
          }
        },
        "readOnly" : true
      },
      "PaymentDetailForSearch" : {
        "type" : "object",
        "description" : "Contains payments matching your search criteria.",
        "properties" : {
          "_links" : {
            "$ref" : "#/components/schemas/PaymentLinksForSearch"
          },
          "amount" : {
            "type" : "integer",
            "format" : "int64",
            "description" : "The description assigned to the payment when it was created.",
            "example" : 1200
          },
          "authorisation_mode" : {
            "type" : "string",
            "description" : "How the payment will be authorised. Payments created in `web` mode require the paying user to visit the `next_url` to complete the payment.",
            "enum" : [ "web", "moto_api", "external" ]
          },
          "authorisation_summary" : {
            "$ref" : "#/components/schemas/AuthorisationSummary"
          },
          "card_brand" : {
            "type" : "string",
            "deprecated" : true,
            "description" : "This attribute is deprecated. Please use `card_details.card_brand` instead.",
            "example" : "Visa",
            "readOnly" : true
          },
          "card_details" : {
            "$ref" : "#/components/schemas/CardDetails"
          },
          "corporate_card_surcharge" : {
            "type" : "integer",
            "format" : "int64",
            "description" : "The [corporate card surcharge](https://docs.payments.service.gov.uk/corporate_card_surcharges/#add-corporate-card-fees) amount in pence.",
            "example" : 250,
            "readOnly" : true
          },
          "created_date" : {
            "type" : "string",
            "example" : "2016-01-21T17:15:00.000Z",
            "readOnly" : true
          },
          "delayed_capture" : {
            "type" : "boolean",
            "description" : "`delayed_capture` is `true` if you’re [controlling how long it takes GOV.UK Pay to take (‘capture’) a payment](https://docs.payments.service.gov.uk/delayed_capture).",
            "example" : false,
            "readOnly" : true
          },
          "description" : {
            "type" : "string",
            "description" : "The description assigned to the payment when it was created.",
            "example" : "Your Service Description"
          },
          "email" : {
            "type" : "string",
            "example" : "The paying user’s email address."
          },
          "exemption" : {
            "$ref" : "#/components/schemas/Exemption"
          },
          "fee" : {
            "type" : "integer",
            "format" : "int64",
            "description" : "The [payment service provider’s (PSP) transaction fee](https://docs.payments.service.gov.uk/reporting/#psp-fees), in pence. `fee` only appears when we have taken (‘captured’) the payment from the user or if their payment fails after they submitted their card details. `fee` will not appear if your PSP is Worldpay or you are using an API key from a test service.",
            "example" : 5,
            "readOnly" : true
          },
          "language" : {
            "type" : "string",
            "description" : "The ISO-6391 Alpha-2 code of the [language of the user's payment page](https://docs.payments.service.gov.uk/optional_features/welsh_language).",
            "enum" : [ "en", "cy" ],
            "example" : "en"
          },
          "metadata" : {
            "$ref" : "#/components/schemas/ExternalMetadata"
          },
          "moto" : {
            "type" : "boolean",
            "description" : "Indicates if this payment is a [Mail Order / Telephone Order (MOTO) payment](https://docs.payments.service.gov.uk/moto_payments).",
            "example" : false
          },
          "net_amount" : {
            "type" : "integer",
            "format" : "int64",
            "description" : "The amount, in pence, that will be paid into your bank account after your payment service provider takes the `fee`.",
            "example" : 1195,
            "readOnly" : true
          },
          "payment_id" : {
            "type" : "string",
            "description" : "The unique ID GOV.UK Pay automatically associated with this payment when you created it.",
            "example" : "hu20sqlact5260q2nanm0q8u93",
            "readOnly" : true
          },
          "payment_provider" : {
            "type" : "string",
            "description" : "The payment service provider that processed this payment.",
            "example" : "worldpay",
            "readOnly" : true
          },
          "provider_id" : {
            "type" : "string",
            "description" : "The unique ID your payment service provider generated for this payment. This is not the same as the `payment_id`.",
            "example" : "reference-from-payment-gateway",
            "readOnly" : true
          },
          "reference" : {
            "type" : "string",
            "description" : "The reference associated with the payment when it was created. `reference` is not unique - multiple payments can have the same `reference` value.",
            "example" : "your-reference"
          },
          "refund_summary" : {
            "$ref" : "#/components/schemas/RefundSummary"
          },
          "return_url" : {
            "type" : "string",
            "description" : "The URL you direct the paying user to after their payment journey on GOV.UK Pay ends.",
            "example" : "http://your.service.domain/your-reference",
            "readOnly" : true
          },
          "settlement_summary" : {
            "$ref" : "#/components/schemas/PaymentSettlementSummary"
          },
          "state" : {
            "$ref" : "#/components/schemas/PaymentState"
          },
          "total_amount" : {
            "type" : "integer",
            "format" : "int64",
            "description" : "Amount your user paid in pence, including corporate card fees. `total_amount` only appears if you [added a corporate card surcharge to the payment](https://docs.payments.service.gov.uk/corporate_card_surcharges/#add-corporate-card-fees).",
            "example" : 1450,
            "readOnly" : true
          }
        }
      },
      "PaymentEvent" : {
        "type" : "object",
        "description" : "A List of Payment Events information",
        "properties" : {
          "_links" : {
            "$ref" : "#/components/schemas/PaymentEventLink"
          },
          "payment_id" : {
            "type" : "string",
            "description" : "The unique ID GOV.UK Pay automatically associated with this payment when you created it.",
            "example" : "hu20sqlact5260q2nanm0q8u93",
            "readOnly" : true
          },
          "state" : {
            "$ref" : "#/components/schemas/PaymentState"
          },
          "updated" : {
            "type" : "string",
            "description" : "When this payment’s state changed. This value uses Coordinated Universal Time (UTC) and ISO-8601 format - `YYYY-MM-DDThh:mm:ss.SSSZ`.",
            "example" : "2017-01-10T16:44:48.646Z",
            "readOnly" : true
          }
        }
      },
      "PaymentEventLink" : {
        "type" : "object",
        "description" : "Resource link for a payment of a payment event",
        "properties" : {
          "payment_url" : {
            "$ref" : "#/components/schemas/Link"
          }
        }
      },
      "PaymentEvents" : {
        "type" : "object",
        "description" : "A List of Payment Events information",
        "properties" : {
          "_links" : {
            "$ref" : "#/components/schemas/PaymentLinksForEvents"
          },
          "events" : {
            "type" : "array",
            "items" : {
              "$ref" : "#/components/schemas/PaymentEvent"
            }
          },
          "payment_id" : {
            "type" : "string",
            "description" : "The unique ID GOV.UK Pay automatically associated with this payment when you created it.",
            "example" : "hu20sqlact5260q2nanm0q8u93",
            "readOnly" : true
          }
        }
      },
      "PaymentInstrument" : {
        "type" : "object",
        "properties" : {
          "CardDetails" : {
            "$ref" : "#/components/schemas/CardDetailsFromResponse"
          },
          "created_date" : {
            "type" : "string",
            "description" : "The date and time you created this payment instrument. This value uses Coordinated Universal Time (UTC) and ISO 8601 format – `YYYY-MM-DDThh:mm:ss.sssZ`.",
            "example" : "2022-07-08T14:33:00.000Z"
          },
          "type" : {
            "type" : "string",
            "description" : "The type of payment instrument.",
            "enum" : [ "card" ]
          }
        }
      },
      "PaymentLinks" : {
        "type" : "object",
        "description" : "links for payment",
        "properties" : {
          "auth_url_post" : {
            "$ref" : "#/components/schemas/PostLink"
          },
          "cancel" : {
            "$ref" : "#/components/schemas/PostLink"
          },
          "capture" : {
            "$ref" : "#/components/schemas/PostLink"
          },
          "events" : {
            "$ref" : "#/components/schemas/Link"
          },
          "next_url" : {
            "$ref" : "#/components/schemas/Link"
          },
          "next_url_post" : {
            "$ref" : "#/components/schemas/PostLink"
          },
          "refunds" : {
            "$ref" : "#/components/schemas/Link"
          },
          "self" : {
            "$ref" : "#/components/schemas/Link"
          }
        }
      },
      "PaymentLinksForEvents" : {
        "type" : "object",
        "description" : "links for events resource",
        "properties" : {
          "self" : {
            "$ref" : "#/components/schemas/Link"
          }
        }
      },
      "PaymentLinksForSearch" : {
        "type" : "object",
        "description" : "links for search payment resource",
        "properties" : {
          "cancel" : {
            "$ref" : "#/components/schemas/PostLink"
          },
          "capture" : {
            "$ref" : "#/components/schemas/PostLink"
          },
          "events" : {
            "$ref" : "#/components/schemas/Link"
          },
          "refunds" : {
            "$ref" : "#/components/schemas/Link"
          },
          "self" : {
            "$ref" : "#/components/schemas/Link"
          }
        }
      },
      "PaymentRefundRequest" : {
        "type" : "object",
        "description" : "The Payment Refund Request Payload",
        "properties" : {
          "amount" : {
            "type" : "integer",
            "format" : "int32",
            "description" : "The amount you want to [refund to your user](https://docs.payments.service.gov.uk/refunding_payments/) in pence.",
            "example" : 150000,
            "maximum" : 10000000,
            "minimum" : 1
          },
          "refund_amount_available" : {
            "type" : "integer",
            "format" : "int32",
            "description" : "Amount in pence. Total amount still available before issuing the refund",
            "example" : 200000,
            "maximum" : 10000000,
            "minimum" : 1
          }
        },
        "required" : [ "amount" ]
      },
      "PaymentSearchResults" : {
        "type" : "object",
        "properties" : {
          "_links" : {
            "$ref" : "#/components/schemas/SearchNavigationLinks"
          },
          "count" : {
            "type" : "integer",
            "format" : "int32",
            "description" : "Number of payments on the current page of search results.",
            "example" : 20
          },
          "page" : {
            "type" : "integer",
            "format" : "int32",
            "description" : "The [page of results you’re viewing](https://docs.payments.service.gov.uk/api_reference/#pagination). To view other pages, make this request again using the `page` parameter.",
            "example" : 1
          },
          "results" : {
            "type" : "array",
            "description" : "Contains payments matching your search criteria.",
            "items" : {
              "$ref" : "#/components/schemas/PaymentDetailForSearch"
            }
          },
          "total" : {
            "type" : "integer",
            "format" : "int32",
            "description" : "Total number of payments matching your search criteria.",
            "example" : 100
          }
        }
      },
      "PaymentSettlementSummary" : {
        "type" : "object",
        "description" : "A structure representing information about a settlement",
        "properties" : {
          "capture_submit_time" : {
            "type" : "string",
            "description" : "The date and time GOV.UK Pay asked your payment service provider to take the payment from your user’s account. This value uses Coordinated Universal Time (UTC) and ISO 8601 format - `YYYY-MM-DDThh:mm:ss.SSSZ`",
            "example" : "2016-01-21T17:15:00.000Z",
            "readOnly" : true
          },
          "captured_date" : {
            "type" : "string",
            "description" : "The date your payment service provider took the payment from your user. This value uses ISO 8601 format - `YYYY-MM-DD`",
            "example" : "2016-01-21",
            "readOnly" : true
          },
          "settled_date" : {
            "type" : "string",
            "description" : "The date that the transaction was paid into the service's account.",
            "example" : "2016-01-21",
            "readOnly" : true
          }
        }
      },
      "PaymentState" : {
        "type" : "object",
        "description" : "A structure representing the current state of the payment in its lifecycle.",
        "properties" : {
          "can_retry" : {
            "type" : "boolean",
            "description" : "If `can_retry` is `true`, you can use this agreement to try to take another recurring payment. If `can_retry` is `false`, you cannot take another recurring payment with this agreement. `can_retry` only appears on failed payments that were attempted using an agreement for recurring payments.",
            "nullable" : true,
            "readOnly" : true
          },
          "code" : {
            "type" : "string",
            "description" : "An [API error code](https://docs.payments.service.gov.uk/api_reference/#gov-uk-pay-api-error-codes)that explains why the payment failed. `code` only appears if the payment failed.",
            "example" : "P010",
            "readOnly" : true
          },
          "finished" : {
            "type" : "boolean",
            "description" : "Indicates whether a payment journey is finished.",
            "readOnly" : true
          },
          "message" : {
            "type" : "string",
            "description" : "A description of what went wrong with this payment. `message` only appears if the payment failed.",
            "example" : "User cancelled the payment",
            "readOnly" : true
          },
          "status" : {
            "type" : "string",
            "description" : "Where the payment is in [the payment status lifecycle](https://docs.payments.service.gov.uk/api_reference/#payment-status-meanings).",
            "example" : "created",
            "readOnly" : true
          }
        }
      },
      "PaymentWithAllLinks" : {
        "type" : "object",
        "properties" : {
          "_links" : {
            "$ref" : "#/components/schemas/PaymentLinks"
          },
          "amount" : {
            "type" : "integer",
            "format" : "int64",
            "description" : "The description assigned to the payment when it was created.",
            "example" : 1200
          },
          "authorisation_mode" : {
            "type" : "string",
            "description" : "How the payment will be authorised. Payments created in `web` mode require the paying user to visit the `next_url` to complete the payment.",
            "enum" : [ "web", "moto_api", "external" ]
          },
          "authorisation_summary" : {
            "$ref" : "#/components/schemas/AuthorisationSummary"
          },
          "card_brand" : {
            "type" : "string",
            "deprecated" : true,
            "description" : "This attribute is deprecated. Please use `card_details.card_brand` instead.",
            "example" : "Visa",
            "readOnly" : true
          },
          "card_details" : {
            "$ref" : "#/components/schemas/CardDetails"
          },
          "corporate_card_surcharge" : {
            "type" : "integer",
            "format" : "int64",
            "description" : "The [corporate card surcharge](https://docs.payments.service.gov.uk/corporate_card_surcharges/#add-corporate-card-fees) amount in pence.",
            "example" : 250,
            "readOnly" : true
          },
          "created_date" : {
            "type" : "string",
            "example" : "2016-01-21T17:15:00.000Z",
            "readOnly" : true
          },
          "delayed_capture" : {
            "type" : "boolean",
            "description" : "`delayed_capture` is `true` if you’re [controlling how long it takes GOV.UK Pay to take (‘capture’) a payment](https://docs.payments.service.gov.uk/delayed_capture).",
            "example" : false,
            "readOnly" : true
          },
          "description" : {
            "type" : "string",
            "description" : "The description assigned to the payment when it was created.",
            "example" : "Your Service Description"
          },
          "email" : {
            "type" : "string",
            "example" : "The paying user’s email address."
          },
          "exemption" : {
            "$ref" : "#/components/schemas/Exemption"
          },
          "fee" : {
            "type" : "integer",
            "format" : "int64",
            "description" : "The [payment service provider’s (PSP) transaction fee](https://docs.payments.service.gov.uk/reporting/#psp-fees), in pence. `fee` only appears when we have taken (‘captured’) the payment from the user or if their payment fails after they submitted their card details. `fee` will not appear if your PSP is Worldpay or you are using an API key from a test service.",
            "example" : 5,
            "readOnly" : true
          },
          "language" : {
            "type" : "string",
            "description" : "The ISO-6391 Alpha-2 code of the [language of the user's payment page](https://docs.payments.service.gov.uk/optional_features/welsh_language).",
            "enum" : [ "en", "cy" ],
            "example" : "en"
          },
          "metadata" : {
            "$ref" : "#/components/schemas/ExternalMetadata"
          },
          "moto" : {
            "type" : "boolean",
            "description" : "Indicates if this payment is a [Mail Order / Telephone Order (MOTO) payment](https://docs.payments.service.gov.uk/moto_payments).",
            "example" : false
          },
          "net_amount" : {
            "type" : "integer",
            "format" : "int64",
            "description" : "The amount, in pence, that will be paid into your bank account after your payment service provider takes the `fee`.",
            "example" : 1195,
            "readOnly" : true
          },
          "payment_id" : {
            "type" : "string",
            "description" : "The unique ID GOV.UK Pay automatically associated with this payment when you created it.",
            "example" : "hu20sqlact5260q2nanm0q8u93",
            "readOnly" : true
          },
          "payment_provider" : {
            "type" : "string",
            "description" : "The payment service provider that processed this payment.",
            "example" : "worldpay",
            "readOnly" : true
          },
          "provider_id" : {
            "type" : "string",
            "description" : "The unique ID your payment service provider generated for this payment. This is not the same as the `payment_id`.",
            "example" : "reference-from-payment-gateway",
            "readOnly" : true
          },
          "reference" : {
            "type" : "string",
            "description" : "The reference associated with the payment when it was created. `reference` is not unique - multiple payments can have the same `reference` value.",
            "example" : "your-reference"
          },
          "refund_summary" : {
            "$ref" : "#/components/schemas/RefundSummary"
          },
          "return_url" : {
            "type" : "string",
            "description" : "The URL you direct the paying user to after their payment journey on GOV.UK Pay ends.",
            "example" : "http://your.service.domain/your-reference",
            "readOnly" : true
          },
          "settlement_summary" : {
            "$ref" : "#/components/schemas/PaymentSettlementSummary"
          },
          "state" : {
            "$ref" : "#/components/schemas/PaymentState"
          },
          "total_amount" : {
            "type" : "integer",
            "format" : "int64",
            "description" : "Amount your user paid in pence, including corporate card fees. `total_amount` only appears if you [added a corporate card surcharge to the payment](https://docs.payments.service.gov.uk/corporate_card_surcharges/#add-corporate-card-fees).",
            "example" : 1450,
            "readOnly" : true
          }
        }
      },
      "PostLink" : {
        "type" : "object",
        "description" : "A POST link related to a payment",
        "properties" : {
          "href" : {
            "type" : "string",
            "description" : "A URL that lets you perform additional actions to this payment when combined with the associated `method`.",
            "example" : "https://an.example.link/from/payment/platform",
            "readOnly" : true
          },
          "method" : {
            "type" : "string",
            "example" : "POST",
            "readOnly" : true
          },
          "params" : {
            "type" : "object",
            "additionalProperties" : {
              "type" : "object",
              "example" : {
                "description" : "This is a value for a parameter called description"
              }
            },
            "example" : {
              "description" : "This is a value for a parameter called description"
            }
          },
          "type" : {
            "type" : "string",
            "example" : "application/x-www-form-urlencoded"
          }
        }
      },
      "PrefilledCardholderDetails" : {
        "type" : "object",
        "description" : "prefilled_cardholder_details",
        "properties" : {
          "billing_address" : {
            "$ref" : "#/components/schemas/Address"
          },
          "cardholder_name" : {
            "type" : "string",
            "description" : "The cardholder name you prefilled when you created this payment.",
            "example" : "J. Bogs",
            "maxLength" : 255,
            "minLength" : 0
          }
        }
      },
      "Refund" : {
        "type" : "object",
        "properties" : {
          "_links" : {
            "$ref" : "#/components/schemas/RefundLinksForSearch"
          },
          "amount" : {
            "type" : "integer",
            "format" : "int64",
            "description" : "The amount refunded to the user in pence.",
            "example" : 120,
            "readOnly" : true
          },
          "created_date" : {
            "type" : "string",
            "description" : "The date and time you created this refund. This value uses Coordinated Universal Time (UTC) and ISO 8601 format - `YYYY-MM-DDThh:mm:ss.SSSZ`.",
            "example" : "2017-01-10T16:52:07.855Z",
            "readOnly" : true
          },
          "payment_id" : {
            "type" : "string",
            "description" : "The unique ID GOV.UK Pay automatically associated with this payment when you created it.",
            "example" : "hu20sqlact5260q2nanm0q8u93",
            "readOnly" : true
          },
          "refund_id" : {
            "type" : "string",
            "description" : "The unique ID GOV.UK Pay automatically associated with this refund when you created it.",
            "example" : "act4c33g40j3edfmi8jknab84x",
            "readOnly" : true
          },
          "settlement_summary" : {
            "$ref" : "#/components/schemas/RefundSettlementSummary"
          },
          "status" : {
            "type" : "string",
            "description" : "The [status of the refund](https://docs.payments.service.gov.uk/refunding_payments/#checking-the-status-of-a-refund-status).",
            "enum" : [ "submitted", "success", "error" ],
            "example" : "success",
            "readOnly" : true
          }
        }
      },
      "RefundDetailForSearch" : {
        "type" : "object",
        "description" : "Contains the refunds matching your search criteria.",
        "properties" : {
          "_links" : {
            "$ref" : "#/components/schemas/RefundLinksForSearch"
          },
          "amount" : {
            "type" : "integer",
            "format" : "int64",
            "description" : "The amount refunded to the user in pence.",
            "example" : 120,
            "readOnly" : true
          },
          "created_date" : {
            "type" : "string",
            "description" : "The date and time you created this refund. This value uses Coordinated Universal Time (UTC) and ISO 8601 format - `YYYY-MM-DDThh:mm:ss.SSSZ`.",
            "example" : "2017-01-10T16:52:07.855Z",
            "readOnly" : true
          },
          "payment_id" : {
            "type" : "string",
            "description" : "The unique ID GOV.UK Pay automatically associated with this payment when you created it.",
            "example" : "hu20sqlact5260q2nanm0q8u93",
            "readOnly" : true
          },
          "refund_id" : {
            "type" : "string",
            "description" : "The unique ID GOV.UK Pay automatically associated with this refund when you created it.",
            "example" : "act4c33g40j3edfmi8jknab84x",
            "readOnly" : true
          },
          "settlement_summary" : {
            "$ref" : "#/components/schemas/RefundSettlementSummary"
          },
          "status" : {
            "type" : "string",
            "description" : "The [status of the refund](https://docs.payments.service.gov.uk/refunding_payments/#checking-the-status-of-a-refund-status).",
            "enum" : [ "submitted", "success", "error" ],
            "example" : "success",
            "readOnly" : true
          }
        }
      },
      "RefundForSearchResult" : {
        "type" : "object",
        "properties" : {
          "_embedded" : {
            "$ref" : "#/components/schemas/EmbeddedRefunds"
          },
          "_links" : {
            "$ref" : "#/components/schemas/RefundLinksForSearch"
          },
          "payment_id" : {
            "type" : "string",
            "description" : "The unique ID GOV.UK Pay associated with this payment when you created it.",
            "example" : "hu20sqlact5260q2nanm0q8u93"
          }
        }
      },
      "RefundLinksForSearch" : {
        "type" : "object",
        "description" : "links for search refunds resource",
        "properties" : {
          "payment" : {
            "$ref" : "#/components/schemas/Link"
          },
          "self" : {
            "$ref" : "#/components/schemas/Link"
          }
        }
      },
      "RefundSearchResults" : {
        "type" : "object",
        "properties" : {
          "_links" : {
            "$ref" : "#/components/schemas/SearchNavigationLinks"
          },
          "count" : {
            "type" : "integer",
            "format" : "int32",
            "description" : "Number of refunds on the current page of search results.",
            "example" : 20
          },
          "page" : {
            "type" : "integer",
            "format" : "int32",
            "description" : "The [page of results](payments.service.gov.uk/api_reference/#pagination) you’re viewing. To view other pages, make this request again using the `page` parameter.",
            "example" : 1
          },
          "results" : {
            "type" : "array",
            "description" : "Contains the refunds matching your search criteria.",
            "items" : {
              "$ref" : "#/components/schemas/RefundDetailForSearch"
            }
          },
          "total" : {
            "type" : "integer",
            "format" : "int32",
            "description" : "Number of refunds matching your search criteria.",
            "example" : 100
          }
        }
      },
      "RefundSettlementSummary" : {
        "type" : "object",
        "description" : "A structure representing information about a settlement for refunds",
        "properties" : {
          "settled_date" : {
            "type" : "string",
            "description" : "The date Stripe took the refund from a payout to your bank account. `settled_date` only appears if Stripe has taken the refund. This value uses Coordinated Universal Time (UTC) and ISO 8601 format - `YYYY-MM-DD`.",
            "example" : "2016-01-21",
            "readOnly" : true
          }
        },
        "readOnly" : true
      },
      "RefundSummary" : {
        "type" : "object",
        "description" : "A structure representing the refunds availability",
        "properties" : {
          "amount_available" : {
            "type" : "integer",
            "format" : "int64",
            "description" : "How much you can refund to the user, in pence.",
            "example" : 100,
            "readOnly" : true
          },
          "amount_submitted" : {
            "type" : "integer",
            "format" : "int64",
            "description" : "How much you’ve already refunded to the user, in pence.",
            "readOnly" : true
          },
          "status" : {
            "type" : "string",
            "description" : "Whether you can [refund the payment](https://docs.payments.service.gov.uk/refunding_payments/#checking-the-status-of-a-refund-status).",
            "example" : "available"
          }
        }
      },
      "RefundsResponse" : {
        "type" : "object",
        "properties" : {
          "_links" : {
            "$ref" : "#/components/schemas/RefundLinksForSearch"
          },
          "payment_id" : {
            "type" : "string",
            "description" : "The unique ID GOV.UK Pay associated with this payment when you created it.",
            "example" : "hu20sqlact5260q2nanm0q8u93"
          }
        }
      },
      "RequestError" : {
        "type" : "object",
        "description" : "A Request Error response",
        "properties" : {
          "code" : {
            "type" : "string",
            "description" : "An [API error code](https://docs.payments.service.gov.uk/api_reference/#gov-uk-pay-api-error-codes)that explains why the payment failed.<br><br>`code` only appears if the payment failed.",
            "example" : "P0102"
          },
          "description" : {
            "type" : "string",
            "description" : "Additional details about the error.",
            "example" : "Invalid attribute value: amount. Must be less than or equal to 10000000"
          },
          "field" : {
            "type" : "string",
            "description" : "The parameter in your request that's causing the error.",
            "example" : "amount"
          },
          "header" : {
            "type" : "string",
            "description" : "The header in your request that's causing the error.",
            "example" : "Idempotency-Key"
          }
        }
      },
      "SearchNavigationLinks" : {
        "type" : "object",
        "description" : "Links to navigate through pages of your search.",
        "properties" : {
          "first_page" : {
            "$ref" : "#/components/schemas/Link"
          },
          "last_page" : {
            "$ref" : "#/components/schemas/Link"
          },
          "next_page" : {
            "$ref" : "#/components/schemas/Link"
          },
          "prev_page" : {
            "$ref" : "#/components/schemas/Link"
          },
          "self" : {
            "$ref" : "#/components/schemas/Link"
          }
        }
      },
      "SettlementSummary" : {
        "type" : "object",
        "description" : "Contains information about when a lost dispute was settled. A dispute is settled when your payment service provider takes it from a payout to your bank account. 'settlement_summary' only appears if you lost the dispute.",
        "properties" : {
          "settled_date" : {
            "type" : "string",
            "description" : "The date your payment service provider took the disputed payment and dispute fee from a payout to your bank account. This value appears in ISO 8601 format - `YYYY-MM-DD`. `settled_date` only appears if you lost the dispute.",
            "example" : "2022-07-28",
            "readOnly" : true
          }
        }
      },
      "ThreeDSecure" : {
        "type" : "object",
        "description" : "Object containing information about the 3D Secure authentication of the payment.",
        "properties" : {
          "required" : {
            "type" : "boolean",
            "description" : "Indicates if this payment was authorised with 3D Secure authentication. `required` is `true` if the payment required 3D Secure authentication."
          }
        }
      }
    },
    "securitySchemes" : {
      "BearerAuth" : {
        "description" : "GOV.UK Pay authenticates API calls with [OAuth2 HTTP bearer tokens](http://tools.ietf.org/html/rfc6750). You need to use an `\"Authorization\"` HTTP header to provide your API key, with a `\"Bearer\"` prefix. For example: `Authorization: Bearer {YOUR_API_KEY_HERE}`",
        "scheme" : "bearer",
        "type" : "http"
      }
    }
  }
}