# Cancel a payment request

Cancel a payment request.

> 📘 Info
>
> You can only cancel a payment request when the status is in the initial state.

Endpoint: POST /payment_requests/{paymentRequestId}/cancel
Version: 1.0.0
Security: ApiKeyAuth, ApiKeySecret

## Path parameters:

  - `paymentRequestId` (string, required)
    The unique identifier created by Belvo used to reference the payment request.
    Example: "2e66d035-c78f-435c-a21d-b86d3e7b351d"

## Response 201 fields (application/json):

  - `id` (string)
    The unique identifier created by Belvo used to reference the payment request.
    Example: "0d1a377b-b4c5-4a94-9e2e-83e59d1f6a9c"

  - `createdDate` (string,null)
    The ISO-8601 timestamp when the payment request was created in Belvo's database.
    Example: "2022-02-09T08:45:50.406032Z"

  - `lastUpdatedDate` (string,null)
    The ISO-8601 timestamp when information regarding the payment request was last updated.
    Example: "2022-02-09T08:45:50.406032Z"

  - `chargebackDate` (string,null)
    The ISO-8601 timestamp when Belvo marked the payment request as chargeback. Only present when status is chargeback. Chargebacks recorded before bankChargebackDate was introduced hold the date reported by the financial institution here instead.
    Example: "2022-02-11T17:42:11.123Z"

  - `bankChargebackDate` (string,null)
    The date the financial institution reported for the chargeback, in YYYY-MM-DD format. Use it to reconcile against the financial institution's statements. null when the payment request is not a chargeback or was charged back before this field was introduced.
    Example: "2022-02-10"

  - `status` (string)
    The status of the payment request. Can be either:
  - initial
    The payment request has been created.
  - processing
    The charge files have been generated for the payment request. Awaiting response from the financial institution.
  - successful
    The financial institution has confirmed the payment request and the funds have been transferred.
  - failed
    The financial institution has reported an error for the payment request and no funds have been transferred.
  - canceled
    The request was canceled. This is only possible if the payment request has not transitioned to the processing status.
  - chargeback
    The financial institution reversed a payment request that was successful.
    Enum: "initial", "processing", "successful", "failed", "canceled", "chargeback"

  - `failedReason` (string,null)
    The financial institution's failure code.

  - `failedReasonMessage` (string,null)
    The financial institution's failure message, describing the reason for the failure.

  - `amount` (string)
    The amount to debit from the customer.
    Example: "100000.00"

  - `currency` (string)
    The three-letter ISO 4217 currency code of the transaction. At the moment, we only support mxn.
    Enum: "mxn"

  - `customer` (string)
    The unique identifier created by Belvo used to reference the customer.
    Example: "3118128a-6792-4b06-bd61-4acf6f6ad6b5"

  - `customerName` (string)
    The name of the customer.
    Example: "Carlos Vives"

  - `reference` (string)
    A reference for the payment request.
    Example: "Monthly gym subscription"

  - `paymentMethod` (object)

  - `paymentMethod.type` (string)
    The type of account. For Mexico, this value is set to bank_account.
    Enum: "bank_account"

  - `paymentMethod.details` (object)
    Details regarding the bank account associated with the payment method.

  - `paymentMethod.details.accountNumber` (string)
    The bank account number.
    Example: "445566790"

  - `paymentMethod.details.accountType` (string)
    The bank account type. Can be either:
  - savings
  - checking
  - debit_card
    Enum: "savings", "checking", "debit_card"

  - `paymentMethod.details.bank` (string)
    The name of the Mexican bank where the account is held.


For a full list of institutions, please see our dedicated Payment Institutions page.

  - `loanInformation` (object)
    (Optinal) Metadata about the loan associated with the payment request.

  - `loanInformation.reference` (string)
    Your reference for the loan associated with the payment request.
    Example: "Camera Purchase 1432"

  - `loanInformation.disbursementDate` (string)
    The date when the loan was disbursed, in YYYY-MM-DD format.
    Example: "2025-01-01"

  - `loanInformation.installmentNumber` (integer)
    The number of the installment being paid.
    Example: 1

  - `loanInformation.installmentAmount` (number)
    The amount of the installment being paid.
    Example: 100.02

  - `loanInformation.installmentDueDate` (string)
    The due date of the installment being paid, in YYYY-MM-DD format.
    Example: "2025-03-01"

  - `loanInformation.totalAmount` (number)
    The total amount of the loan.
    Example: 12000.24

  - `loanInformation.totalInstallments` (integer)
    The total number of installments for the loan.
    Example: 12

## Response 400 fields (application/json):

  - `statusCode` (integer)
    The HTTP status code for this error.
    Example: 400

  - `error` (string)
    The HTTP status code description for this error.
    Example: "Bad Request"

  - `message` (any)
    A short description of the error, indicating what is wrong with the request.
> Note: We return either a string or an array of strings, depending on the validation error(s). 

The description can be (among others):

  - id must be a UUID
  - Not enough balance
  - amount is not a valid decimal number.
  - currency must be one of the following values: cop, mxn, usd
  - reference must be a string
  - Customer not found for merchant
  - documentType is a required field
    Example: "id must be a UUID"

## Response 401 fields (application/json):

  - `statusCode` (integer)
    The HTTP status code for this error.
    Example: 401

  - `error` (string)
    The HTTP status code description for this error.
    Example: "Unauthorized"

  - `message` (string)
    A short description of the error, indicating what is wrong with the request.
In the case of a 401 Unauthorized error, the message is:

  - Unauthorized credentials
    Example: "Unauthorized credentials"

## Response 404 fields (application/json):

  - `statusCode` (integer)
    The HTTP status code for this error.
    Example: 404

  - `error` (string)
    The HTTP status code description for this error.
    Example: "Not Found"

  - `message` (string)
    A short description of the error, indicating what is wrong with the request.
The description can be (among others):

  - Payout Target not found
  - Payment method not found
  - Customer not found
    Example: "Payout Target not found"