Simulate a payroll deposit (sandbox only)

Builds a bank deposit webhook, signs it with the sandbox's own secret, and sends it through the same HTTPS edge production uses — the full pipeline runs (verify → normalize → enqueue → reconcile), no real bank involved. Identify the receiving donor account with enrollment_id (the enrollment whose donor finished identity verification in the hosted flow); Roster resolves the simulated account for you. The church and the enrollment must belong to the authenticated partner. status_code echoes what the webhook edge answered: a rejection surfaces as-is rather than being masked as success. A deposit to an enrollment that is not active yet is accepted and held, exactly as a real early deposit would be. The simulated bank records the credit before the notice is sent, so when the webhook edge cannot be reached the answer is 502 and the credit stays recorded: repeat the same request with the same Idempotency-Key to resend the same notice without a second credit.

Headers

Idempotency-Key
Type: string
min length:
1
max length:
255
required

Required on every POST, before any effect: 1–255 visible ASCII characters, no spaces. The key belongs to the first body sent with it on this operation for 30 days from the moment that request arrives, including while that request is running and after a 5xx or a timeout. On an operation that creates a resource (POST /v1/churches, POST /v1/churches/import, POST /v1/church_consents, POST /v1/donor_sessions, POST /v1/manage_sessions, POST /v1/refunds and POST /v1/webhook_endpoints), a key whose request succeeded keeps its body for as long as the resource it created exists. A creation replayed with the same key and body returns the original resource with 200 and changes nothing; a 4xx releases the key.

Body

required

application/json

amount
Type: number
greater than:
0
max:
1000000
required

Deposit amount in dollars; must be exact cents, up to 1000000 (US$1,000,000.00). A larger amount gets 400.

church_id
Type: string
required

Roster identifier of the church this record belongs to.

enrollment_id
Type: string
required

The enrollment whose donor account receives the deposit. Send this or account_ref, not both. Returns 400 until the donor has finished identity verification, because the simulated account does not exist before that.

account_ref
Type: string

Simulated bank account reference receiving the credit. Alternative to enrollment_id. An account Roster does not know is accepted on purpose, as a real deposit to an unknown account would be, and is held as unmatched; it never reaches a donor. To credit a test donor, send enrollment_id.

trace
Type: string

Optional trace id, unique within your account. Roster scopes it to you before the notice is sent, so the reference the webhook edge receives (returned in simulated.trace) is not the value you send, and another partner's trace never collides with yours. When omitted, it is derived from your Idempotency-Key, so a retry with the same key and body finds the same deposit instead of crediting again. A trace you already used for a different deposit gets 400; a key you already used for a different deposit gets 409.

Responses

application/json
application/problem+json
application/problem+json
application/problem+json
application/problem+json
application/problem+json

post/sandbox/simulate/deposit

curl https://api.sandbox.rostergiving.com/sandbox/simulate/deposit \
  --request POST \
  --header 'Idempotency-Key: ' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --data '{
  "church_id": "",
  "enrollment_id": "",
  "account_ref": "",
  "amount": 1,
  "trace": ""
}'

Show Schema

{
  "status_code": 1,
  "simulated": {
    "event_type": "ach.credit.received",
    "trace": "string",
    "bank_ts": "2026-10-22T14:55:08.129Z"
  },
  "eligible_at": "2026-10-22T14:55:08.129Z",
  "next_run_at": "2026-10-22T14:55:08.129Z"
}

Simulated deposit sent to the webhook edge.

List the sandbox test values (sandbox only)

Simulate payroll connection (sandbox only)