Payout passcode errors - Dollr Developer Docs

Symptom

POST /v1/executions/payout returns 422 or 403, or payout status is FAILED immediately.

Cause

Payout execution requires a passcode object — merchant verification plus device metadata. Missing or incorrect passcode is the most common payout integration mistake.

Set up your passcode

Log in to merchant.heydollr.app
Go to Settings → Security (or Profile → Passcode)
Create or reset your merchant passcode
Link the passcode to the phone number you will send in passcode.token.phone

If you cannot find passcode settings, contact dev@heydollr.app.

Required payload shape

{
  "session_id": "42",
  "payout_account_id": "18",
  "reference_id": "550e8400-e29b-41d4-a716-446655440000",
  "passcode": {
    "token": {
      "phone": "231771234567",
      "code": "your-passcode"
    },
    "device": {
      "name": "Payout Server",
      "type": "SERVER",
      "platform": "NODE",
      "user_agent": "my-app/1.0",
      "client_ip": "203.0.113.10"
    }
  }
}

Field	Notes
`token.code`	Your merchant passcode (required)
`token.phone`	Phone tied to passcode in portal
`token.user_id`	Alternative to phone if your account uses user ID
`device.*`	All device fields required for audit

Checklist

Merchant account fully verified (403 guide)
Passcode created in merchant portal
phone matches portal registration
payout_account_id matches session create payload
reference_id is UUID v4, stored before HTTP call

Last modified on June 23, 2026