---
title: "Update a payment"
method: PUT
path: "/payments/{payment_id}"
tags: ["Payment"]
---

# Update a payment

`PUT /payments/{payment_id}`

## Request

- Base URL: `https://api.gocardless.com`
- URL: `https://api.gocardless.com/payments/{payment_id}`
- Auth: HTTP bearer

Updates a payment object. This accepts only the metadata parameter.

## Path parameters

- `payment_id` string, required

## Headers

- `GoCardless-Version` string, required

## Request body

- object
  - `payments` object
    - `retry_if_possible` boolean: On failure, automatically retry the payment using [intelligent retries](https://docs.gocardless.com/docs/optimise/reduced-failed-payments-with-success-plus). Default is `false`. <p class="notice"><strong>Important</strong>: To be able to use intelligent retries, Success+ needs to be enabled in [GoCardless dashboard](https://manage.gocardless.com/success-plus). </p>
    - `metadata` CustomerMetadata: Key-value store of custom data. Up to 3 keys are permitted, with key names up to 50 characters and values up to 500 characters.

## Response `200`

Successful response

- PaymentSingleResourceResponse
  - `payments` Payment: Payment objects represent payments from a [customer](https://docs.gocardless.com/docs/api-reference/customer) to a [creditor](https://docs.gocardless.com/docs/api-reference/creditor), taken against a Direct Debit [mandate](https://docs.gocardless.com/docs/api-reference/mandate). GoCardless will notify you via a [webhook](https://docs.gocardless.com/docs/api-reference/webhooks) whenever the state of a payment changes.
    - `id` string, required: Unique identifier, beginning with "PM".
    - `created_at` string, date-time, required: Fixed [timestamp](https://docs.gocardless.com/docs/api-reference/data-conventions#dates-and-times), recording when this resource was created.
    - `amount` integer, required: Amount, in the lowest denomination for the currency (e.g. pence in GBP, cents in EUR). Minimum and maximum amounts vary by payment scheme. For more information, see [Transaction limits](https://support.gocardless.com/hc/en-gb/articles/115000309245-Transaction-limits) For Variable Recurring Payments (VRP), this must not exceed the mandate's `max_amount_per_payment` constraint.
    - `amount_refunded` integer, required: Amount [refunded](https://docs.gocardless.com/docs/api-reference/refund), in the lowest denomination for the currency (e.g. pence in GBP, cents in EUR).
    - `currency` 'AUD' | 'CAD' | 'DKK' | 'EUR' | 'GBP' | 'NZD' | 'SEK' | 'USD', required: [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217#Active_codes) currency code. Currently "AUD", "CAD", "DKK", "EUR", "GBP", "NZD", "SEK" and "USD" are supported.
    - `description` string, nullable, required: A human-readable description of the payment. This will be included in the notification email GoCardless sends to your customer if your organisation does not send its own notifications (see [compliance requirements](https://docs.gocardless.com/docs/api-reference/compliance-requirements)).
    - `charge_date` string, date, nullable, required: A future date on which the payment should be collected. If not specified, the payment will be collected as soon as possible. If the value is before the [mandate](https://docs.gocardless.com/docs/api-reference/mandate)'s `next_possible_charge_date` creation will fail. If the value is not a working day it will be rolled forwards to the next available one.
    - `reference` string, nullable, required: An optional reference that will appear on your customer's bank statement. The character limit for this reference is dependent on the scheme.<br /> <strong>ACH</strong> - 10 characters<br /> <strong>Autogiro</strong> - 11 characters<br /> <strong>Bacs</strong> - 10 characters<br /> <strong>BECS</strong> - 30 characters<br /> <strong>BECS NZ</strong> - 12 characters<br /> <strong>Betalingsservice</strong> - 30 characters<br /> <strong>Faster Payments</strong> - 18 characters<br /> <strong>PAD</strong> - scheme doesn't offer references<br /> <strong>PayTo</strong> - 18 characters<br /> <strong>SEPA</strong> - 140 characters<br /> Note that this reference must be unique (for each merchant) for the BECS scheme as it is a scheme requirement. <p class='restricted-notice'><strong>Restricted</strong>: You can only specify a payment reference for Bacs payments (that is, when collecting from the UK) if you're on the <a href='https://gocardless.com/pricing'>GoCardless Plus, Pro or Enterprise packages</a>.</p> <p class='restricted-notice'><strong>Restricted</strong>: You can not specify a payment reference for Faster Payments.</p>
    - `metadata` CustomerMetadata, required: Key-value store of custom data. Up to 3 keys are permitted, with key names up to 50 characters and values up to 500 characters.
    - `status` 'pending_customer_approval' | 'pending_submission' | 'submitted' | 'confirmed' | 'paid_out' | 'cancelled' | 'customer_approval_denied' | 'failed' | 'charged_back', required: One of: - `pending_customer_approval`: we're waiting for the customer to approve this payment - `pending_submission`: the payment has been created, but not yet submitted to the banks - `submitted`: the payment has been submitted to the banks - `confirmed`: the payment has been confirmed as collected - `paid_out`: the payment has been included in a [payout](https://docs.gocardless.com/docs/api-reference/payout) - `cancelled`: the payment has been cancelled - `customer_approval_denied`: the customer has denied approval for the payment. You should contact the customer directly - `failed`: the payment failed to be processed. Note that payments can fail after being confirmed if the failure message is sent late by the banks. - `charged_back`: the payment has been charged back
    - `app_fee` integer, nullable: The amount to be deducted from the payment as the OAuth app''s fee, in the lowest denomination for the currency (e.g. pence in GBP, cents in EUR). Only present if the payment was created via an app.
    - `links` PaymentLinks, required
      - `mandate` string: ID of the [mandate](https://docs.gocardless.com/docs/api-reference/mandate) against which this payment should be collected.
      - `creditor` string: ID of [creditor](https://docs.gocardless.com/docs/api-reference/creditor) to which the collected payment will be sent.
      - `payout` string: ID of [payout](https://docs.gocardless.com/docs/api-reference/payout) which contains the funds from this payment.<br/>_Note_: this property will not be present until the payment has been successfully collected.
      - `subscription` string: ID of [subscription](https://docs.gocardless.com/docs/api-reference/subscription) from which this payment was created.<br/>_Note_: this property will only be present if this payment is part of a subscription.
      - `instalment_schedule` string: ID of [instalment_schedule](https://docs.gocardless.com/docs/api-reference/instalment-schedule) from which this payment was created.<br/>**Note**: this property will only be present if this payment is part of an instalment schedule.
    - `faster_ach` boolean, nullable: This field indicates whether the ACH payment is processed through Faster ACH or standard ACH. It is only present in the API response for ACH payments.
    - `fx` PaymentFx, required
      - `exchange_rate` string, nullable: Rate used in the foreign exchange of the `amount` into the `fx_currency`. Present only after a resource is paid out. Has up to 10 decimal places.
      - `estimated_exchange_rate` string, nullable: Estimated rate that will be used in the foreign exchange of the `amount` into the `fx_currency`. This will vary based on the prevailing market rate until the moment that it is paid out. Present only before a resource is paid out. Has up to 10 decimal places.
      - `fx_amount` union: Amount that was paid out in the `fx_currency` after foreign exchange. Present only after the resource has been paid out.
        - string, nullable
        - integer
      - `fx_currency` 'AUD' | 'CAD' | 'DKK' | 'EUR' | 'GBP' | 'NZD' | 'SEK' | 'USD', nullable: [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217#Active_codes) code for the currency in which amounts will be paid out (after foreign exchange). Currently "AUD", "CAD", "DKK", "EUR", "GBP", "NZD", "SEK" and "USD" are supported. Present only if payouts will be (or were) made via foreign exchange.
    - `retry_if_possible` boolean, required: On failure, automatically retry the payment using [intelligent retries](https://docs.gocardless.com/docs/optimise/reduced-failed-payments-with-success-plus). Default is `false`. <p class="notice"><strong>Important</strong>: To be able to use intelligent retries, Success+ needs to be enabled in [GoCardless dashboard](https://manage.gocardless.com/success-plus). </p>
    - `scheme` string, nullable, required: A bank payment scheme. Currently "ach", "autogiro", "bacs", "becs", "becs_nz", "betalingsservice", "faster_payments", "pad", "pay_to", "sepa_core", "sepa_credit_transfer" and "sepa_instant_credit_transfer" are supported.

## Other responses

- `400`: Bad Request
- `401`: Unauthorised
- `404`: Not found
- `422`: Validation Error
- `500`: Internal Error

---

[API](https://skmtc.dev/gocardless/apis/gocardless-api.md) - [All operations](https://skmtc.dev/gocardless/apis/gocardless-api/llms.txt) - [OpenAPI document](https://skmtc.dev/gocardless/apis/gocardless-api/revisions/4dd3dae45364?raw)