> ## Documentation Index > Fetch the complete documentation index at: https://docs.services.payward.com/llms.txt > Use this file to discover all available pages before exploring further. # Get bank link > Retrieves a Bank Link and its nested active Account Links. Unlinked links are not returned. Eligibility runs fresh on every read rather than being stored. Ownership validation is part of it: the bank account's holder must match this account's verified holder. An account that fails carries `ineligibility_reasons` such as `name_mismatch` and reports `ineligible`; an account that could not be evaluated carries none and reports `unknown`. ## OpenAPI ````yaml /api-reference/openapi_v3_pws.json get /v1/accounts/{account_id}/funds/bank-links/{bank_link_id} openapi: 3.1.0 info: title: Payward Services API description: >- The Payward Services (PWS) public API. PWS exposes Swaps (institutional FX-style trading), Conversion rules (rule-driven fiat ↔ crypto value movement), retail-style Quotes and Price Trigger Swaps, end-user Users / Verifications, Travel Rule address ownership verification, Funds (deposits, withdrawals, addresses, transactions), Portfolio, Earn, Reports, Webhooks, and Ramp (hosted fiat-to-crypto on-ramp checkout). All requests must be authenticated. All monetary values are decimal strings; all timestamps are ISO 8601 UTC. List endpoints are cursor-paginated. Errors follow a uniform shape (see `*ErrorResponse` schemas). version: v1 contact: name: Payward Services API Support url: https://docs.payward.com email: api-support@payward.com servers: - url: https://api.services.payward.com description: Production security: - ApiKey: [] ApiSign: [] ApiNonce: [] tags: - name: Users description: >- User onboarding and status flows that the partner manages. - **Create User** provisions a user with an email and external reference. - **Get User** retrieves the user's profile, verification status, and required actions. Use the returned user `id` for calls that require the user's identifier. - name: Assets description: >- Catalog of assets available on the platform with retail-display metadata (logos, market data, descriptions). - name: Conversion rules x-group: Users description: >- Rule-driven fiat ↔ crypto value movement, including conversion rules and deposits. - name: On-demand conversions x-group: Users description: One-off conversions from an account balance to a wallet destination. - name: Earn description: >- Manage auto-earn preferences and retrieve allocation and reward information. - name: Funds description: >- Deposits, withdrawals, addresses, methods, and the consolidated funding-transactions ledger. - name: Bank Links description: >- Link US bank accounts to an account through a Kraken-hosted widget, then reference them for money movement. Two resources model a connection: - A **Bank Link** is the connection between one account and one banking institution. Create it to get a hosted-widget URL, and send the user there to choose their institution and approve access. One account can hold many Bank Links. - An **Account Link** is one bank account — a checking account, for example — that the user shared through that connection. One Bank Link owns one or more Account Links. Use `account_link_id` to reference the bank account when you move money. Both ids are opaque handles. Provider identifiers, access tokens, owner names, and raw bank numbers are never exposed. Eligibility is evaluated on every read, and ownership must match: the bank account's holder must match the account's verified holder. An account that fails ownership validation reports `ineligible` with the reason `name_mismatch`. Unlinking is permanent. Linking the same bank account again creates a new Bank Link and a new `account_link_id`; old ids stay valid only for reading history. - name: Portfolio description: End-user portfolio summary, history, and transaction views. - name: Price Trigger Swaps description: Limit-style orders that execute when a configured price trigger is met. - name: On-chain Swaps description: >- Wallet-funded onchain quote trading for xStock and USDC pairs. On-chain quotes settle on-chain through the Payward on-chain proxy contract. - name: Ramp description: >- Hosted fiat-to-crypto on-ramp checkout: country / fiat / payment-method / cryptocurrency-asset discovery, transaction limits and prospective quotes, and the hosted checkout URL. - name: Reports description: Settlement and reconciliation reports for the partner. - name: Swaps description: >- Direct partner-to-Payward swap quotes and executions (institutional FX-style trading). - name: Travel Rule Verifications description: Travel Rule address ownership verification flows. - name: Verifications description: Identity verification (KYC) submission and status for end users. - name: Webhooks description: Manage webhook subscriptions for asynchronous event delivery. paths: /v1/accounts/{account_id}/funds/bank-links/{bank_link_id}: get: tags: - Bank Links summary: Get bank link description: >- Retrieves a Bank Link and its nested active Account Links. Unlinked links are not returned. Eligibility runs fresh on every read rather than being stored. Ownership validation is part of it: the bank account's holder must match this account's verified holder. An account that fails carries `ineligibility_reasons` such as `name_mismatch` and reports `ineligible`; an account that could not be evaluated carries none and reports `unknown`. operationId: getBankLink parameters: - in: path name: account_id required: true x-selected-account: true style: simple description: Public identifier of the account the link belongs to. example: AA23N84GGQN4WE6I schema: type: string minLength: 14 maxLength: 42 - in: path name: bank_link_id required: true style: simple description: Public bank-link id, an opaque handle. example: bal_5f4d2a8e-91a4-4d6c-8a17-9b1e2c3f4a5b schema: type: string minLength: 4 maxLength: 128 responses: '200': description: Successful response content: application/json: schema: type: object required: - data properties: data: $ref: '#/components/schemas/BankLink' description: The Bank Link with its nested active Account Links. examples: linkedBankLink: summary: Linked connection with an eligible and an ineligible account value: data: bank_link_id: bal_5f4d2a8e-91a4-4d6c-8a17-9b1e2c3f4a5b method_id: 3f9a1c2e-8b7d-4e6f-9a1b-2c3d4e5f6a7b status: linked accounts_eligibility_status: eligible linked_at: '2026-07-27T12:04:11Z' institution: name: Pacific Trust Bank account_links: - account_link_id: al_7c2b8d19-4e35-4a71-b0c6-1d8f5e9a2b34 account_last4: '4242' status: active eligibility_status: eligible eligible_rails: - ach - rtp - account_link_id: al_9e1f6a03-2c58-4bd9-8f47-3a6b0c7d5e82 account_last4: '8815' status: active eligibility_status: ineligible ineligibility_reasons: - name_mismatch not_linked_accounts: - account_last4: '5309' reason: missing_identity '400': description: Validation error content: application/json: schema: $ref: '#/components/schemas/BadRequestError' '401': description: Authentication required content: application/json: schema: $ref: '#/components/schemas/UnauthenticatedError' '403': description: Forbidden content: application/json: schema: $ref: '#/components/schemas/ForbiddenError' '404': description: Not found content: application/json: schema: $ref: '#/components/schemas/BankLinkNotFoundError' '429': description: Rate limit exceeded content: application/json: schema: $ref: '#/components/schemas/ResourceExhaustedError' '500': description: Internal server error content: application/json: schema: $ref: '#/components/schemas/InternalError' '501': description: Not implemented content: application/json: schema: $ref: '#/components/schemas/UnimplementedError' '503': description: Service unavailable content: application/json: schema: $ref: '#/components/schemas/UnavailableError' '504': description: Deadline exceeded content: application/json: schema: $ref: '#/components/schemas/DeadlineExceededError' x-codeSamples: - lang: bash source: >- curl -X GET "https://api.services.payward.com/v1/accounts/AA23N84GGQN4WE6I/funds/bank-links/bal_7c99d922-0d8a-4f0a-8612-7f47d7e5c62d" \ -H "API-Key: $PWS_API_KEY" \ -H "API-Nonce: $PWS_API_NONCE" \ -H "API-Sign: $PWS_API_SIGN" components: schemas: BankLink: title: Bank link description: >- A connection between one account and one banking institution, created through the hosted linking flow. A Bank Link owns the Account Links — the individual bank accounts — the user shared through it. Provider account and item references are never exposed. type: object required: - bank_link_id - method_id - status - accounts_eligibility_status properties: bank_link_id: description: >- Public bank-link id — an opaque handle. Stable for the life of the connection, including across reconnects. Unlinking deletes the connection at the provider, so linking the same bank account again produces a new `bank_link_id`. type: string method_id: description: Funding method this Bank Link was created for. type: string status: description: >- Lifecycle of the connection. `pending` — waiting for the user to complete the hosted widget. `activating` — the widget flow finished and the link is activating. `linked` — active and usable. `expired` — the provider connection expired or was revoked; reconnect it. `unlinked` — permanently severed; unlinked links disappear from get and list. type: string enum: - pending - activating - linked - expired - unlinked next_action: description: >- How the partner completes the link. Present while the link is `pending` and no browser has opened its hosted widget session yet — opening it claims the session, first-browser-wins, after which the URL no longer loads and this field is omitted. type: object required: - type - widget_url properties: type: type: string enum: - hosted_link widget_url: description: >- Kraken-hosted widget URL. It exposes no provider URL and no provider session token. type: string format: uri expires_at: $ref: '#/components/schemas/google.protobuf.Timestamp' description: When the hosted widget URL stops working. institution: description: >- Display-safe institution details. Provider account and item references are never exposed. type: object required: - name properties: name: description: Institution display name. type: string minLength: 1 maxLength: 256 account_links: description: Account Links owned by this Bank Link. type: array items: $ref: '#/components/schemas/AccountLink' not_linked_accounts: description: >- Accounts the user selected at the provider that could not be linked under this Bank Link. They hold no `account_link_id`, are excluded from `account_links` and from `accounts_eligibility_status`, and can never move money. Surfaced so a partner can tell the user that an account they picked was left out. Absent or empty when every selected account linked. type: array items: description: An account selected at the provider that could not be linked. type: object required: - account_last4 - reason properties: account_last4: description: >- The account's last four digits, safe to display. May be empty when the provider reported none. type: string reason: description: >- Safe reason the account could not be linked. Known values are `missing_identity` — the provider could not verify the account holder's identity for this account — `missing_balance` — the provider could not read the account's balance — and `unknown`. New reasons may be introduced over time; treat any unrecognized value as `unknown`. type: string accounts_eligibility_status: description: >- Whether any Account Link under this Bank Link can move money: the fold of the accounts' own `eligibility_status`. Always present. `eligible` — at least one account is eligible. `ineligible` — every account is conclusively ruled out, as a link that finished linking without a single account vacuously is. `unknown` — no account is confirmed eligible while at least one is still inconclusive, because its ownership or its rails were not evaluated. A `pending` link has no accounts to evaluate yet, so it reports `unknown` rather than the denial `ineligible` would be. Informational, like the per-account `eligibility_status` it folds: payouts are gated on connection and account status, not on this value. type: string enum: - eligible - ineligible - unknown linked_at: $ref: '#/components/schemas/google.protobuf.Timestamp' description: >- When the connection became active. Absent until the link finishes linking. expires_at: $ref: '#/components/schemas/google.protobuf.Timestamp' description: >- When the connection is due to expire, if the provider has reported an expiry. BadRequestError: description: Request validation failed or the request could not be processed. allOf: - $ref: '#/components/schemas/PwsValidationErrorEnvelope' - type: object required: - error properties: error: allOf: - $ref: '#/components/schemas/PwsValidationError' - type: object required: - status - code properties: status: type: integer format: int32 enum: - 400 code: type: string enum: - bad_request UnauthenticatedError: description: Authentication credentials are missing, invalid, or not accepted. allOf: - $ref: '#/components/schemas/PwsGeneralErrorEnvelope' - type: object required: - error properties: error: allOf: - $ref: '#/components/schemas/PwsGeneralError' - type: object required: - status - code properties: status: type: integer format: int32 enum: - 401 code: type: string enum: - unauthenticated ForbiddenError: description: The caller is not allowed to perform this operation. oneOf: - title: Forbidden allOf: - $ref: '#/components/schemas/PwsGeneralErrorEnvelope' - type: object required: - error properties: error: allOf: - $ref: '#/components/schemas/PwsGeneralError' - type: object required: - status - code properties: status: type: integer format: int32 enum: - 403 code: type: string enum: - forbidden - $ref: '#/components/schemas/GatewayError' BankLinkNotFoundError: description: >- The bank link does not exist, was unlinked, or belongs to another account. Not retryable. allOf: - $ref: '#/components/schemas/PwsGeneralErrorEnvelope' - type: object required: - error properties: error: allOf: - $ref: '#/components/schemas/PwsGeneralError' - type: object required: - status - code properties: status: type: integer format: int32 enum: - 404 code: type: string enum: - bank_link_not_found ResourceExhaustedError: description: The request was rate limited or a resource quota was exhausted. allOf: - $ref: '#/components/schemas/PwsGeneralErrorEnvelope' - type: object required: - error properties: error: allOf: - $ref: '#/components/schemas/PwsGeneralError' - type: object required: - status - code properties: status: type: integer format: int32 enum: - 429 code: type: string enum: - resource_exhausted InternalError: description: An unexpected server-side error occurred. allOf: - $ref: '#/components/schemas/PwsGeneralErrorEnvelope' - type: object required: - error properties: error: allOf: - $ref: '#/components/schemas/PwsGeneralError' - type: object required: - status - code properties: status: type: integer format: int32 enum: - 500 code: type: string enum: - internal UnimplementedError: description: The operation is not implemented by the upstream service. allOf: - $ref: '#/components/schemas/PwsGeneralErrorEnvelope' - type: object required: - error properties: error: allOf: - $ref: '#/components/schemas/PwsGeneralError' - type: object required: - status - code properties: status: type: integer format: int32 enum: - 501 code: type: string enum: - unimplemented UnavailableError: description: The service is temporarily unavailable. allOf: - $ref: '#/components/schemas/PwsGeneralErrorEnvelope' - type: object required: - error properties: error: allOf: - $ref: '#/components/schemas/PwsGeneralError' - type: object required: - status - code properties: status: type: integer format: int32 enum: - 503 code: type: string enum: - unavailable DeadlineExceededError: description: The upstream service did not complete the request before the deadline. allOf: - $ref: '#/components/schemas/PwsGeneralErrorEnvelope' - type: object required: - error properties: error: allOf: - $ref: '#/components/schemas/PwsGeneralError' - type: object required: - status - code properties: status: type: integer format: int32 enum: - 504 code: type: string enum: - deadline_exceeded google.protobuf.Timestamp: description: RFC 3339 timestamp. type: string format: date-time AccountLink: title: Account link description: >- One bank account shared under a Bank Link — a checking account, for example. Reference it by `account_link_id` when you move money. type: object required: - account_link_id - account_last4 - status - eligibility_status properties: account_link_id: description: >- Public account-link id — an opaque handle. Stable while the account stays shared. Once the account is removed or the Bank Link is unlinked, linking the same bank account again produces a new `account_link_id`; the old id remains valid only for reading history. type: string account_last4: description: The account's last four digits, safe to display. type: string status: description: >- `active` — the user currently shares this account. `removed` — the user stopped sharing it, a reconnect no longer included it, or the Bank Link was unlinked. type: string enum: - active - removed eligible_rails: description: >- Rails this account can currently use. Values are provider-neutral method identifiers such as `ach` or `rtp`. type: array items: type: string ineligibility_reasons: description: >- Safe reasons why no rail is eligible, such as `name_mismatch` when ownership validation fails. Empty when at least one rail is eligible or eligibility has not yet been evaluated. type: array items: type: string eligibility_status: $ref: '#/components/schemas/AccountEligibilityStatus' description: >- Whether this account can move money, from its own ownership validation and rail capability. Always present, and consistent with this account's `eligible_rails` and `ineligibility_reasons`. Informational: a payout is accepted or rejected on the Bank Link's connection status and this account's `status`, never on this value. An account reporting `unknown` can still complete a payout, and one reporting `eligible` is still rejected if the connection has since expired or been revoked. PwsValidationErrorEnvelope: description: Error envelope for request validation failures. type: object required: - error properties: error: $ref: '#/components/schemas/PwsValidationError' description: Validation error details. PwsValidationError: description: Standard PWS API error object for request validation failures. type: object required: - type - status - instance - code properties: type: description: Machine-readable error class. type: string status: description: HTTP status code returned for this error. type: integer format: int32 instance: description: Request identifier for this specific error occurrence. type: string code: description: Stable machine-readable error code. type: string doc_url: description: Optional link to documentation for this error. type: string format: uri causes: description: Validation failures that contributed to the error. type: array items: $ref: '#/components/schemas/PwsErrorCause' PwsGeneralErrorEnvelope: description: Error envelope for operational or domain failures. type: object required: - error properties: error: $ref: '#/components/schemas/PwsGeneralError' description: General error details. PwsGeneralError: description: Standard PWS API error object for non-validation failures. allOf: - $ref: '#/components/schemas/PwsErrorBase' - type: object properties: causes: description: Additional error details, when present. type: array items: type: object additionalProperties: true GatewayError: title: Gateway type: object required: - error properties: error: type: object required: - type - status - code properties: type: type: string const: service_error status: type: integer format: int32 const: 403 code: type: string const: gateway AccountEligibilityStatus: description: >- Whether one Account Link can move money, from the two checks it is subject to. `eligible` — its owner is validated and at least one rail is known. `ineligible` — a check ruled it out, or the account is no longer linked. `unknown` — a check could not answer or has not run. type: string enum: - eligible - ineligible - unknown PwsErrorCause: description: A single request validation failure. type: object required: - field - message properties: field: description: Dot-notation path to the offending request field. type: string message: description: Human-readable explanation of the failed validation rule. type: string PwsErrorBase: description: Common fields present on every PWS API error object. type: object required: - type - status - instance - code properties: type: description: Machine-readable error class. type: string status: description: HTTP status code returned for this error. type: integer format: int32 instance: description: Request identifier for this specific error occurrence. type: string code: description: Stable machine-readable error code. type: string doc_url: description: Optional link to documentation for this error. type: string format: uri securitySchemes: ApiKey: type: apiKey name: API-Key in: header description: Your public API key. Identifies the partner making the request. ApiSign: type: apiKey name: API-Sign in: header description: HMAC signature over the request, computed with your private key. ApiNonce: type: apiKey name: API-Nonce in: header description: Monotonically increasing nonce included in the request signature. ````