@wingspan/payments

SDK Installation

NPM

npm add @wingspan/payments

Yarn

yarn add @wingspan/payments

SDK Example Usage

Example

import { Payments } from "@wingspan/payments";

async function run() {
    const sdk = new Payments({
        bearerAuth: "<YOUR_BEARER_TOKEN_HERE>",
    });

    const result = await sdk.serviceSettings.get();

    // Handle the result
    console.log(result);
}

run();

Available Resources and Operations

serviceSettings

• get - Check Service Status

wingspanWallet

• create - Register a New Wingspan Wallet Card
• delete - Remove a card using its unique ID
• get - Retrieve card details by its unique ID
• list - List All Stored Wingspan Wallet Cards
• request - Request a verification code for card authentication
• update - Modify card details by its unique ID
• validate - Validate verification code to receive a token

deprecated

• ~~create~~ - Register New Custom Data for Collaborator-Member Relationship :warning: Deprecated
• ~~delete~~ - Erase a Specific Collaborator-Member Custom Data :warning: Deprecated
• deleteInstantPayout - Deprecated Remove Instant Payout Configuration
• ~~get~~ - Retrieve Specific Collaborator Custom Data :warning: Deprecated
• getInstantPayout - Deprecated Retrieve Instant Payout Information
• ~~list~~ - Retrieve All Collaborator-Member Custom Data Points :warning: Deprecated
• ~~update~~ - Modify a Specific Collaborator-Member Custom Data :warning: Deprecated
• updateInstantPayout - Deprecated Set Up Instant Payout Configuration

bankingManagement

• create - Register a new payout debit card for a member
• delete - Unlink and delete a specific payout debit card from a member's profile
• download - Download a specific bank statement as a PDF
• get - Retrieve Specific Bank Statement
• getApplicationLink - Fetch the application link for setting up a clearing bank account
• getDebitCard - Retrieve a specific payout debit card linked to a member
• getInstitution - Retrieve banking institution details by its routing number
• getPayoutSetting - Retrieve payout settings for a specific member
• list - Fetch all registered payout debit cards for a member
• listStatements - Retrieve All Bank Statements
• update - Modify and update payout settings for a specific member

oneThousandAndNinetyNineOperations

• calculate - Determine 1099 Amounts for Collaborators
• create - Re-enable recipient sync on a tax form.
• createBatchCalculation - Initialize a new batch for bulk calculation 1099
• createItem - Add a new item to a calculation 1099 batch
• createProof - Provide Recipient Proof of Identity
• createTaxForm - Create a new tax form.
• get - Fetch tax form.
• getBatchCalculation - Retrieve specific details of a bulk calculation 1099 batch
• getForm1099 - Retrieve Form 1099 PDF for a Collaborator by Year and Index
• getFormW9 - Retrieve Form W9 PDF for a Collaborator
• getItem - Fetch details of a specific item from a calculation 1099 batch
• listBatchCalculation - Retrieve all bulk calculation 1099 batches
• listItem - Retrieve all items from a calculation 1099 batch
• listTaxForm - Fetch 1099 tax forms.
• mark - Indicate a collaborator's 1099 form was returned undelivered
• remail - Request a new mailing of the 1099 form for a collaborator
• request - Request a new 1099 invite email.
• submit - Submit Payee TIN for verification
• update - Update a tax form.
• updateBatchCalculation - Modify the details of a specific bulk calculation 1099 batch
• updateItem - Revise the attributes of an item in a calculation 1099 batch
• updateW9 - Submit Payee W9 Information.

bulkOperations

