Three lines



API Reference - Cancel Deposit

Cancel deposit

Cancel the deposit draft order to make it unusable for any further state changes. Should be called only after a successful update-deposit call. Make your request at this endpoint:

POST /v1/payments/deposits/:id/cancel


OAuth 2.0 bearer token with the payments.deposits scope.

Path parameters

Name Type Description
id UUID Deposit ID

Request headers

Name Type Description
X-Idempotency-Key String See the idempotency section.

Body parameters

Name Type Description
cancel_reason Enum Reason string stored along with deposit object. Options are
  • BANK_SOFT_ERROR The user should contact their bank to resolve the error. The payment can be retried later on.

  • INSUFFICIENT_BALANCE The transaction failed because of insufficient balance.

  • PAYMENT_FRAUD_ERROR Generic error for fraud related issues.

  • PAYMENT_NETWORK_ERROR Generic network error for payments.

  • PAYMENT_PSP_ERROR The PSP is currently not able to process the transaction. The transaction should be retried.

  • VALIDATION_ERROR The payment request is invalid.

  • BANK_HARD_ERROR This transaction failed and it should not be retried. The user needs to check with their bank to find out why.

  • PAYMENT_PSP_HARD_DECLINE_ERROR This error indicates a hard failure in the PSP side. It should not be retried.

  • INSTRUMENT_EXPIRED_HARD_ERROR User’s payment instrument is expired. It needs to be fixed before the payment method can be used for future transaction.

  • INVALID_PAYMENT_DETAILS_ERROR Payment info provided by the user is rejected by the provider.

  • USER_CANCELLED User cancels during payment initiation flow.

  • MERCHANT_EXPIRED User did not pay after a specific period.

  • MERCHANT_REJECTED Partner refuses to process.

  • PAYMENT_ERROR Generic payment error. This should not be used unless there is not any more specific error that can be used.

Example request and response

Example request

The following is an example request for the cancel deposit resource. To use this request, replace $token in the example below with the access token.

curl -X POST \
  "" \
  -H "Authorization: Bearer $token" \
  -H 'X-Idempotency-Key: 3dad6604-c805-4153-9286-b58dca9b6ca7-cancel' \
  -H 'Content-Type: application/json' \
  -d '{
    "cancel_reason": "USER_CANCELLED"

This is an example of what you can expect to see in response:

	"deposit": {
		"id": "b6118d57-2106-3873-094c-2e7a4ab9f967",
		"destination": {
			"id": "cHBfYjA3NDA5MzItYzI2Mi00MTk5LThkZGItY2Y2NGRhMTU0OWQ4",
			"owner_id": "e00905e1-066d-4c44-bd9d-ea8fd7d7be8e",
			"type": "Account",
			"uri": "//payments/customers/e00905e1-066d-4c44-bd9d-ea8fd7d7be8e/accounts/cHBfYjA3NDA5MzItYzI2Mi00MTk5LThkZGItY2Y2NGRhMTU0OWQ4"
		"source": {
			"id": "Z3NfZjNmMmU2MDYtMjYzYS0zMzY2LThjOWMtMmQ0MGU1ODE2ZWZj",
			"owner_id": "a7b46663-3b97-40be-9b3e-ab805a56b269",
			"type": "Account",
			"uri": "//payments/customers/a7b46663-3b97-40be-9b3e-ab805a56b269/accounts/Z3NfZjNmMmU2MDYtMjYzYS0zMzY2LThjOWMtMmQ0MGU1ODE2ZWZj"
		"state": {
			"value": "CANCELLED",
			"detail": "USER_CANCELLED"
		"amount": {
			"value": 1000000,
			"currency": "EUR"
		"description": "",
		"country_iso2": "NL",
		"session_id": "36adcbfd-15fc-45e6-bd51-0f2a52c17c93",
		"funding_method": "TEST_FUNDING_METHOD",
		"type": "Deposit",
		"uri": "//payments/deposits/b6118d57-2106-3873-094c-2e7a4ab9f967"

Cancel deposit errors

HTTP status code URL sample Scenario
200{{VALID_DEPOSIT_UUID}}/cancel Valid DRAFT deposit
409{{PREVIOUSLY_CONFIRMED_DEPOSIT_UUID}}/cancel Confirmed deposit
404{{NON_EXISTING_DEPOSIT_UUID}}/cancel Non-existing deposit
400 Invalid Deposit UUID
403{{UNAUTHORIZED_DEPOSIT_UUID}}/cancel Unauthorized Deposit
Cancel deposit header errors
HTTP status code URL sample Headers scenario
200{{VALID_UUID}}/cancel X-Idempotency-Key: Valid ID 1 Try to cancel twice using different Idempotency keys
409{{VALID_UUID}}/cancel X-Idempotency-Key: Valid ID 2


© 2023 Uber Technologies Inc.