Skip to content
RightCapital Knowledge Base

Nationwide

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

Overview

Section titled “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

Section titled “Data Imported”

Account Mapping

Section titled “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

Section titled “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

Section titled “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

Section titled “Contract Fields”

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

Investment Fields

Section titled “Investment Fields”

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

Authentication

Section titled “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

Section titled “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

Section titled “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

Section titled “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.

Section titled “Related”