• create - Initiate a New Bulk Invoice Batch
• createBatchItem - Add a new item to a specific bulk payable batch
• createClient - Create a new bulk client batch
• createClientItem - Add a New Item to a Client Batch
• createCollaborator - Initiate a new bulk collaborator batch.
• createPayable - Initiate a New Bulk Payable Batch
• createSpecificCollaboratorItem - Append a new item to a specific collaborator batch
• createSpecificInvoice - Add a new item to a specific bulk invoice batch
• deleteCollaborator - Remove a Specific Collaborator Batch
• deletePayable - Remove a Specific Bulk Payable Batch
• get - Retrieve details of a specific bulk invoice batch
• getBatchItem - Fetch the import summary for a specific bulk payable batch
• getClient - Fetch Details of a Specific Item from a Client Batch
• getClientItem - Fetch Details of a Specific Item from a Client Batch
• getCollaborator - Retrieve Details of a Specific Collaborator Batch
• getPayable - Retrieve Details of a Specific Bulk Payable Batch
• getSpecific - Retrieve a Specific Item from a Bulk Payable Batch
• getSpecificCollaboratorItem - Retrieve details of a specific item from a collaborator batch
• getSpecificInvoice - Retrieve a specific item from a bulk invoice batch
• list - Retrieve All Bulk Invoice Batches
• listBatchItem - Retrieve all items from a specific bulk payable batch
• listClient - Retrieve all bulk client batches
• listClientItem - Retrieve All Items from a Client Batch
• listCollaborator - Fetch all bulk collaborator batches
• listPayable - Retrieve All Bulk Payable Batches
• listSpecificCollaboratorItem - Retrieve all items from a specific collaborator batch
• listSpecificInvoice - Fetch all items from a specific bulk invoice batch
• update - Modify the details of a specific bulk invoice batch
• updateClient - Modify Details of a Specific Item in a Client Batch
• updateClientItem - Modify Details of a Specific Item in a Client Batch
• updateCollaborator - Modify Details of a Bulk Collaborator Batch
• updatePayable - Modify a Specific Bulk Payable Batch
• updateSpecific - Modify a Specific Item in a Bulk Payable Batch
• updateSpecificCollaboratorItem - Modify the details of a specific item within a collaborator batch
• updateSpecificInvoice - Modify a specific item within a bulk invoice batch

clientManagement

• create - Register a New Client Deduction
• deleteAssociation - Remove a specific member-client relationship from the system
• deleteClientDeduction - Remove a Client Deduction
• establish - Establish a new association between a member and client
• getAssociation - Retrieve detailed information of a specific member-client relationship
• getClientDeduction - Fetch Specific Client Deduction Details
• list - Retrieve All Clients (Version 2)
• listAssociations - Fetch a list of member and client associations
• listClientDeduction - Retrieve All Client Deductions
• listSpecificClientDetail - Retrieve Specific Client Details (Version 2)
• updateAssociation - Update information of a specific member-client relationship
• updateClientDeduction - Modify a Client Deduction

invoiceManagement

• create - Initiate New Invoice for a Member
• createClient - Create a new client-generated invoice template
• createGenerated - Generate a New Invoice on Behalf of the Client
• createTemplate - Create a new invoice template
• delete - Remove Invoice Record by ID
• deleteTemplate - Remove a specific invoice template
• execute - Execute Payment for a Client-Generated Invoice
• generate - Generate a PDF for a specific invoice
• generateTest - Generate Test Invoice for a Client
• get - Fetch Invoice by ID
• getClient - Fetch a specific client-generated invoice template by ID
• getFees - Retrieve Fees Associated with a Client's Invoice
• getGenerated - Fetch Specific Client-Generated Invoice by ID
• getMember - Retrieve All Member Invoices
• getTemplate - Retrieve a specific invoice template by ID
• list - Retrieve All Invoices Generated by a Client
• listClient - Retrieve all client-generated invoice templates
• listTemplates - Retrieve all available invoice templates
• refund - Refund a deposited invoice
• send - Send an invoice by email
• update - Modify Existing Invoice Details
• updateClient - Modify a client-generated invoice template
• updateGenerated - Modify an Existing Client-Generated Invoice
• updateTemplate - Modify details of an existing invoice template

collaboratorManagement

