Fifth Third Bancorp Virtual Reference Numbers API

VRNs act as aliases for accounts, enabling unique use cases like accounts receivable segmentation or reconciliation. **Endpoints:** - GET [List Virtual Reference Numbers: GET /virtual_reference_numbers](https://developers.newline53.com/reference/get_virtual-reference-numbers) - POST [Create a new Virtual Reference Number: POST /virtual_reference_numbers](https://developers.newline53.com/reference/post_virtual-reference-numbers) - GET [Get a single Virtual Reference Number: GET /virtual_reference_numbers/{uid}](https://developers.newline53.com/reference/get_virtual-reference-numbers-uid) - PUT [Edit a Virtual Reference Number: PUT /virtual_reference_numbers/{uid}](https://developers.newline53.com/reference/put_virtual-reference-numbers-uid) - DELETE [Archive a Virtual Reference Number: DELETE /virtual_reference_numbers/{uid}](https://developers.newline53.com/reference/delete_virtual-reference-numbers-uid) - PUT [Lock a Virtual Reference Number: PUT /virtual_reference_numbers/{uid}/lock](https://developers.newline53.com/reference/put_virtual-reference-numbers-uid-lock) - PUT [Unlock a Virtual Reference Number: PUT /virtual_reference_numbers/{uid}/unlock](https://developers.newline53.com/reference/put_virtual-reference-numbers-uid-unlock) Virtual Reference Numbers (or VRNs) are virtualized account numbers that point to a single deposit account. They are aliases to a Synthetic Account and can form a many-to-one relationship with their parent Synthetic Account. **Common VRNs Use Cases:** - This is to reference a stored funds product that is client-managed on a separate ledger. Clients can then provide VRNs to external merchants or counterparties who wish to pay for that stored fund's product. - This provides Clients with another layer of network-addressable account numbers with which to accept payments. This many-to-one relationship affords Clients account segmentation. For instance, one VRN is utilized for Accounts Receivable (AR) while the other is used for Accounts Payable (AP), all while referencing the same underlying Account. These same VRNs can then be aligned with Custodial Accounts transactions to allow for quick reconciliation or accounting. > **Note** > For certain payment rails, like Instant Payments, VRNs must be registered with Newline and Fifth Third before being used, as this will allow for network acceptance. Please review the fields in each API reference to confirm Instant Payment registration.

Operations 7

GET /virtual_reference_numbers List Virtual Reference Numbers #
POST /virtual_reference_numbers Create a new Virtual Reference Number #
GET /virtual_reference_numbers/{uid} Get a single Virtual Reference Number #
PUT /virtual_reference_numbers/{uid} Edit a Virtual Reference Number #
DELETE /virtual_reference_numbers/{uid} Archive a single Virtual Reference Number #
PUT /virtual_reference_numbers/{uid}/lock Lock a single Virtual Reference Number #
PUT /virtual_reference_numbers/{uid}/unlock Unlock a single Virtual Reference Number #

Documentation

📖
Documentation
https://developers.newline53.com/docs/api-authentication
📖
APIReference
https://developers.newline53.com/reference/post_auth
📖
APIReference
https://developers.newline53.com/reference/customers
📖
Documentation
https://developers.newline53.com/reference/overview-of-customer-types
📖
APIReference
https://developers.newline53.com/reference/customer-products
📖
Documentation
https://developers.newline53.com/reference/customer-product-statuses
📖
APIReference
https://developers.newline53.com/reference/products
📖
APIReference
https://developers.newline53.com/reference/pools
📖
APIReference
https://developers.newline53.com/reference/custodial-accounts
📖
Documentation
https://developers.newline53.com/reference/custodial-account-statuses
📖
APIReference
https://developers.newline53.com/reference/synthetic-accounts
📖
Documentation
https://developers.newline53.com/reference/synthetic-account-categories
📖
APIReference
https://developers.newline53.com/reference/transfers
📖
Documentation
https://developers.newline53.com/reference/transfer-statuses
📖
APIReference
https://developers.newline53.com/reference/combined-transfers
📖
APIReference
https://developers.newline53.com/reference/transactions
📖
Documentation
https://developers.newline53.com/reference/transaction-statuses-and-transaction-types
📖
APIReference
https://developers.newline53.com/reference/returns
📖
APIReference
https://developers.newline53.com/reference/virtual-reference-numbers
📖
Documentation
https://developers.newline53.com/reference/virtual-reference-number-statuses
📖
APIReference
https://developers.newline53.com/reference/sandbox
📖
Documentation
https://developers.newline53.com/docs/sandbox-walkthrough

Specifications

Work with this as data

Every API here is available over the APIs.io API and to AI agents over MCP.

MCP server

One button, every client — Claude, Cursor, VS Code and the rest.

https://apis.io/mcp

Tools for apis

7 MCP tools reach this
  • find_apisBrowse and filter every API in the catalog.
  • get_api_artifactsOne API's artifacts, grouped by type.
  • get_openapiThe primary OpenAPI for this API.
  • find_similar_apisAPIs that look like this one.
  • apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.
  • resolveTurn a domain, URL or GitHub org into the provider it belongs to.
  • find_cohortsEvery scored population of providers in the catalog.
All 92 tools →

Call it yourself

curl for this page
This API
curl "https://apis.io/api/v1/apis/fifth-third-bancorp-virtual-reference-numbers-api"
All apis
curl "https://apis.io/api/v1/apis?limit=25"

Discovery needs no key. Ratings and market analysis are Pro.

Get an API key

Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.

A second provider on the same verified email joins the account you already have.

OpenAPI Specification

fifth-third-bancorp-virtual-reference-numbers-api-openapi.yml Raw ↑
openapi: 3.2.0
info:
  title: Newline Platform Virtual Reference Numbers API
  version: 1.0.0
  description: Welcome!
servers:
- url: https://sandbox.newline53.com/api/v1
security:
- ApiKeyAuth: []
tags:
- name: Virtual Reference Numbers
  description: VRNs act as aliases for accounts, enabling unique use cases like accounts receivable segmentation or reconciliation.
paths:
  /virtual_reference_numbers:
    parameters:
    - $ref: '#/paths/~1auth/parameters/0'
    get:
      tags:
      - Virtual Reference Numbers
      summary: List Virtual Reference Numbers
      description: Retrieves a list of Virtual Reference Numbers (VRNs) associated with the specified Synthetic Account. Supports filtering by status and other attributes.
      parameters:
      - name: instant_payment_rail_registration_status
        in: query
        schema:
          type: string
          description: Registration status with Newline and Fifth Third, for RTP network acceptance.
          example: registered
          enum:
          - failed
          - pending
          - registered
          - unregistered
      - name: status
        in: query
        schema:
          description: A value indicating the overall state of this VRN.
          type: string
          example: active
          enum:
          - active
          - archived
      - name: synthetic_account_uid
        in: query
        schema:
          type: string
          description: A unique id referring to the mapped, general Synthetic Account.
          example: Dg1EPao8XukUpHG8
      - name: virtual_reference_number
        in: query
        schema:
          type: string
          description: The VRN
          example: '1234567890123456'
      responses:
        '200':
          description: A list of Virtual Reference Numbers is returned
          headers:
            x-trace-id:
              $ref: '#/paths/~1auth/post/responses/201/headers/x-trace-id'
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/paths/~1pools/get/responses/200/content/application~1json/schema/allOf/0'
                - type: object
                  properties:
                    data:
                      type: array
                      items:
                        allOf:
                        - $ref: '#/paths/~1pools~1%7Buid%7D/get/responses/200/content/application~1json/schema/allOf/0'
                        - $ref: '#/paths/~1virtual_reference_numbers/post/responses/201/content/application~1json/schema/allOf/0'
              examples:
                virtual_reference_numbers_list:
                  value:
                    total_count: 4
                    count: 2
                    limit: 2
                    offset: 0
                    data:
                    - archived_at: null
                      created_at: '2023-10-04T13:23:04.345Z'
                      custodial_account_uid: tcvYpQ1ip76LaL4a
                      external_uid: null
                      name: greenfield1
                      routing_number: '123456789'
                      instant_payment_rail_registration_status: registered
                      locked_at: '2023-10-15T15:53:13.591Z'
                      lock_reason: customer_request
                      status: active
                      synthetic_account_uid: Dg1EPao8XukUpHG8
                      uid: dYTG8WAWAh5UyvY7
                      virtual_reference_number_last_four: 3456
                    - archived_at: '2023-10-15T15:53:13.591Z'
                      created_at: '2023-10-04T13:23:04.345Z'
                      custodial_account_uid: tcvYpQ1ip76LaL4a
                      external_uid": abcdefg1
                      name: greenfield2
                      routing_number: '123456789'
                      instant_payment_rail_registration_status: registered
                      locked_at: null
                      lock_reason: null
                      status: archived
                      synthetic_account_uid: Dg1EPao8XukUpHG8
                      uid: dYTG8WAWAh5UyvY7
                      virtual_reference_number_last_four: 4321
        '422':
          description: Failed to retrieve Virtual Reference Numbers
          headers:
            x-trace-id:
              $ref: '#/paths/~1auth/post/responses/201/headers/x-trace-id'
          content:
            application/json:
              schema:
                $ref: '#/paths/~1returns/get/responses/403/content/application~1json/schema'
              examples:
                failed_to_retrieve_vrns:
                  value:
                    errors:
                    - code: 30003
                      title: Failed to retrieve VRNs
                      detail: An exception occurred while retrieving VRNs
                      occurred_at: '2023-10-04T13:23:04.345Z'
                    status: 422
      operationId: getVirtualReferenceNumbers
      x-operation-id-source: derived
    post:
      tags:
      - Virtual Reference Numbers
      summary: Create a new Virtual Reference Number
      description: Creates a new Virtual Reference Number (VRN) for the specified Synthetic Account.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                external_uid:
                  $ref: '#/paths/~1virtual_reference_numbers~1%7Buid%7D/put/requestBody/content/application~1json/schema/properties/external_uid'
                name:
                  $ref: '#/paths/~1virtual_reference_numbers~1%7Buid%7D/put/requestBody/content/application~1json/schema/properties/name'
                synthetic_account_uid:
                  type: string
                  description: A unique id referring to the mapped, general Synthetic Account.
                  example: Dg1EPao8XukUpHG8
                routing_number:
                  description: The ABA routing number associated with this VRN.
                  allOf:
                  - type: string
                    maxLength: 9
                    minLength: 9
                    pattern: ^[0-9]{9}$
                    example: '123456789'
              required:
              - synthetic_account_uid
              - routing_number
            examples:
              create_payload:
                value:
                  external_uid: YrfDrfVRgpPgnhF5
                  name: greenfield1
                  synthetic_account_uid: Dg1EPao8XukUpHG8
                  routing_number: '123456789'
      responses:
        '201':
          description: A single registered Virtual Reference Number is returned
          headers:
            x-trace-id:
              $ref: '#/paths/~1auth/post/responses/201/headers/x-trace-id'
          content:
            application/json:
              schema:
                allOf:
                - type: object
                  properties:
                    archived_at:
                      type: string
                      description: The DateTime at which this VRN was archived. This value will be present if the status is archived. If in another state, the value will be null.
                      example: null
                    created_at:
                      type: string
                      description: The DateTime at which this VRN was created
                      example: '2023-10-04T13:23:04.345Z'
                    custodial_account_uid:
                      type: string
                      description: A unique id referring to the mapped, Custodial Account.
                      example: tcvYpQ1ip76LaL4a
                    external_uid:
                      $ref: '#/paths/~1virtual_reference_numbers~1%7Buid%7D/put/requestBody/content/application~1json/schema/properties/external_uid'
                    instant_payment_rail_registration_status:
                      $ref: '#/paths/~1virtual_reference_numbers/get/parameters/0/schema'
                    locked_at:
                      type: string
                      description: The DateTime at which this VRN was locked. This value will be present if the status is locked. If in another state, the value will be null.
                      example: null
                    lock_reason:
                      type: string
                      enum:
                      - admin
                      - customer_request
                      description: Provided reason for locking the VRN.
                      example: null
                    name:
                      $ref: '#/paths/~1virtual_reference_numbers~1%7Buid%7D/put/requestBody/content/application~1json/schema/properties/name'
                    routing_number:
                      type: string
                      description: The ABA routing number (if any) associated with this VRN.
                      example: '123456789'
                    status:
                      $ref: '#/paths/~1virtual_reference_numbers/get/parameters/1/schema'
                    synthetic_account_uid:
                      $ref: '#/paths/~1virtual_reference_numbers/get/parameters/2/schema'
                    uid:
                      type: string
                      description: Unique identifier for the VRN
                      example: dYTG8WAWAh5UyvY7
                    virtual_reference_number_last_four:
                      type: string
                      description: Last 4 digits of the VRN
                      example: '3456'
                - type: object
                  properties:
                    virtual_reference_number:
                      type: string
                      description: The VRN
                      example: '1234567890123456'
              examples:
                pending:
                  value:
                    archived_at: null
                    created_at: '2023-10-04T13:23:04.345Z'
                    custodial_account_uid: tcvYpQ1ip76LaL4a
                    external_uid: null
                    instant_payment_rail_registration_status: pending
                    locked_at: null
                    lock_reason: null
                    name: greenfield1
                    routing_number: '123456789'
                    status: active
                    synthetic_account_uid: Dg1EPao8XukUpHG8
                    uid: dYTG8WAWAh5UyvY7
                    virtual_reference_number: 1234567890123456
                    virtual_reference_number_last_four: 3456
        '422':
          description: Creation Error
          headers:
            x-trace-id:
              $ref: '#/paths/~1auth/post/responses/201/headers/x-trace-id'
          content:
            application/json:
              schema:
                $ref: '#/paths/~1returns/get/responses/403/content/application~1json/schema'
              examples:
                vrn_creation_error_sync:
                  value:
                    errors:
                    - code: 30001
                      title: Failed to create VRNs
                      detail: An exception occurred while creating VRNs
                      occurred_at: '2023-10-04T13:23:04.345Z'
                    status: 422
                synthetic_account_ineligible_for_vrn:
                  value:
                    errors:
                    - code: 30002
                      title: The Synthetic Account provided is ineligible for VRNs
                      detail: The Synthetic Account must be an active, general, liability account
                      occurred_at: '2023-10-04T13:23:04.345Z'
                    status: 422
      operationId: postVirtualReferenceNumbers
      x-operation-id-source: derived
  /virtual_reference_numbers/{uid}:
    parameters:
    - $ref: '#/paths/~1auth/parameters/0'
    - $ref: '#/paths/~1pools~1%7Buid%7D/parameters/1'
    get:
      tags:
      - Virtual Reference Numbers
      summary: Get a single Virtual Reference Number
      description: Retrieves a single Virtual Reference Number resource along with its details, including status, linked Synthetic Account, and registration metadata.
      responses:
        '200':
          description: A single Virtual Reference Number is returned
          headers:
            x-trace-id:
              $ref: '#/paths/~1auth/post/responses/201/headers/x-trace-id'
          content:
            application/json:
              schema:
                $ref: '#/paths/~1virtual_reference_numbers/post/responses/201/content/application~1json/schema'
              examples:
                registered:
                  value:
                    archived_at: null
                    created_at: '2023-10-04T13:23:04.345Z'
                    custodial_account_uid: tcvYpQ1ip76LaL4a
                    external_uid: null
                    instant_payment_rail_registration_status: registered
                    locked_at: null
                    lock_reason: null
                    name: greenfield1
                    routing_number: '123456789'
                    status: active
                    synthetic_account_uid: Dg1EPao8XukUpHG8
                    uid: dYTG8WAWAh5UyvY7
                    virtual_reference_number: 1234567890123456
                    virtual_reference_number_last_four: 3456
        '404':
          description: The Virtual Reference Number is not found
          headers:
            x-trace-id:
              $ref: '#/paths/~1auth/post/responses/201/headers/x-trace-id'
          content:
            application/json:
              schema:
                $ref: '#/paths/~1returns/get/responses/403/content/application~1json/schema'
              examples:
                unknown_virtual_reference_number:
                  value:
                    errors:
                    - code: 30000
                      title: Unknown VRN
                      detail: Could not find Virtual Reference Number. Invalid VRN uid
                      occurred_at: '2023-10-04T13:23:04.345Z'
                    status: 404
      operationId: getVirtualReferenceNumbersByUid
      x-operation-id-source: derived
    put:
      tags:
      - Virtual Reference Numbers
      summary: Edit a Virtual Reference Number
      description: Updates the metadata of an existing Virtual Reference Number. This may include changes to labels, descriptions, or Instant Payment registration settings.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              properties:
                external_uid:
                  description: 'A unique identifier the Client supplies. It must be unique within the resource type. If the same value is given, no new resource will be created.

                    '
                  allOf:
                  - type: string
                    minLength: 1
                    maxLength: 255
                    description: 'A unique identifier the Client supplies. It must be unique within the resource type. If the same value is given, no new resource will be created.

                      '
                    example: partner-generated-id
                name:
                  type: string
                  description: A unique name, per pool, to identify the resource.
                  maxLength: 255
                  example: greenfield1
      responses:
        '200':
          description: The updated Virtual Reference Number resource is returned
          headers:
            x-trace-id:
              $ref: '#/paths/~1auth/post/responses/201/headers/x-trace-id'
          content:
            application/json:
              schema:
                $ref: '#/paths/~1virtual_reference_numbers/post/responses/201/content/application~1json/schema'
              examples:
                registered:
                  $ref: '#/paths/~1virtual_reference_numbers~1%7Buid%7D/get/responses/200/content/application~1json/examples/registered'
        '404':
          description: The Virtual Reference Number is not found
          headers:
            x-trace-id:
              $ref: '#/paths/~1auth/post/responses/201/headers/x-trace-id'
          content:
            application/json:
              schema:
                $ref: '#/paths/~1returns/get/responses/403/content/application~1json/schema'
              examples:
                unknown_virtual_reference_number:
                  $ref: '#/paths/~1virtual_reference_numbers~1%7Buid%7D/get/responses/404/content/application~1json/examples/unknown_virtual_reference_number'
        '422':
          description: Failed to update Virtual Reference Number
          headers:
            x-trace-id:
              $ref: '#/paths/~1auth/post/responses/201/headers/x-trace-id'
          content:
            application/json:
              schema:
                $ref: '#/paths/~1returns/get/responses/403/content/application~1json/schema'
              examples:
                failed_to_update_vrn:
                  summary: Lock operation failed
                  description: An exception occurred while updating VRNs
                  value:
                    errors:
                    - code: 30004
                      title: Failed to update VRNs
                      detail: An exception occurred while updating VRNs
                      occurred_at: '2023-10-04T13:23:04.345Z'
                    status: 422
      operationId: putVirtualReferenceNumbersByUid
      x-operation-id-source: derived
    delete:
      tags:
      - Virtual Reference Numbers
      summary: Archive a single Virtual Reference Number
      description: Archives a Virtual Reference Number, removing it from active use. Archived VRNs cannot be used for incoming payments or reconciliation.
      responses:
        '204':
          description: Virtual Reference Number is archived successfully
          headers:
            x-trace-id:
              $ref: '#/paths/~1auth/post/responses/201/headers/x-trace-id'
          content:
            application/json:
              schema:
                $ref: '#/paths/~1virtual_reference_numbers/post/responses/201/content/application~1json/schema'
              examples:
                archived:
                  value:
                    archived_at: '2023-10-15T15:53:13.591Z'
                    created_at: '2023-10-04T13:23:04.345Z'
                    custodial_account_uid: tcvYpQ1ip76LaL4a
                    external_uid": abcdefg1
                    name: greenfield2
                    routing_number: '123456789'
                    instant_payment_rail_registration_status: registered
                    locked_at: null
                    lock_reason: null
                    status: archived
                    synthetic_account_uid: Dg1EPao8XukUpHG8
                    uid: dYTG8WAWAh5UyvY7
                    virtual_reference_number: 987654321654321
                    virtual_reference_number_last_four: 4321
        '404':
          description: The Virtual Reference Number is not found
          headers:
            x-trace-id:
              $ref: '#/paths/~1auth/post/responses/201/headers/x-trace-id'
          content:
            application/json:
              schema:
                $ref: '#/paths/~1returns/get/responses/403/content/application~1json/schema'
              examples:
                unknown_virtual_reference_number:
                  $ref: '#/paths/~1virtual_reference_numbers~1%7Buid%7D/get/responses/404/content/application~1json/examples/unknown_virtual_reference_number'
      operationId: deleteVirtualReferenceNumbersByUid
      x-operation-id-source: derived
  /virtual_reference_numbers/{uid}/lock:
    parameters:
    - $ref: '#/paths/~1auth/parameters/0'
    - $ref: '#/paths/~1pools~1%7Buid%7D/parameters/1'
    put:
      tags:
      - Virtual Reference Numbers
      summary: Lock a single Virtual Reference Number
      description: Locks a Virtual Reference Number to prevent new transactions or usage. This is typically used for fraud prevention or temporary deactivation.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              properties:
                lock_reason:
                  type: string
                  enum:
                  - admin
                  - customer_request
                  description: Lock reason
                  example: disabled by client request
              required:
              - lock_reason
      responses:
        '200':
          description: The locked Virtual Reference Number resource is returned
          headers:
            x-trace-id:
              $ref: '#/paths/~1auth/post/responses/201/headers/x-trace-id'
          content:
            application/json:
              schema:
                $ref: '#/paths/~1virtual_reference_numbers/post/responses/201/content/application~1json/schema'
              examples:
                locked:
                  value:
                    archived_at: null
                    created_at: '2023-10-04T13:23:04.345Z'
                    custodial_account_uid: tcvYpQ1ip76LaL4a
                    external_uid: null
                    name: greenfield1
                    routing_number: '123456789'
                    instant_payment_rail_registration_status: registered
                    locked_at: '2023-10-15T15:53:13.591Z'
                    lock_reason: customer_request
                    status: active
                    synthetic_account_uid: Dg1EPao8XukUpHG8
                    uid: dYTG8WAWAh5UyvY7
                    virtual_reference_number: 1234567890123456,
                    virtual_reference_number_last_four: 3456
        '404':
          description: The Virtual Reference Number is not found
          headers:
            x-trace-id:
              $ref: '#/paths/~1auth/post/responses/201/headers/x-trace-id'
          content:
            application/json:
              schema:
                $ref: '#/paths/~1returns/get/responses/403/content/application~1json/schema'
              examples:
                unknown_virtual_reference_number:
                  $ref: '#/paths/~1virtual_reference_numbers~1%7Buid%7D/get/responses/404/content/application~1json/examples/unknown_virtual_reference_number'
        '422':
          description: The Virtual Reference Number could not be locked
          headers:
            x-trace-id:
              $ref: '#/paths/~1auth/post/responses/201/headers/x-trace-id'
          content:
            application/json:
              schema:
                $ref: '#/paths/~1returns/get/responses/403/content/application~1json/schema'
              examples:
                vrn_already_locked:
                  summary: VRN already locked
                  description: Returned when the VRN is already locked and cannot be locked again.
                  value:
                    errors:
                    - code: 30010
                      title: VRN is already locked
                      detail: The Virtual Reference Number is already locked and cannot be locked again
                      occurred_at: '2023-10-04T13:23:04.345Z'
                    status: 422
                vrn_lock_cooldown_active:
                  summary: Lock cooldown active
                  description: Returned when a lock cooldown is active and the VRN cannot be locked again yet.
                  value:
                    errors:
                    - code: 30017
                      title: VRN cooldown active
                      detail: VRN cannot be locked/unlocked until the cooldown period has ended
                      occurred_at: '2023-10-04T13:23:04.345Z'
                    status: 422
                virtual_reference_number_archived:
                  summary: Archived VRN
                  description: Returned when the VRN is archived and cannot be acted upon.
                  value:
                    errors:
                    - code: 30005
                      title: Archived VRN
                      detail: Cannot use archived VRN
                      occurred_at: '2023-10-04T13:23:04.345Z'
                    status: 422
                failed_to_update_vrn:
                  $ref: '#/paths/~1virtual_reference_numbers~1%7Buid%7D/put/responses/422/content/application~1json/examples/failed_to_update_vrn'
      operationId: putVirtualReferenceNumbersByUidLock
      x-operation-id-source: derived
  /virtual_reference_numbers/{uid}/unlock:
    parameters:
    - $ref: '#/paths/~1auth/parameters/0'
    - $ref: '#/paths/~1pools~1%7Buid%7D/parameters/1'
    put:
      tags:
      - Virtual Reference Numbers
      summary: Unlock a single Virtual Reference Number
      description: Unlocks a previously locked Virtual Reference Number, restoring its ability to receive payments and participate in reconciliation workflows.
      responses:
        '200':
          description: The locked Virtual Reference Number resource is returned
          headers:
            x-trace-id:
              $ref: '#/paths/~1auth/post/responses/201/headers/x-trace-id'
          content:
            application/json:
              schema:
                $ref: '#/paths/~1virtual_reference_numbers/post/responses/201/content/application~1json/schema'
              examples:
                registered:
                  $ref: '#/paths/~1virtual_reference_numbers~1%7Buid%7D/get/responses/200/content/application~1json/examples/registered'
        '404':
          description: The Virtual Reference Number is not found
          headers:
            x-trace-id:
              $ref: '#/paths/~1auth/post/responses/201/headers/x-trace-id'
          content:
            application/json:
              schema:
                $ref: '#/paths/~1returns/get/responses/403/content/application~1json/schema'
              examples:
                unknown_virtual_reference_number:
                  $ref: '#/paths/~1virtual_reference_numbers~1%7Buid%7D/get/responses/404/content/application~1json/examples/unknown_virtual_reference_number'
        '422':
          description: The Virtual Reference Number could not be unlocked
          headers:
            x-trace-id:
              $ref: '#/paths/~1auth/post/responses/201/headers/x-trace-id'
          content:
            application/json:
              schema:
                $ref: '#/paths/~1returns/get/responses/403/content/application~1json/schema'
              examples:
                vrn_already_unlocked:
                  summary: VRN already unlocked
                  description: Returned when the VRN is already unlocked and cannot be unlocked again.
                  value:
                    errors:
                    - code: 30013
                      title: VRN is already unlocked
                      detail: The Virtual Reference Number is already unlocked and cannot be unlocked again
                      occurred_at: '2023-10-04T13:23:04.345Z'
                    status: 422
                vrn_unlock_cooldown_active:
                  summary: Unlock cooldown active
                  description: Returned when a unlock cooldown is active and the VRN cannot be unlocked again yet.
                  value:
                    errors:
                    - code: 30018
                      title: VRN cooldown active
                      detail: VRN cannot be locked/unlocked until the cooldown period has ended
                      occurred_at: '2023-10-04T13:23:04.345Z'
                    status: 422
                virtual_reference_number_archived:
                  $ref: '#/paths/~1virtual_reference_numbers~1%7Buid%7D~1lock/put/responses/422/content/application~1json/examples/virtual_reference_number_archived'
                failed_to_update_vrn:
                  $ref: '#/paths/~1virtual_reference_numbers~1%7Buid%7D/put/responses/422/content/application~1json/examples/failed_to_update_vrn'
      operationId: putVirtualReferenceNumbersByUidUnlock
      x-operation-id-source: derived
components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: Authorization
      description: Access token signed with shared HMAC
x-explorer-enabled: false