Nationwide

Nationwide is an API-based data sync integration that imports annuity accounts from Nationwide Financial (Nationwide Advisory).

Overview

Attribute	Value
Integration Type	Data Sync (Inbound)
Authentication	OAuth 2.0 Authorization Code grant, HTTP Basic for token exchange
OAuth Scope	openid
Data Flow	Nationwide → RightCapital
Entity Types	Accounts (Annuity) only
Subtype	ANNUITY_TAXABLE
Constraint	One integration per advisor
Developer	Winston Li (Zefeng Li)
Cron Owner	heli.yin
Notion	Nationwide Advisory

Data Imported

Account Mapping

All accounts are investment accounts with subtype ANNUITY_TAXABLE. The vendor field linbus determines the annuity type:

Nationwide linbus	RightCapital Annuity Type
Fixed	Fixed Annuity
Variable	Variable Annuity

Note: Holdings only fetched for Variable annuities. Fixed annuities have no subaccount allocations.

Holding Mapping

All fund types map to open_end_fund / fund / open_end:

Nationwide fundType	RightCapital Discrete Type
Variable	open_end_fund
Fixed	open_end_fund
Index	open_end_fund
Strategy	open_end_fund

Security matching priority: CUSIP → fundCode (as security_reference). CUSIP is nullable, 9-char string.

Price calculation:

• If value and quantity are both non-zero: price = value / quantity
• Otherwise: price = 1, quantity = value

Other holding behavior: isCash() always returns false. No date tracking (LacksDate trait).

API Endpoints

Full paths relative to the configured API base (NATIONWIDE_API_ENDPOINT):

Endpoint	Method	Purpose
policy-management/nationwide-advisory-contract-list/v1/contracts	GET	List contracts
policy-management/nationwide-advisory-investments/v1/contracts/{id}/investments	GET	Get holdings

Contract Fields

contractNumber, productName, productType, owner, linbus, contractStatus, issueDate, annuitant, contractTotalBalance

Investment Fields

fundType, fundCode, longName, investmentValue, numberOfUnits, cusip, fundCompanyCode, fundCompany, cellType

Authentication

• Grant type: authorization_code — Advisor completes OAuth flow, code is exchanged for tokens.
• Token exchange: HTTP Basic Auth (HttpBasicAuthOptionProvider) to Nationwide’s token endpoint.
• User identification: userId claim extracted from JWT id_token, stored as the integration reference.
• Request headers: Each request carries:
  • X-NW-Message-ID — unique UUID per request
  • client_id — OAuth client ID
• Refresh token: 30-day expiry. When refreshed, the refresh token value stays the same (only the access token changes).
• Error handling: Nationwide returns "Refresh Token Expired" (within 2 days of expiry) or "Invalid Refresh Token" (after 2 days). Both are mapped to RefreshTokenExpiredException → UnauthorizedException.

Code Locations

Component	Path
Connector	retail-api/app/Integrations/Nationwide/Connector.php
Integrator	retail-api/app/Integrations/Nationwide/Integrator.php
Sync	retail-api/app/Integrations/Nationwide/Sync.php
Config	retail-api/app/Integrations/Nationwide/Config.php
Controller	retail-api/app/Integrations/Nationwide/Controller.php
OAuth Provider	retail-api/app/Integrations/Nationwide/OAuth2/Provider.php
Account Model	retail-api/app/Integrations/Nationwide/Models/Account.php
Investment Account	retail-api/app/Integrations/Nationwide/Models/InvestmentAccount.php
Holding Model	retail-api/app/Integrations/Nationwide/Models/Holding.php
Console Command	retail-api/app/Console/Commands/Integrations/Nationwide/Sync.php

Configuration

Environment variables:

Variable	Purpose
NATIONWIDE_API_ENDPOINT	API base URL
NATIONWIDE_OAUTH_CLIENT_ID	OAuth client ID
NATIONWIDE_OAUTH_CLIENT_SECRET	OAuth client secret
NATIONWIDE_OAUTH_REDIRECT_URI	OAuth redirect URI

Sync cron: 0 3 * * 2-6 (Tue–Sat UTC 3:00) via queue retail-integration-nationwide-nightly-sync (CLI: nationwide:sync).

Refresh Token Expired

Symptom: UnauthorizedException during sync.

Cause: Refresh token has a 30-day lifetime. Nationwide returns "Refresh Token Expired" for the first ~2 days after expiry, then "Invalid Refresh Token".

Solution: Advisor must re-authenticate through the OAuth flow.

Related

• Allianz API - Similar annuity integration