• associate - Associate Collaborator with a Specific Group
• create - Register a New Collaborator
• createCollaboratorDeduction - Register a New Deduction for a Collaborator
• createCollaboratorGroup - Generate New Collaborator Group
• delete - Remove a Specific Collaborator Record
• deleteCollaboratorDeduction - Erase a Specific Deduction Entry
• disassociate - Disassociate Collaborator from a Specific Group
• get - Retrieve Details of a Specific Collaborator
• getCollaboratorDeduction - Retrieve Specific Deduction Details
• getEventAssociated - Retrieve Events Associated with a Collaborator
• list - Retrieve All Collaborators (Version 2)
• listCollaboratorDeduction - Retrieve All Deductions for Collaborators
• listCollaboratorGroups - Retrieve All Collaborator Groups
• listRegistered - Retrieve All Registered Collaborators
• listSpecificCollaboratorDetail - Retrieve Specific Collaborator Details (Version 2)
• update - Modify Collaborator Details
• updateCollaboratorDeduction - Modify Details of a Specific Deduction

documentSigningAndEligibility

• create - Add a New Payment Eligibility Requirement
• delete - Remove a Specific Eligibility Requirement
• deleteCollaboratorGroup - Remove Eligibility Requirement from Collaborator Group
• deletePayment - Remove a specific Payment Eligibility Requirement
• establish - Establish a new Eligibility Requirement
• get - Retrieve a Specific Eligibility Requirement
• getGroupConfiguration - Retrieve Specific Collaborator Group Configuration
• getPayment - Retrieve details of a specific Payment Eligibility Requirement
• list - Retrieve all Eligibility Requirements
• listPayment - Retrieve All Payment Eligibility Requirements
• update - Modify a Specific Eligibility Requirement
• updateCollaboratorGroup - Modify Eligibility Requirement for Collaborator Group
• updateGroupConfiguration - Modify Collaborator Group Configuration
• updatePayment - Modify a specific Payment Eligibility Requirement

customFieldManagement

• create - Add a New Custom Field
• delete - Remove a Specific Custom Field
• get - Fetch Details of a Specific Custom Field
• list - Retrieve All Custom Fields
• update - Modify Details of a Specific Custom Field

merchantCategoryCodes

• get - Retrieve Merchant Category Codes (MCC)

payablesManagement

• create - Create a New Payable for a Member on Behalf of a Client
• delete - Delete Client Payable by Payable ID
• execute - Execute Approved Payroll Transactions
• get - Retrieve Payable Details by Payable ID
• getApproved - Retrieve Approved Payables Ready for Immediate Payroll
• list - List All Payables Associated with a Client
• listSummary - Retrieve Summary of All Payables
• update - Update Client Payable Information by Payable ID

payrollSettings

• get - Retrieve Individual Payroll Settings
• update - Modify Existing Payroll Settings

reportingAndAnalytics

• get - Obtain a summarized report of payable amounts for each collaborator
• getPayrollReport - Extract detailed report of payables associated with a particular payroll run
• listDetailedCollaborator - Retrieve detailed information on all collaborators
• listLineItem - Obtain Aging Report for Line Items
• listPayable - Retrieve Aging Report for Payables

Error Handling

All SDK methods return a response object or throw an error. If Error objects are specified in your OpenAPI Spec, the SDK will throw the appropriate Error type.

| Error Object | Status Code | Content Type | | --------------- | --------------- | --------------- | | errors.SDKError | 4xx-5xx | / |

Validation errors can also occur when either method arguments or data returned from the server do not match the expected format. The SDKValidationError that is thrown as a result will capture the raw value that failed validation in an attribute called rawValue. Additionally, a pretty() method is available on this error that can be used to log a nicely formatted string since validation errors can list many issues and the plain error string may be difficult read when debugging.

import { Payments } from "@wingspan/payments";
import * as errors from "@wingspan/payments/sdk/models/errors";

