Update a Payment
POST/v2/payments/:id
Update a Payment with the provided details. Only payments in open or requires_action state can be updated, except for metadata which can be updated in any state.
Request
Responses
- 200
- 202
- 400
- 401
- 403
- 404
- 409
- 429
- 500
- 503
- 504
OK
The merchant is entitled but its environment is not provisioned yet. Provisioning has been kicked off (exactly once) and is in progress; retry the request — it succeeds once the environment is ready. Returned only for identity-token (dashboard) requests bound to a merchant, not for secret-key API calls; any such endpoint can return it while provisioning is underway.
The request was rejected. type is invalid_request_error when the request itself is at fault — errors then lists every problem found, with field-attributable entries prefixed by the field’s path; or invalid_state_error when the request was well-formed but the resource is not in a state that allows it.
No API key was supplied, or the key is not valid. type is authentication_error.
The API key is valid but lacks the permission this operation requires. type is permission_error.
No resource exists with the requested identifier. type is not_found_error.
type is conflict_error. The supplied X-Idempotency-Key was already used with a different request body (code is idempotency_conflict, and retrying will not help), or the resource is being modified by another in-flight request (code is resource_locked, and retrying with backoff will).
Too many requests. A limit applies per operation; requests to other operations are unaffected. type is rate_limit_error. Use the Retry-After-global header to know when to retry.
Response Headers
Seconds to wait before retrying.
The request could not be completed because of an unexpected error. type is api_error.
The request could not be served right now: the API is temporarily at capacity, or a dependency needed to authorize the request is unavailable — the auth service that verifies credentials, or the entitlement lookup behind it. type is api_error. It is raised before the operation runs, so the request had no effect, and unlike a plain 500 the condition is transient: retry with backoff.
The request exceeded the processing time limit and was abandoned. type is api_error and code is timeout — unlike a plain 500 the request may still have taken effect, so retry with the same idempotency key rather than blindly.