Skip to content

Commit

Permalink
PP-12092: Updates recurring payments details (#946)
Browse files Browse the repository at this point in the history 
* Updates recurring payments details

* Changes based on 2i
  • Loading branch information
@NathanD-GDS
NathanD-GDS authored Jan 19, 2024
1 parent 5e4d816 commit a37d9f1
Show file tree
Hide file tree
Showing 3 changed files with 20 additions and 3 deletions.
1 change: 1 addition & 0 deletions source/api_reference/search_agreements_reference/index.html.md.erb
View file
Original file line number Diff line number Diff line change
Expand Up @@ -107,6 +107,7 @@ curl -X GET "https://publicapi.payments.service.gov.uk/v1/agreements?status=acti
| `status` | | The status of this agreement.<br><br>Possible values are:<br><br><li>`created`<br><li>`active`<br><li>`cancelled`<br><li>`inactive`<br><br>You can [read more about the meanings of each agreement `status`](/recurring_payments/#understanding-agreement-status). |
| `user_identifier` | string | An identifier to help you identify the user this agreement is with. |
| `created_date` | date (ISO 8601) | The date and time you created this agreement.<br><br>This value uses Coordinated Universal Time (UTC) and ISO 8601 format – `YYYY-MM-DDThh:mm:ss.sssZ`. |
| `cancelled_date` | date (ISO 8601) | The date and time you cancelled this agreement.<br><br>`cancelled_date` only appears on [cancelled agreements](/api_reference/cancel_agreement_reference).<br><br>This value uses Coordinated Universal Time (UTC) and ISO 8601 format – `YYYY-MM-DDThh:mm:ss.sssZ`. |
| `payment_instrument` | object | Contains information about the user’s saved payment details.<br><br>`payment_instrument` only appears if you have [set up the agreement by saving the user’s payment details](/recurring_payments/#set-up-an-agreement-for-recurring-payments). |
| `payment_instrument.type` | string | The payment method the user is making recurring payments with.<br><br>Currently, the only possible value is `card`. |
| `payment_instrument.card_details` | object | Contains information about the card the user is making recurring payments with. |
Expand Down
1 change: 1 addition & 0 deletions source/api_reference/single_agreement_reference/index.html.md.erb
View file
Original file line number Diff line number Diff line change
Expand Up @@ -85,6 +85,7 @@ After you send your request, you’ll receive a response similar to this example
| `status` | string | The status of this agreement.<br><br>Possible values are:<br><br><li>`created`<br><li>`active`<br><li>`cancelled`<br><li>`inactive`<br><br>You can [read more about the meanings of each agreement `status`](/recurring_payments/#understanding-agreement-status). |
| `user_identifier` | string | An identifier to help you identify the user this agreement is with. |
| `created_date` | date (ISO 8601) | The date and time you created this agreement.<br><br>This value uses Coordinated Universal Time (UTC) and ISO 8601 format – `YYYY-MM-DDThh:mm:ss.sssZ`. |
| `cancelled_date` | date (ISO 8601) | The date and time you cancelled this agreement.<br><br>`cancelled_date` only appears on [cancelled agreements](/api_reference/cancel_agreement_reference).<br><br>This value uses Coordinated Universal Time (UTC) and ISO 8601 format – `YYYY-MM-DDThh:mm:ss.sssZ`. |
| `payment_instrument` | object | Contains information about the user’s saved payment details.<br><br>`payment_instrument` only appears if you have [set up the agreement by saving the user’s payment details](/recurring_payments/#set-up-an-agreement-for-recurring-payments). |
| `payment_instrument.type` | string | The payment method the user is making recurring payments with.<br><br>Currently, the only possible value is `card`. |
| `payment_instrument.card_details` | object | Contains information about the card the user is making recurring payments with. |
Expand Down
21 changes: 18 additions & 3 deletions source/recurring_payments/index.html.md.erb
View file
Original file line number Diff line number Diff line change
Expand Up @@ -182,7 +182,9 @@ Read more about creating payments in [our guidance for taking payments](/making_

### Update a user’s recurring payment card details

You can update the card used to take recurring payments. This overrides the existing card details. You should do this if a user’s existing card is going to expire soon, or if a user tells you they want to pay with a different card.
You can update the card that GOV.UK Pay uses to take recurring payments from users. This overrides the existing card details. You should do this if a user’s existing card is going to expire soon, or if a user tells you they want to pay with a different card.

You could be charged failed payment fees if you try to take payments from an expired card.

To update the user’s card details, repeat [the process to set up an agreement](#set-up-an-agreement-for-recurring-payments) by creating a payment and adding `set_up_agreement: "{AGREEMENT_ID}"` to your API request body. Replace `"{AGREEMENT_ID}"` with the same `agreement_id` you sent when first setting up this agreement.

Expand Down Expand Up @@ -219,7 +221,7 @@ The API returns a standard create payment response. Successful responses include

GOV.UK Pay uses a token representing the user’s saved payment details from the agreement to take the payment.

Check the status of the payment through our API (`GET /v1/payments/{PAYMENT_ID}`) or by [using webhooks to get automatic payment event updates](/recurring_payments/#use-webhooks-to-receive-automatic-event-updates).
The payment enters the `submitted` status while we process it. You can check the status of the payment through our API (`GET /v1/payments/{PAYMENT_ID}`) or by [using webhooks to get automatic payment event updates](/recurring_payments/#use-webhooks-to-receive-automatic-event-updates).

If a recurring payment fails when we try to take it, it’s handled like any other failed payment. You can [read more about what you need to do when a recurring payment fails](#handling-failed-recurring-payments).

Expand Down Expand Up @@ -461,7 +463,20 @@ You can cancel an agreement for recurring payments at any time. You may want to

You must provide a way for your users to return to your service and cancel their recurring payments.

To cancel an agreement, use this endpoint:
You can cancel an agreement through the [GOV.UK Pay admin tool](https://selfservice.payments.service.gov.uk/my-services) or the API.

### Cancel an agreement through the GOV.UK Pay admin tool

1. Go to **Agreements**.
1. Select the agreement you want to cancel.
1. Select **Cancel this agreement**.
1. Select **Confirm cancellation**.

You can see who cancelled an agreement and when they cancelled it in **Agreement details**.

### Cancel an agreement through the API

To cancel an agreement through the API, use this endpoint:

`POST /v1/agreements/{AGREEMENT_ID}/cancel`

Expand Down

0 comments on commit a37d9f1

Please sign in to comment.