async function run() {
    const sdk = new Payments({
        bearerAuth: "<YOUR_BEARER_TOKEN_HERE>",
    });

    let result;
    try {
        result = await sdk.serviceSettings.get();
    } catch (err) {
        switch (true) {
            case err instanceof errors.SDKValidationError: {
                // Validation errors can be pretty-printed
                console.error(err.pretty());
                // Raw value may also be inspected
                console.error(err.rawValue);
                return;
            }
            default: {
                throw err;
            }
        }
    }

    // Handle the result
    console.log(result);
}

run();

Server Selection

Select Server by Name

You can override the default server globally by passing a server name to the server optional parameter when initializing the SDK client instance. The selected server will then be used as the default on the operations that use it. This table lists the names associated with the available servers:

| Name | Server | Variables | | ----- | ------ | --------- | | prod | https://api.wingspan.app | None | | staging | https://stagingapi.wingspan.app | None |

import { Payments } from "@wingspan/payments";

async function run() {
    const sdk = new Payments({
        server: "staging",
        bearerAuth: "<YOUR_BEARER_TOKEN_HERE>",
    });

    const result = await sdk.serviceSettings.get();

    // Handle the result
    console.log(result);
}

run();

Override Server URL Per-Client

The default server can also be overridden globally by passing a URL to the serverURL optional parameter when initializing the SDK client instance. For example:

import { Payments } from "@wingspan/payments";

async function run() {
    const sdk = new Payments({
        serverURL: "https://api.wingspan.app",
        bearerAuth: "<YOUR_BEARER_TOKEN_HERE>",
    });

    const result = await sdk.serviceSettings.get();

    // Handle the result
    console.log(result);
}

run();

Custom HTTP Client

The TypeScript SDK makes API calls using an HTTPClient that wraps the native Fetch API. This client is a thin wrapper around fetch and provides the ability to attach hooks around the request lifecycle that can be used to modify the request or handle errors and response.

The HTTPClient constructor takes an optional fetcher argument that can be used to integrate a third-party HTTP client or when writing tests to mock out the HTTP client and feed in fixtures.

The following example shows how to use the "beforeRequest" hook to to add a custom header and a timeout to requests and how to use the "requestError" hook to log errors:

import { Payments } from "@wingspan/payments";
import { HTTPClient } from "@wingspan/payments/lib/http";

const httpClient = new HTTPClient({
  // fetcher takes a function that has the same signature as native `fetch`.
  fetcher: (request) => {
    return fetch(request);
  }
});

httpClient.addHook("beforeRequest", (request) => {
  const nextRequest = new Request(request, {
    signal: request.signal || AbortSignal.timeout(5000);
  });

  nextRequest.headers.set("x-custom-header", "custom value");

  return nextRequest;
});

httpClient.addHook("requestError", (error, request) => {
  console.group("Request Error");
  console.log("Reason:", `${error}`);
  console.log("Endpoint:", `${request.method} ${request.url}`);
  console.groupEnd();
});

const sdk = new Payments({ httpClient });

Authentication

Per-Client Security Schemes

This SDK supports the following security scheme globally:

| Name | Type | Scheme | | ------------ | ------------ | ------------ | | bearerAuth | http | HTTP Bearer |

To authenticate with the API the bearerAuth parameter must be set when initializing the SDK client instance. For example:

import { Payments } from "@wingspan/payments";

async function run() {
    const sdk = new Payments({
        bearerAuth: "<YOUR_BEARER_TOKEN_HERE>",
    });

    const result = await sdk.serviceSettings.get();

    // Handle the result
    console.log(result);
}

run();

Requirements

For supported JavaScript runtimes, please consult RUNTIMES.md.

Development

Maturity

This SDK is in beta, and there may be breaking changes between versions without a major version update. Therefore, we recommend pinning usage to a specific package version. This way, you can install the same version each time without breaking changes unless you are intentionally looking for the latest version.

Contributions

While we value open-source contributions to this SDK, this library is generated programmatically. Feel free to open a PR or a Github issue as a proof of concept and we'll do our best to include it in a future release!

SDK Created by Speakeasy