Refund a payment

POST/v1/payments/{paymentId}/refunds

You can use this endpoint to fully or partially refund a payment.

Requires a bearer token.

In this mock: Returns 202 with the refund in submitted state. The payment must be in success. Errors: P0601/P0602 (400), P0603/P0604 (412).

Path parameters

Name	Type	Description
paymentId required	string	The unique payment_id of the payment you want to refund.

Request body

Name	Type	Description
amount required	integer	The amount you want to refund to your user in pence.
refund_amount_available	integer	Amount in pence. Total amount still available before issuing the refund

Example request

curl -X POST "https://publicapi.payments.platform-engineering.com/v1/payments/{paymentId}/refunds" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "amount": 150000
}'

Responses

200: successful operation

Name	Type	Description
_links	object	links for search refunds resource
_links.payment	object	A link related to a payment
_links.payment.href	string	A URL that lets you perform additional actions to this payment when combined with the associated method.
_links.payment.method	string	An API method that lets you perform additional actions to this paymentwhen combined with the associated href.
_links.self	object	A link related to a payment
_links.self.href	string	A URL that lets you perform additional actions to this payment when combined with the associated method.
_links.self.method	string	An API method that lets you perform additional actions to this paymentwhen combined with the associated href.
amount	integer	The amount refunded to the user in pence.
created_date	string	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.
payment_id	string	The unique ID GOV.UK Pay automatically associated with this payment when you created it.
refund_id	string	The unique ID GOV.UK Pay automatically associated with this refund when you created it.
settlement_summary	object	A structure representing information about a settlement for refunds
settlement_summary.settled_date	string	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.
status	string	The status of the refund. One of: submitted, success, error

{
  "_links": {
    "payment": {
      "href": "https://an.example.link/from/payment/platform",
      "method": "GET"
    },
    "self": {
      "href": "https://an.example.link/from/payment/platform",
      "method": "GET"
    }
  },
  "amount": 120,
  "created_date": "2017-01-10T16:52:07.855Z",
  "payment_id": "hu20sqlact5260q2nanm0q8u93",
  "refund_id": "act4c33g40j3edfmi8jknab84x",
  "settlement_summary": {
    "settled_date": "2016-01-21"
  },
  "status": "success"
}

202: ACCEPTED

401: 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: Not found

Name	Type	Description
code	string	An API error codethat explains why the payment failed.<br><br>code only appears if the payment failed.
description	string	Additional details about the error.
field	string	The parameter in your request that's causing the error.
header	string	The header in your request that's causing the error.

{
  "code": "P0102",
  "description": "Invalid attribute value: amount. Must be less than or equal to 10000000",
  "field": "amount",
  "header": "Idempotency-Key"
}

412: Refund amount available mismatch

429: Too many requests

Name	Type	Description
code	string	A GOV.UK Pay API error code. You can find out more about this code in our documentation.
description	string	Additional details about the error

{
  "code": "P0900",
  "description": "Too many requests"
}

500: Downstream system error

Name	Type	Description
code	string	An API error codethat explains why the payment failed.<br><br>code only appears if the payment failed.
description	string	Additional details about the error.
field	string	The parameter in your request that's causing the error.
header	string	The header in your request that's causing the error.

{
  "code": "P0102",
  "description": "Invalid attribute value: amount. Must be less than or equal to 10000000",
  "field": "amount",
  "header": "Idempotency-Key"
}