> ## 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.

# Simule um pagamento de Virtual Account

Aprenda a testar a integração da sua Virtual Account simulando pagamentos recebidos no ambiente de teste. Valide seus listeners de webhook e a lógica de conciliação sem transferências bancárias reais.

Testar a integração da sua Virtual Account é uma etapa crucial antes de entrar em produção. Para facilitar isso, a Localpayment oferece um endpoint de simulação no **ambiente de teste** que permite acionar um pagamento simulado para qualquer Virtual Account ativa.

Esta simulação reproduz o comportamento de uma transferência ACH local real, acionando as mesmas atualizações de status internas e notificações de webhook que você esperaria em um ambiente de produção.

## Fluxo de simulação

1. **Create a Virtual Account**: Primeiro, gere uma Virtual Account no ambiente de teste.
2. **Get Virtual Account Status**: Use o endpoint [Get Virtual Account Status](https://docs.localpayment.com/pt-br/reference/get-virtual-account-status.md) para confirmar se a conta foi criada com sucesso e recuperar o campo `beneficiary.bank.account.number` da resposta.
3. **Link para a simulação**: Em sua solicitação de simulação, utilize o `beneficiary.bank.account.number` obtido na etapa anterior para vincular o pagamento simulado à conta correta. Além disso, forneça um `externalId` exclusivo: ele funciona como o ID do payin gerado para esta transação; use um `externalId` diferente para cada solicitação de simulação. Você também deve incluir seu **accountNumber** Localpayment (ID do comerciante) para identificar a conta comercial associada ao pagamento simulado.
4. **Acionar simulação**: Chame o endpoint [Simulate a Virtual Account Payment](https://docs.localpayment.com/pt-br/reference/simulate-payin-to-virtual-account.md).
5. **Webhook de recebimento**: Localpayment enviará um webhook `payin.completed` (ou similar) para o seu endpoint configurado.
6. **Verificar status**: Use a API de status da transação para confirmar se a transação simulada atingiu o estado esperado.

***

## Dependências técnicas

> [!NOTE]
>
> **Requisito sequencial**: Não é possível simular um pagamento para uma conta que não foi criada com sucesso. Se a chamada [Create a Virtual Account](https://docs.localpayment.com/pt-br/reference/create-virtual-account.md) falhar, a tentativa de simulação retornará um erro 404 Não Encontrado.

***

## Exemplos de código (Estágio)

Selecione seu mercado-alvo para ver um exemplo completo de `curl`. Utilize os mesmos dados do beneficiário fornecidos ao criar a Virtual Account e informe um `externalId` exclusivo para cada solicitação de simulação.

> [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] Colômbia
>
> ```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] Peru
>
> ```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"
>       }
>     }
>   }
> }
> '
> ```

***

## Exemplo de notificação de webhook

Após o processamento bem-sucedido, a Localpayment envia um evento síncrono `payin.completed` para o seu endpoint configurado. Esta notificação segue a estrutura padrão de alto nível `PayIn` observada em todos os produtos de pagamento.

```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"
    }
  }
}
```

***

## Solução de problemas

| Código de erro | Causa potencial | Correção recomendada |
| :- | :- | :- |
| **400 Solicitação Inválida** | Identificação do pagador inválida ou campos ausentes. | Certifique-se de que os dados do pagador correspondam às informações do beneficiário utilizadas na criação da Virtual Account. |
| **404 Não encontrado** | `externalId` não corresponde a nenhum VA ativo. | Verifique se a Virtual Account foi criada com sucesso no ambiente de teste antes de iniciar a simulação. |
| **401 Não autorizado** | Token inválido ou de produção utilizado. | Confirme se você está usando a chave de API do seu **ambiente de teste** (Stage). |
| **422 Não processável** | Divergência de valor ou moeda. | Verifique se a moeda corresponde ao `paymentMethod.code` selecionado. |

***

## Próximos passos

> [card] [Verificar status](https://docs.localpayment.com/pt-br/reference/get-transaction-status.md)
>
> Obtenha atualizações de status em tempo real para confirmar o progresso da transação simulada.

> [card] [Configurar Webhooks](https://docs.localpayment.com/pt-br/docs/webhooks.md)
>
> Valide a lógica do seu ouvinte com notificações de sucesso em tempo real.


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