Simulate a Virtual Account Payment
Testing your virtual account integration is a critical step before going live. To facilitate this, Localpayment provides a simulation endpoint in the Stage environment that allows you to trigger a mock incoming payment to any active virtual account.
This simulation mimics the behavior of a real local ACH transfer, triggering the same internal status updates and webhook notifications you would expect in Production.
Simulation Flow
- Create a Virtual Account: First, generate a virtual account in the Stage environment.
- Get Virtual Account Status: Use the Get Virtual Account Status endpoint to confirm the account was successfully created and retrieve the
beneficiary.bank.account.numberfield from the response. - Link to Simulation: In your simulation request, use the
beneficiary.bank.account.numberobtained in the previous step to link the mock payment to the correct account. Additionally, provide a uniqueexternalId— this acts as the ID of the payin generated for this transaction; use a differentexternalIdfor each simulation request. You must also include your Localpayment accountNumber (Merchant ID) to identify the merchant account associated with the simulated payment. - Trigger Simulation: Call the Simulate a Virtual Account Payment endpoint.
- Receive Webhook: Localpayment will send a
payin.completed(or similar) webhook to your configured endpoint. - Verify Status: Use the Transaction Status API to confirm the mock transaction has reached the expected state.
Technical Dependencies
Sequential Requirement: You cannot simulate a payment for an account that has not been successfully created. If the Create a Virtual Account call fails, the simulation attempt will return a 404 Not Found error.
Code Examples (Stage)
Select your target market to see a complete curl example. Use the same beneficiary data provided when creating the virtual account, and supply a unique externalId for each simulation request.
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"
}
},
"payer": {
"type": "INDIVIDUAL",
"name": "Carlos",
"lastName": "Mendez",
"fullName": "Carlos Mendez",
"document": {
"type": "CUIT",
"id": "20314567894"
},
"email": "[email protected]",
"bank": {
"name": "Banco Galicia",
"code": "007",
"account": {
"type": "CBU",
"number": "0070001200001234567890"
}
}
}
}
'Webhook Notification Sample
Upon successful processing, Localpayment sends a synchronous payin.completed event to your configured endpoint. This notification follows the standard high-level PayIn structure seen across all payment products.
{
"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"
}
}
}{
"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"
}
}
}Troubleshooting
| Error Code | Potential Cause | Recommended Fix |
|---|---|---|
| 400 Bad Request | Invalid payer identity or missing fields. | Ensure the payer data matches the beneficiary information used when creating the virtual account. |
| 404 Not Found | externalId does not match any active VA. | Verify the Virtual Account was successfully created in Stage before simulating. |
| 401 Unauthorized | Invalid or Production token used. | Confirm you are using your Stage environment API key. |
| 422 Unprocessable | Amount or currency mismatch. | Cross-check that the currency matches the paymentMethod.code selected. |