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.number field from the response.
Link to Simulation: In your simulation request, use the beneficiary.bank.account.number obtained in the previous step to link the mock payment to the correct account. Additionally, provide a unique externalId — this acts as the ID of the payin generated for this transaction; use a different externalId for 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.

Next Steps

Verify Status

Retrieve real-time status updates to confirm mock transaction progress.

Configure Webhooks

Validate your listener logic with live success notifications.

Review Reconciliation

Map simulation data to your internal ledger and settlement logic.