# Manage payouts with the API

> Execute vendor payments with precision through a two-step authorize-and-capture flow. Process payouts via virtual card, ACH, or check with support for multiple invoices per transaction

<AudienceInfo audiences={['developers']} />

Use Payabli's payout functions to authorize, capture, and cancel vendor payment transactions. This guide covers the complete payout lifecycle through the API.

## Considerations

Keep these considerations in mind when working with payouts:

* Payouts follow a two-step process: authorize then capture.
* You can include multiple invoices on a payout request, provided that the invoices are for the same vendor.
* At this time, you can make payouts to US and Canadian vendors only. Only paper check payments are available for Canadian vendors.
* Payout processing supports ASCII characters only. Don't send non-ASCII characters in any fields related to payout processing.

## Authorize a payout request

A payout request starts the process for paying vendors. Creating a payout request authorizes it immediately, but the transaction isn't flagged for batch processing until it's captured.

Send a POST request to `/api/MoneyOut/authorize` to create a new payout authorization. See the [API reference](/developers/api-reference/moneyout/authorize-a-transaction-for-payout) for full documentation.

<Tabs>
  <Tab title="Simple payout authorization">
    This example authorizes a payout. The amount is \$47, the vendor number is 7895433, and the only invoice being paid is 54323.

    <EndpointRequestSnippet endpoint="POST /MoneyOut/authorize" example="AuthorizePayout" />
  </Tab>

  <Tab title="Payout authorization with stored ACH">
    This example authorizes a payout using a stored ACH payment method. The amount is \$47, the vendor number is 7895433, and the only invoice being paid is 54323.

    <EndpointRequestSnippet endpoint="POST /MoneyOut/authorize" example="StoredACH" />
  </Tab>
</Tabs>

A successful request returns a JSON response. You need the referenceId from the response to capture the transaction. In this example, the ID is 129-219.

<EndpointResponseSnippet endpoint="POST /MoneyOut/authorize" example="AuthorizePayout" />

### Send bill image with payout authorization

For the smoothest payout experience, Payabli recommends to always attach an image of a bill in the `invoiceData` object. For example:

<EndpointRequestSnippet endpoint="POST /MoneyOut/authorize" example="WithImage" />

If you use Payabli's [bill engine](/guides/pay-out-developer-bills-manage), you can add the bill image when you create the bill. If not, you can include a bill image with your payout authorization request.

You have two options for attaching the image:

* Base64-encoded string
* A publicly accessible fURL where the file is hosted

How you attached the image affects how Payabli handles the file. The table below summarizes the differences between the two methods.

| Method         | doNotCreateBills is true                                                                                                                                                                                                      | doNotCreateBills is false                                                                                                                                                                                                                                     |
| -------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Base64-encoded | Payabli doesn't save a file for the base64-encoded content. During the money out capture process, Payabli sends out the capture to the payout processor without any file information.                                         | Payabli stores base64-encoded content as a file. During the capture process, Payabli generates a publicly accessible URL for the file and sends it to the payout processor.                                                                                   |
| fURL           | If you have the file hosted publicly, you can send the file's URL as the `fURL` instead. Payabli doesn't save the file. During the capture process, Payabli passes the URL you sent with the request to the payout processor. | If you have the file hosted publicly, you can send the file's URL instead. Payabli uses the URL from the request to save the file. During the capture process, Payabli generates a publicly accessible URL for the file and sends it to the payout processor. |

### Payouts with saved ACH payment methods

Vendors can have many stored ACH accounts, and you can send payouts to any of their accounts using `storedMethodId` in the payout request. How the process works depends on whether the vendor already exists in the system and how many ACH payment methods they have stored.

