Create and process a single Payable

Suggest Edits

In Wingspan, you can issue payments to payees in the application or by calling the POST /payments/payable API endpoint to create the Payable, approving them, and running payroll.

Before you begin

Before you begin the Payable creation process, ensure that you have the following:

  • Collaborator ID: the collaborator ID is an identifier used to denote the payee of the payable. Collaborator IDs can be found by calling GET /payments/collaborator or you can invite a new collaborator to your project by using the POST method for the /payments/collaborator endpoint.
  • General payment details such as:
    • Payment structure: whether you are paying the payee by an hourly rate, by the number of units produced, or as a flat rate.
    • The currency that the payee is to be paid in.
    • If you need to include attachments to the line items of the Payable.
    • Gather any necessary attachments in PDF format for the Payable.
    • Your Wingspan API authorization token. The authorization token can be found on the Developer page in the Wingspan application. For more information see, Get started with the Wingspan API.
    • You policy on late fees for late payments and how frequently they occur.
    • Your policy on credit card processing fees.

To create a Payable

  1. If you need to include an attachment to the line items of a payable, call:

    POST https://api.wingspan.app/files/member/private/upload

    Headers:

    • Authorization: Bearer {token}: The bearer token for authentication and authorization.
    • Content-Type: multipart/form: Indicates the media type of the resource/data.
    • Form Data: =@"{file_path}": Represents the file that needs to be uploaded. The file path should point to the location of the file on the system.

    Note: {file_path} should be replaced with the actual path of the file. For example, '=@"/Users/jsmith/Documents/Project_1_Receipt.pdf"'.

    Request Body Parameters:

    There are no body parameters for this call.

    Example call request

    curl --request POST \
     --url https://api.wingspan.app/files/files/member/private/upload \
     --header 'Authorization: Bearer eyJhbG9AyQ' \
     --header 'Content-Type: multipart/form-data' \
     --form '=@"/Users/jsmith/Documents/Project_1_Receipt.pdf"'

    Response:

    A successful request will return an appropriate success status code (e.g., 201 Created or 200 OK) along with a JSON response containing details of the uploaded file, such as file ID, URL, and other metadata. In case of errors, appropriate HTTP status codes and error messages will be returned.

  2. In the response copy and save the fileId. The fileId is needed to attach media to the Payable.

  3. Create the Payable by calling POST https://api.wingspan.app/payments/payable.

    Headers:

    • accept: application/json: Specifies the format of the response data.
    • content-type: application/json: Indicates the media type of the resource/data.
    • Authorization: Bearer <Your_Access_Token>: This header is required for authentication. Replace <Your_Access_Token> with your actual access token.

    The example below outlines the parameters needed to create a payable for a payee that is being compensated with an hourly rate. There are many other parameter options to suit a variety of needs. For more information about Payable request body parameters, see Components of a Payable.

    Request Body Parameters:

    • collaboratorId (string): Unique identifier for the payee also known as a collaborator.
    • currency (string): Currency type (e.g., USD, CAD).
    • dueDate (string): Due date for the payment in ISO format (e.g., "2023-12-01").
    • lineItems (array of objects): List of items for which payment is to be made.
      • costPerUnit (number): Cost per unit can refer to Hourly rates, cost of an item, or a flat rate.
      • description (string): Description or reason for the payment.
      • quantity (number): Quantity of the items or number of hours.
      • reimbursableExpense (boolean): Indicates if the expense is reimbursable.
      • totalCost (number): Total cost for the line item (costPerUnit * quantity).
    • acceptedPaymentMethods (array of strings): List of payment methods that are accepted. This can be Credit, ACH, or Manual.
    • attachments (object): Any attachments associated with the payable.
      • customAttachmentIds (array of strings): List of custom attachment identifiers. If you need to attach a document to the line time, you include the fileId here.
    • invoiceNotes (string): Any notes or comments related to the payable.
    • lateFeeHandling (object): Configuration for handling late fees.
      • frequency (object): Specifies how often late fees should be applied.
      • daily (boolean): If set to true, late fees are applied daily.
      • lateFeePercentage (number): Percentage of the payable amount to be charged as a late fee.
    • notificationPreferences (object): Preferences for notifications related to the payable.
    • sendReminders (boolean): If set to true, reminders will be sent.
    • sendInvoice (boolean): If set to true, an invoice will be sent.
    • sendReceipt (boolean): If set to true, a receipt will be sent upon successful payment.
    • status (string): Current status of the payable. Set this to Draft if the Payable needs to be Approved before being sent to general payroll. Set this to Open to Approve immediately.

    Example call and Request body

    curl --request POST \
     --url https://api.wingspan.app/payments/payable \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --header 'Authorization: Bearer YOUR_FULL_ACCESS_TOKEN' \
     --data '
{
  "collaboratorId": "123",
  "currency": "USD",
  "dueDate": "2023-012-01",
  "lineItems": [
    {
      "costPerUnit": 50,
      "description": "Payment for project 1.",
      "quantity": 40,
      "reimbursableExpense": false,
      "totalCost": 2000
    },
    {
      "costPerUnit": 50,
      "description": "Payment for project 2.",
      "quantity": 25,
      "reimbursableExpense": false,
      "totalCost": 1250
    }
  ],
  "acceptedPaymentMethods": [
    "Credit",
    "ACH"
  ],
  "attachments": {
    "customAttachmentIds": [
      "789hjk"
    ]
  },
  "invoiceNotes": "This is payments for both projects 1 and 2.",
  "lateFeeHandling": {
    "frequency": {
      "daily": true
    },
    "lateFeePercentage": 5
  },
  "notificationPreferences": {
    "sendReminders": true,
    "sendInvoice": true,
    "sendReceipt": true
  },
  "status": "Draft"
}
'

    Response:

    A successful request returns a 201 Created status code along with a JSON response containing details of the created payable. In case of errors, appropriate HTTP status codes and error messages are returned.

  4. If the call is successful make note of the payableId and invoiceNumber for your personal records. It’s a good idea to keep these in an accessible location should you need to modify the Payable later on.

  5. If you have configured your payroll settings to require a single or multi-step Approval process, then the Payable must be Approved by a representative from your organization before it is entered into the pool for your next payroll run.

    You must use the user interface in the application to approve payables. To approve Payables in the Wingspan application, go to Payables and select the To approve tab.

  6. After all necessary Payables are approved, you can initiate a payroll run immediately or allow the approved Payables to run during your regularly scheduled runs. For more information on payroll settings, see Payroll settings.

  7. To run payroll immediately, call POST https://api.wingspan.app/payments/pay-approved.

Headers:

  • accept: application/json: Specifies the format of the response data.
  • content-type: application/json: Indicates the media type of the resource/data.
  • Authorization: Bearer <Your_Access_Token>: This header is required for authentication. Replace <Your_Access_Token> with your actual access token.

Request Body Parameters:

There are no body parameters for this call.

Response:

A successful request will return an appropriate success status code (e.g., 201 Created or 200 OK) along with a JSON response containing details of the Payroll Run.

Your payroll run is now complete and funds are transferred from your payroll funding account to your payees. You can review your payment history on the Payments page in the Wingspan application.

Updated 6 months ago