Activate/Deactivate Virtual Account

Localpayment allows you to temporarily suspend or reactivate virtual accounts, providing flexibility to manage account status without permanent deletion. This is useful for temporary holds, dispute resolution, or seasonal business patterns.

Before You Begin

Ensure you have:

Valid API credentials (access token).
Virtual account external ID you want to activate or deactivate.
Understanding of the virtual account's current status.

Virtual Account Status Management

Manage your virtual account status using any of the following methods:

Activate Virtual Account

Reactivate a previously deactivated virtual account to resume payment acceptance.

Deactivate Virtual Account

Temporarily suspend a virtual account to prevent further payments while preserving account data.

Check Account Status

Verify the current status of a virtual account before performing activation or deactivation.

Virtual Account Status Reference

Understanding virtual account statuses is crucial for proper activation/deactivation management:

Description	Can Activate	Can Deactivate
INPROGRESS	❌	❌
COMPLETED	❌	✅
DELETED	❌	❌
DISABLED	✅	❌

Activate Virtual Account

Reactivate a previously deactivated virtual account to resume payment acceptance.

Send a PUT request to Update Virtual Account Status endpoint using the external ID:

Example Request

Below is an example using curl:

curl --request PUT \
     --url https://api.stage.localpayment.com/api/virtual-account/{externalId}/activation/enable/ \
  --header 'Authorization: Bearer <your_access_token>' \
     --header 'accept: application/json'

Key Request Parameters

The request requires several key objects:

Parameter	Description	Required
`externalId`	The external ID of the virtual account to activate (path parameter)	✅

Successful Response

{
  "currency": "MXN",
  "externalId": "e36ef929-c2d4-fcf0-b30c-99dc51798f4b",
  "internalId": "c09095fb-6a0e-47af-9f43-3d9452b0f290",
  "accountNumber": "484.484.00000011",
  "beneficiary": {
    "type": "INDIVIDUAL",
    "name": "John",
    "document": {
      "type": "RFC",
      "id": "EXTF900101NI1"
    },
    "bank": {
      "branch": {},
      "account": {
        "number": "646011319800023123",
        "aliases": [],
        "owner": {
          "document": {}
        }
      }
    },
    "fullName": "John Doe",
    "lastName": "Doe"
  },
  "status": {
    "code": "200",
    "description": "COMPLETED",
    "detail": "Virtual account has been created"
  },
  "errors": []
}

Key Response Fields

Field	Description	Use Case
`internalId`	Localpayment's unique identifier for the virtual account.	Support and system reference
`externalId`	Your original reference number for the virtual account.	Internal reconciliation and tracking
`status.code`	Current status code of the virtual account.	Determine account usability and next actions

Deactivate Virtual Account

Temporarily suspend a virtual account to prevent further payments while preserving account data and history.

Send a PUT request to Update Virtual Account Status endpoint using the external ID:

⚠️
Important
In Peru, when a virtual account is deactivated, it will appears as nonexistent in your banking app.

Example Request

Below is an example using curl:

curl --request PUT \
     --url https://api.stage.localpayment.com/api/virtual-account/{externalId}/activation/disable/ \
  --header 'Authorization: Bearer <your_access_token>' \
     --header 'accept: application/json'

Key Request Parameters

The request requires several key objects:

Parameter	Description	Required
`externalId`	The external ID of the virtual account to activate (path parameter)	✅

Successful Response

{
  "currency": "MXN",
  "externalId": "e36eff59-22d4-ccf0-bf0c-99dc51798f4b",
  "internalId": "c09095fb-6a4e-17cf-9343-9d9452b0f290",
  "accountNumber": "484.484.00000011",
  "beneficiary": {
    "type": "INDIVIDUAL",
    "name": "John",
    "document": {
      "type": "RFC",
      "id": "EXTF900101NI1"
    },
    "bank": {
      "branch": {},
      "account": {
        "number": "646011319800023123",
        "aliases": [],
        "owner": {
          "document": {}
        }
      }
    },
    "fullName": "John Doe",
    "lastName": "Doe"
  },
  "status": {
    "code": "300",
    "description": "DISABLED",
    "detail": "Virtual account disabled"
  },
  "errors": []
}

Key Response Fields

Field	Description	Use Case
`internalId`	Localpayment's unique identifier for the virtual account.	Support and system reference
`externalId`	Your original reference number for the virtual account.	Internal reconciliation and tracking
`status.code`	Current status code of the virtual account.	Determine account usability and next actions

Next Steps

After managing virtual account activation status, you may need to perform additional actions:

Check Virtual Account Status

Verify the current status of activated or deactivated virtual accounts.

Delete Virtual Account

Permanently remove virtual accounts that are no longer needed.