<Steps>
  <Step title="Vendor already exists">
    <Accordion title="Case 1: Vendor has exactly one ACH method stored">
      If the vendor already exists and has exactly one ACH method stored, the system automatically uses that stored method. `storedMethodId` is not required.

      ```json
      {
        "entryPoint": "48acde49",
        "source": "api",
        "paymentMethod": {
          "method": "ach"
        },
        "paymentDetails": {
          "totalAmount": 150.00
        },
        "vendorData": {
          "vendorNumber": "ACME-12345"
        }
      }
      ```
    </Accordion>

    <Accordion title="Case 2: Vendor has multiple ACH methods stored">
      If the vendor has multiple ACH methods stored, you must specify `storedMethodId` to indicate which account to use.

      ```json
      {
        "entryPoint": "48acde49",
        "source": "api",
        "paymentMethod": {
          "method": "ach",
          "storedMethodId": "4c6a4b78-72dc-4bdd-9455-b9d30f991ee1-138020"
        },
        "paymentDetails": {
          "totalAmount": 150.00
        },
        "vendorData": {
          "vendorNumber": "ACME-12345"
        }
      }
      ```
    </Accordion>
  </Step>

  <Step title="New vendor or vendor doesn't have any ACH method stored">
    If the vendor doesn't exist or doesn't have any ACH method stored, `billingData` is used to:

    * Create a new ACH stored method in the vault
    * Use that method for the payment

    In this case, `billingData` is required and if you don't include it, you'll get an error.

    ```json
      {
        "entryPoint": "48acde49",
        "source": "api",
        "paymentMethod": {
          "method": "ach"
        },
        "paymentDetails": {
          "totalAmount": 275.50
        },
        "vendorData": {
          "vendorNumber": "SUPPLIES-789",
          "name1": "Metro Office Supplies Inc",
          "name2": "Commercial Division",
          "ein": "12-3456789",
          "phone": "555-123-4567",
          "email": "billing@metroofficesupplies.com",
          "address1": "1425 Business Park Drive",
          "address2": "Suite 200",
          "city": "Austin",
          "state": "TX",
          "zip": "78759",
          "country": "US",
          "mcc": "5943",
          "remitAddress1": "1425 Business Park Drive",
          "remitAddress2": "Accounts Payable",
          "remitCity": "Austin",
          "remitState": "TX",
          "remitZip": "78759",
          "remitCountry": "US",
          "vendorStatus": 1,
          "billingData": {
            "bankName": "Wells Fargo Bank",
            "routingAccount": "121000248",
            "accountNumber": "9876543210",
            "typeAccount": "Checking",
            "bankAccountHolderName": "Metro Office Supplies Inc"
          }
        }
      }
    ```

    In future requests for this vendor, you can use the stored method without needing to include `billingData` again. Payabli automatically saves the ACH account details as a stored method in the vault.
  </Step>
</Steps>

## Capture a payout transaction

Send a POST request to `/api/MoneyOut/capture/{referenceId}` to capture an authorized payout transaction. See the [API reference](/developers/api-reference/moneyout/capture-an-authorized-payout-transaction) for full documentation.

This example captures the authorized payout transaction with ID `129-219`.

<EndpointRequestSnippet endpoint="GET /MoneyOut/capture/{referenceId}" example="CapturePayout" />

A successful request returns a JSON response.

<EndpointResponseSnippet endpoint="GET /MoneyOut/capture/{referenceId}" example="CapturePayout" />

## Cancel a payout transaction

Send a POST request to `/api/MoneyOut/cancel/{referenceId}` to cancel a payout transaction. See the [API reference](/developers/api-reference/moneyout/cancel-a-payout-transaction) for full documentation.

You can cancel an authorized payout at any time, because it hasn't started processing. After a payout is captured, you have a small window in which you can cancel it. When the payment status has changed to `processed`, you must contact Payabli support to cancel the payout.

This example cancels the authorized payout transaction with ID `129-219`.

<EndpointRequestSnippet endpoint="GET /MoneyOut/cancel/{referenceId}" example="CancelPayout" />

A successful request returns a 200 response with a JSON body.

<EndpointResponseSnippet endpoint="GET /MoneyOut/cancel/{referenceId}" example="CancelPayout" />

## Related resources

See these related resources to help you get the most out of Payabli.

<AccordionGroup>
  <Accordion title="Related topics">
    * **[Audit payout transactions with the API](/guides/pay-out-developer-payouts-audit)** - Learn how to use the Payabli API to track and audit payout transactions
  </Accordion>
</AccordionGroup>