# Simulate Payout Completion

Move one of the user's payouts to `completed` or `failed` without the bank ramp, to test your payout screens.

## Overview

Create a payout with [Initiate Payout](https://docs.aureahub.com/docs/payout-initiate.md) and keep its `payoutId`, then call this endpoint. Aurea sets the payout's status to the chosen `outcome` and sends the user the same push notification as a real completion or failure. The bank ramp is not contacted, and no webhook is involved.

> ℹ️ Only the user's own **sandbox** payouts can be simulated: a production payout, or another user's, answers `404`. Payouts must be switched on for your tenant in the sandbox, otherwise `403` `NOAH_FUNCTION_OFF`. The simulation works on any Aurea deployment; there is no separate sandbox host.

## Endpoint

### `POST /v1/ramp/bank/payout/sandbox/simulate`

Authentication: bearer token required.

Sets the status of one of the authenticated user's sandbox payouts to completed or failed.

**Request body**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `payoutId` | string | yes | Payout UUID returned by Initiate Payout |
| `outcome` | string | no | completed (default) or failed |

**Responses**

`200` OK

```json
{ "success": true, "message": "Payout simulation triggered: completed" }
```

`404` Not a sandbox payout of the user

```json
{ "statusCode": 404, "error": "NotFoundError", "message": "Payout not found" }
```

`403` Payouts switched off

```json
{
  "statusCode": 403,
  "error": "ForbiddenError",
  "message": "The bank ramp's payout is not switched on for this tenant in sandbox.",
  "details": { "code": "NOAH_FUNCTION_OFF", "function": "payout", "environment": "sandbox" }
}
```

## Implementation

```javascript
const API = 'https://api.aureahub.com'; // base URL of the Aurea deployment you use
const headers = { Authorization: `Bearer ${token}`, 'Content-Type': 'application/json' };

// 1. Create a sandbox payout (isTestnet: true selects the sandbox)
const payout = await fetch(`${API}/v1/ramp/bank/payout/initiate`, {
  method: 'POST', headers,
  body: JSON.stringify({ cryptoCurrency: 'EURC_TEST', cryptoAmount: '20000000', fiatCurrency: 'EUR', returnUrl: 'myapp://payout/done', isTestnet: true })
}).then(r => r.json());

// 2. Force the outcome
await fetch(`${API}/v1/ramp/bank/payout/sandbox/simulate`, {
  method: 'POST', headers,
  body: JSON.stringify({ payoutId: payout.payoutId, outcome: 'completed' })
});

// 3. Read it back from the sandbox: status is now "completed"
const current = await fetch(`${API}/v1/ramp/bank/payout/transactions/${payout.payoutId}?isTestnet=true`, { headers }).then(r => r.json());
```

---

Web version: https://docs.aureahub.com/#sandbox-payout