> ## Documentation Index
> Fetch the complete documentation index at: https://docs.localpayment.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Simular un pago de cuenta virtual

Aprende a probar la integración de tu cuenta virtual simulando pagos entrantes en el entorno de prueba. Valida tus receptores de webhook y la lógica de conciliación sin transferencias bancarias reales.

Probar la integración de tu cuenta virtual es un paso fundamental antes de tu lanzamiento. Para facilitar este proceso, Localpayment proporciona un endpoint de simulación en el **entorno de prueba** que te permite simular un pago entrante a cualquier cuenta virtual activa.

Esta simulación imita el comportamiento de una transferencia ACH local real, lo que activa las mismas actualizaciones de estado internas y notificaciones de webhook que cabría esperar en un entorno de producción.

## Flujo de simulación

1. **Crear una cuenta virtual**: Primero, genera una cuenta virtual en el entorno de prueba.
2. **Obtener estado de la cuenta virtual**: Usa el endpoint [Obtener estado de la cuenta virtual](https://docs.localpayment.com/es/reference/get-virtual-account-status.md) para confirmar que la cuenta se creó correctamente y recuperar el campo `beneficiary.bank.account.number` de la respuesta.
3. **Vincular con la simulación**: En tu solicitud de simulación, usa el `beneficiary.bank.account.number` obtenido en el paso anterior para vincular el pago simulado a la cuenta correcta. Además, proporciona un `externalId` único — este actúa como el ID del payin generado para esta transacción; utiliza un `externalId` diferente para cada solicitud de simulación. También debes incluir el **accountNumber** (ID de comerciante) de tu cuenta de Localpayment para identificar la cuenta del comerciante asociada al pago simulado.
4. **Activar simulación**: Llama al endpoint [Simular un pago de cuenta virtual](https://docs.localpayment.com/es/reference/simulate-payin-to-virtual-account.md).
5. **Recibir Webhook**: Localpayment enviará un webhook `payin.completed` (o similar) a tu endpoint configurado.
6. **Verificar estado**: utiliza la API de estado de la transacción para confirmar que la transacción simulada ha alcanzado el estado esperado.

***

## Dependencias técnicas

> [!NOTE]
>
> **Requisito secuencial**: No se puede simular un pago para una cuenta que no se haya creado correctamente. Si la llamada para [Crear una cuenta virtual](https://docs.localpayment.com/es/reference/create-virtual-account.md) falla, el intento de simulación devolverá un error 404 (No encontrado).

***

## Ejemplos de código (Stage)

Selecciona tu mercado objetivo para ver un ejemplo completo de `curl`. Utiliza los mismos datos del beneficiario proporcionados al crear la cuenta virtual y proporciona un `externalId` único para cada solicitud de simulación.

> [tab] Argentina
>
> ```bash theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
> curl --request POST \
>   --url https://api.stage.localpayment.com/api/simulate/va \
>   --header 'Authorization: Bearer {{access_token}}' \
>   --header 'accept: application/json' \
>   --header 'content-type: application/json' \
>   --data '
> {
>   "externalId": "de14bcf2-15ee-22e3-ab59-99c3fcba31e8",
>   "paymentMethod": {
>     "type": "BankTransfer",
>     "code": "1025",
>     "flow": "DIRECT"
>   },
>   "country": "ARG",
>   "currency": "ARS",
>   "amount": 100.00,
>   "accountNumber": "{{accountNumber}}",
>   "beneficiary": {
>     "type": "INDIVIDUAL",
>     "name": "Camilo",
>     "lastName": "Sabogal",
>     "fullName": "Camilo Sabogal",
>     "document": {
>       "type": "CUIT",
>       "id": "20314567894"
>     },
>     "bank": {
>       "account": {
>         "number": "3745135018378011718454"
>       }
>     }
>   },
>   "payer": {
>     "type": "INDIVIDUAL",
>     "name": "Carlos",
>     "lastName": "Mendez",
>     "fullName": "Carlos Mendez",
>     "document": {
>       "type": "CUIT",
>       "id": "20314567894"
>     },
>     "email": "carlos.mendez@email.com",
>     "bank": {
>       "name": "Banco Galicia",
>       "code": "007",
>       "account": {
>         "type": "CBU",
>         "number": "0070001200001234567890"
>       }
>     }
>   }
> }
> '
> ```

> [tab] Brasil
>
> ```bash theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
> curl --request POST \
>   --url https://api.stage.localpayment.com/api/simulate/va \
>   --header 'Authorization: Bearer {{access_token}}' \
>   --header 'accept: application/json' \
>   --header 'content-type: application/json' \
>   --data '
> {
>   "externalId": "0d55e796-bba6-4cf0-aead-8d9c1ed31044",
>   "paymentMethod": {
>     "type": "BankTransfer",
>     "code": "1350",
>     "flow": "DIRECT"
>   },
>   "country": "BRA",
>   "currency": "BRL",
>   "amount": 100.00,
>   "accountNumber": "{{accountNumber}}",
>   "beneficiary": {
>     "type": "INDIVIDUAL",
>     "name": "Rafael",
>     "lastName": "Oliveira",
>     "fullName": "Rafael Oliveira",
>     "document": {
>       "type": "CPF",
>       "id": "12345678909"
>     },
>     "bank": {
>       "account": {
>         "number": "00099999-8"
>       }
>     }
>   },
>   "payer": {
>     "type": "INDIVIDUAL",
>     "name": "Rafael",
>     "lastName": "Oliveira",
>     "fullName": "Rafael Oliveira",
>     "document": {
>       "type": "CPF",
>       "id": "12345678909"
>     },
>     "email": "rafael.oliveira@email.com",
>     "bank": {
>       "name": "Itau",
>       "code": "341",
>       "account": {
>         "number": "12345-6"
>       }
>     }
>   }
> }
> '
> ```

> [tab] Chile
>
> ```bash theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
> curl --request POST \
>   --url https://api.stage.localpayment.com/api/simulate/va \
>   --header 'Authorization: Bearer {{access_token}}' \
>   --header 'accept: application/json' \
>   --header 'content-type: application/json' \
>   --data '
> {
>   "externalId": "d2ffc771-2678-4dcc-8819-d446656a19f9",
>   "paymentMethod": {
>     "type": "BankTransfer",
>     "code": "2530",
>     "flow": "DIRECT"
>   },
>   "country": "CHL",
>   "currency": "CLP",
>   "amount": 100.00,
>   "accountNumber": "{{accountNumber}}",
>   "beneficiary": {
>     "type": "INDIVIDUAL",
>     "name": "Valentina",
>     "lastName": "Rojas",
>     "fullName": "Valentina Rojas",
>     "document": {
>       "type": "RUT",
>       "id": "123456789"
>     },
>     "bank": {
>       "account": {
>         "number": "00099999999"
>       }
>     }
>   },
>   "payer": {
>     "type": "INDIVIDUAL",
>     "name": "Valentina",
>     "lastName": "Rojas",
>     "fullName": "Valentina Rojas",
>     "document": {
>       "type": "RUT",
>       "id": "123456789"
>     },
>     "email": "valentina.rojas@email.com",
>     "bank": {
>       "name": "Banco de Chile",
>       "code": "001",
>       "account": {
>         "number": "00112345678"
>       }
>     }
>   }
> }
> '
> ```

> [tab] Colombia
>
> ```bash theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
> curl --request POST \
>   --url https://api.stage.localpayment.com/api/simulate/va \
>   --header 'Authorization: Bearer {{access_token}}' \
>   --header 'accept: application/json' \
>   --header 'content-type: application/json' \
>   --data '
> {
>   "externalId": "b3e14f73-8452-49b2-bf3c-b770774edfa8",
>   "paymentMethod": {
>     "type": "BankTransfer",
>     "code": "2006",
>     "flow": "DIRECT"
>   },
>   "country": "COL",
>   "currency": "COP",
>   "amount": 100.00,
>   "accountNumber": "{{accountNumber}}",
>   "beneficiary": {
>     "type": "INDIVIDUAL",
>     "name": "Andres",
>     "lastName": "Herrera",
>     "fullName": "Andres Herrera",
>     "document": {
>       "type": "CC",
>       "id": "1020456789"
>     },
>     "bank": {
>       "account": {
>         "number": "20099999999"
>       }
>     }
>   },
>   "payer": {
>     "type": "INDIVIDUAL",
>     "name": "Andres",
>     "lastName": "Herrera",
>     "fullName": "Andres Herrera",
>     "document": {
>       "type": "CC",
>       "id": "1020456789"
>     },
>     "email": "andres.herrera@email.com",
>     "bank": {
>       "name": "Bancolombia",
>       "code": "007",
>       "account": {
>         "number": "20012345678"
>       }
>     }
>   }
> }
> '
> ```

> [tab] Costa Rica (CRC)
>
> ```bash theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
> curl --request POST \
>   --url https://api.stage.localpayment.com/api/simulate/va \
>   --header 'Authorization: Bearer {{access_token}}' \
>   --header 'accept: application/json' \
>   --header 'content-type: application/json' \
>   --data '
> {
>   "externalId": "a1c2e3f4-5b6d-47a8-9c0e-1f2a3b4c5d6e",
>   "paymentMethod": {
>     "type": "BankTransfer",
>     "code": "1420",
>     "flow": "DIRECT"
>   },
>   "country": "CRI",
>   "currency": "CRC",
>   "amount": 100.00,
>   "accountNumber": "{{accountNumber}}",
>   "beneficiary": {
>     "type": "INDIVIDUAL",
>     "name": "Carlos",
>     "lastName": "Mendez",
>     "fullName": "Carlos Mendez",
>     "document": {
>       "type": "CI",
>       "id": "2-0456-0789"
>     },
>     "bank": {
>       "account": {
>         "number": "CR91090100000000125311"
>       }
>     }
>   },
>   "payer": {
>     "type": "INDIVIDUAL",
>     "name": "John",
>     "lastName": "Doe",
>     "fullName": "John Doe",
>     "document": {
>       "type": "CI",
>       "id": "01-0100-0001"
>     },
>     "email": "john.doe@email.com",
>     "bank": {
>       "name": "Banco Nacional de Costa Rica",
>       "code": "0151",
>       "account": {
>         "number": "CR99000000000000000003"
>       }
>     }
>   }
> }
> '
> ```

> [tab] Costa Rica (USD)
>
> ```bash theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
> curl --request POST \
>   --url https://api.stage.localpayment.com/api/simulate/va \
>   --header 'Authorization: Bearer {{access_token}}' \
>   --header 'accept: application/json' \
>   --header 'content-type: application/json' \
>   --data '
> {
>   "externalId": "b2d3f4a5-6c7e-48b9-a1d0-2f3b4c5d6e7f",
>   "paymentMethod": {
>     "type": "BankTransfer",
>     "code": "1421",
>     "flow": "DIRECT"
>   },
>   "country": "CRI",
>   "currency": "USD",
>   "amount": 100.00,
>   "accountNumber": "{{accountNumber}}",
>   "beneficiary": {
>     "type": "INDIVIDUAL",
>     "name": "Carlos",
>     "lastName": "Mendez",
>     "fullName": "Carlos Mendez",
>     "document": {
>       "type": "CI",
>       "id": "2-0456-0789"
>     },
>     "bank": {
>       "account": {
>         "number": "CR91090100000000125511"
>       }
>     }
>   },
>   "payer": {
>     "type": "INDIVIDUAL",
>     "name": "John",
>     "lastName": "Doe",
>     "fullName": "John Doe",
>     "document": {
>       "type": "CI",
>       "id": "01-0100-0001"
>     },
>     "email": "john.doe@email.com",
>     "bank": {
>       "name": "Banco Nacional de Costa Rica",
>       "code": "0151",
>       "account": {
>         "number": "CR99000000000000000002"
>       }
>     }
>   }
> }
> '
> ```

> [tab] México (SPEI)
>
> ```bash theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
> curl --request POST \
>   --url https://api.stage.localpayment.com/api/simulate/va \
>   --header 'Authorization: Bearer {{access_token}}' \
>   --header 'accept: application/json' \
>   --header 'content-type: application/json' \
>   --data '
> {
>   "externalId": "f059a032-9253-4607-9b8e-2948ed18d595",
>   "paymentMethod": {
>     "type": "BankTransfer",
>     "code": "1630",
>     "flow": "DIRECT"
>   },
>   "country": "MEX",
>   "currency": "MXN",
>   "amount": 100.00,
>   "accountNumber": "{{accountNumber}}",
>   "beneficiary": {
>     "type": "INDIVIDUAL",
>     "name": "Juan",
>     "lastName": "Perez",
>     "fullName": "Juan Perez",
>     "document": {
>       "type": "RFC",
>       "id": "PEPJ800101XXX"
>     },
>     "bank": {
>       "account": {
>         "number": "137424104400399999"
>       }
>     }
>   },
>   "payer": {
>     "type": "INDIVIDUAL",
>     "name": "Alejandra",
>     "lastName": "Guzman",
>     "fullName": "Alejandra Guzman",
>     "document": {
>       "type": "RFC",
>       "id": "KCWV771228TS4"
>     },
>     "email": "alejandra.guzman@email.com",
>     "bank": {
>       "name": "BanCoppel",
>       "code": "137",
>       "account": {
>         "type": "C",
>         "number": "137424104400310004"
>       }
>     }
>   }
> }
> '
> ```

> [tab] México (TEF)
>
> ```bash theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
> curl --request POST \
>   --url https://api.stage.localpayment.com/api/simulate/va \
>   --header 'Authorization: Bearer {{access_token}}' \
>   --header 'accept: application/json' \
>   --header 'content-type: application/json' \
>   --data '
> {
>   "externalId": "b8c924d1-3f7a-4e82-bc1d-9a06fe37510c",
>   "paymentMethod": {
>     "type": "BankTransfer",
>     "code": "1680",
>     "flow": "DIRECT"
>   },
>   "country": "MEX",
>   "currency": "MXN",
>   "amount": 100.00,
>   "accountNumber": "{{accountNumber}}",
>   "beneficiary": {
>     "type": "COMPANY",
>     "name": "Servicios Digitales México S.A.",
>     "document": {
>       "type": "RFC",
>       "id": "HEMJ900101ABC"
>     },
>     "bank": {
>       "account": {
>         "number": "000000000000000009"
>       }
>     }
>   },
>   "payer": {
>     "type": "COMPANY",
>     "name": "Juan",
>     "lastName": "Doe",
>     "fullName": "Juan Doe",
>     "document": {
>       "type": "RFC",
>       "id": "HEMJ900101ABC"
>     },
>     "email": "juan.doe@email.com",
>     "bank": {
>       "name": "BANCO INBURSA",
>       "code": "036",
>       "account": {
>         "type": "CLABE",
>         "number": "00000000000000000001"
>       }
>     }
>   }
> }
> '
> ```

> [tab] Perú
>
> ```bash theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
> curl --request POST \
>   --url https://api.stage.localpayment.com/api/simulate/va \
>   --header 'Authorization: Bearer {{access_token}}' \
>   --header 'accept: application/json' \
>   --header 'content-type: application/json' \
>   --data '
> {
>   "externalId": "e6807dd1-e910-41ea-9adc-b240a5509dd3",
>   "paymentMethod": {
>     "type": "BankTransfer",
>     "code": "6100",
>     "flow": "DIRECT"
>   },
>   "country": "PER",
>   "currency": "PEN",
>   "amount": 100.00,
>   "accountNumber": "{{accountNumber}}",
>   "beneficiary": {
>     "type": "INDIVIDUAL",
>     "name": "Lucia",
>     "lastName": "Torres",
>     "fullName": "Lucia Torres",
>     "document": {
>       "type": "DNI",
>       "id": "45678901"
>     },
>     "bank": {
>       "account": {
>         "number": "00219100111111100009"
>       }
>     }
>   },
>   "payer": {
>     "type": "INDIVIDUAL",
>     "name": "Lucia",
>     "lastName": "Torres",
>     "fullName": "Lucia Torres",
>     "document": {
>       "type": "DNI",
>       "id": "45678901"
>     },
>     "email": "lucia.torres@email.com",
>     "bank": {
>       "name": "BCP",
>       "code": "002",
>       "account": {
>         "number": "19400123456789"
>       }
>     }
>   }
> }
> '
> ```

***

## Ejemplo de notificación de webhook

Tras un procesamiento exitoso, Localpayment envía un evento `payin.completed` síncrono a tu endpoint configurado. Esta notificación sigue la estructura `PayIn` de alto nivel estándar observada en todos los productos de pago.

```json MEX (SPEI) theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
{
  "transactionType": "PayIn",
  "transactionFlow": null,
  "country": "MEX",
  "data": {
    "transactionType": "PayIn",
    "externalId": "f059a032-9253-4607-9b8e-2948ed18d595",
    "internalId": "5aced5da-40c1-4bec-85ff-c8cd1bcb4526",
    "paymentMethod": {
      "type": "BankTransfer",
      "code": "1630",
      "flow": "DIRECT"
    },
    "country": "MEX",
    "currency": "MXN",
    "amount": 100.00,
    "accountNumber": "{{accountNumber}}",
    "confirmed": {
      "currency": "MXN",
      "fxQuote": 1.0,
      "amount": 100.00
    },
    "beneficiary": {
      "type": "INDIVIDUAL",
      "name": "Juan",
      "lastName": "Perez",
      "fullName": "Juan Perez",
      "document": {
        "type": "RFC",
        "id": "PEPJ800101XXX"
      }
    },
    "payer": {
      "type": "INDIVIDUAL",
      "name": "Alejandra",
      "lastName": "Guzman",
      "fullName": "Alejandra Guzman",
      "document": {
        "type": "RFC",
        "id": "KCWV771228TS4"
      }
    },
    "status": {
      "code": "200",
      "description": "COMPLETED",
      "detail": "The payin was credited"
    },
    "date": {
      "creationDate": "2024-03-27T15:00:00Z",
      "processedDate": "2024-03-27T15:00:05Z"
    }
  }
}
```

```json MEX (TEF) theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
{
  "transactionType": "PayIn",
  "transactionFlow": null,
  "country": "MEX",
  "data": {
    "transactionType": "PayIn",
    "externalId": "b8c924d1-3f7a-4e82-bc1d-9a06fe37510c",
    "internalId": "e05fc3c3-f739-4393-b275-4a12f5a1af15",
    "paymentMethod": {
      "type": "BankTransfer",
      "code": "1680",
      "flow": "DIRECT"
    },
    "country": "MEX",
    "currency": "MXN",
    "amount": 1000.01,
    "accountNumber": "{{accountNumber}}",
    "confirmed": {
      "currency": "MXN",
      "fxQuote": 1,
      "amount": 1000.01
    },
    "beneficiary": {
      "type": "COMPANY",
      "name": "Servicios Digitales México S.A.",
      "document": {
        "type": "RFC",
        "id": "HEMJ900101ABC"
      },
      "bank": {
        "name": "Banco Central",
        "code": "001",
        "account": {
          "number": "000000000000000009"
        }
      }
    },
    "payer": {
      "type": "COMPANY",
      "name": "Juan",
      "lastName": "Doe",
      "fullName": "Juan Doe",
      "document": {
        "type": "RFC",
        "id": "HEMJ900101ABC"
      },
      "bank": {
        "name": "BANCO INBURSA",
        "code": "036",
        "account": {
          "type": "CLABE",
          "number": "00000000000000000001"
        }
      }
    },
    "status": {
      "code": "200",
      "description": "COMPLETED",
      "detail": "The payin was credited"
    },
    "date": {
      "creationDate": "2024-03-27T15:00:00Z",
      "processedDate": "2024-03-27T15:00:05Z"
    }
  }
}
```

***

## Solución de problemas

| Código de error | Causa potencial | Solución recomendada |
| :- | :- | :- |
| **400 Solicitud incorrecta** | Identidad del pagador no válida o campos faltantes. | Asegúrate de que los datos del pagador coincidan con la información del beneficiario utilizada al crear la cuenta virtual. |
| **404 No encontrado** | `externalId` no coincide con ningún VA activo. | Verifica que la cuenta virtual se haya creado correctamente en el entorno de prueba antes de realizar la simulación. |
| **401 No autorizado** | Se ha utilizado un token inválido o de producción. | Confirma que estás utilizando la clave API de tu **entorno de prueba**. |
| **422 No procesable** | Discrepancia en la cantidad o en la moneda. | Verifica que la moneda coincida con el `paymentMethod.code` seleccionado. |

***

## Próximos pasos

> [card] [Verificar estado](https://docs.localpayment.com/es/reference/get-transaction-status.md)
>
> Obtén actualizaciones de estado en tiempo real para confirmar el progreso de la transacción simulada.

> [card] [Configurar webhooks](https://docs.localpayment.com/es/docs/webhooks.md)
>
> Valida la lógica de tu oyente con notificaciones de éxito en tiempo real.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.