Send paymentsSend payouts

Manage payouts with the API

Learn how to use the Payabli API to create, capture, and cancel payout transactions
View as MarkdownOpen in Claude
Applies to: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.
  • For check payouts, Payabli validates the vendor’s remit (mailing) address at authorization, before the payout is charged. If validation fails, the authorization fails and Payabli doesn’t charge the paypoint. Correct the address and re-authorize. Other payout methods aren’t affected.

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. Include autoCapture: true in the request body to capture the transaction automatically after authorization.

Capture with autoCapture is asynchronous, so the authorization response confirms only that the transaction was authorized, not that capture succeeded. To confirm capture, listen for the payout_transaction_approvedcaptured webhook event.

If capture fails, Payabli emits one of these failure events instead:

Listen for these events to detect which payouts didn’t capture, and read the Reason field in the payload to see why. To retry, correct the vendor record or payout request based on the reason, then submit a new authorization. Pay Out has no refunds, and a failed payout never moves funds, so a new authorization is the recovery path.

Send a POST request to /api/MoneyOut/authorize to create a new payout authorization. See the API reference for full documentation.

This example authorizes a payout. The amount is $47, the vendor number is VEN-123, and the only invoice being paid is 54323.

POST
/api/MoneyOut/authorize
curl -X POST https://api-sandbox.payabli.com/api/MoneyOut/authorize \
     -H "Authorization: Bearer <token>" \
     -H "Content-Type: application/json" \
     -d '{
  "entryPoint": "8cfec329267",
  "paymentMethod": {
    "method": "managed"
  },
  "paymentDetails": {
    "totalAmount": 47,
    "unbundled": false
  },
  "vendorData": {
    "vendorNumber": "VEN-123"
  },
  "orderDescription": "Window Painting",
  "invoiceData": [
    {
      "billId": 54323
    }
  ],
  "autoCapture": true
}'
Try it

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.

Response
{
  "responseCode": 1,
  "pageIdentifier": null,
  "roomId": 0,
  "isSuccess": true,
  "responseText": "Success",
  "responseData": {
    "authCode": null,
    "referenceId": "129-219",
    "resultCode": 1,
    "resultText": "Authorized",
    "avsResponseText": null,
    "cvvResponseText": null,
    "customerId": 456,
    "vendorId": 456,
    "methodReferenceId": null
  }
}

For the smoothest payout experience, Payabli recommends attaching a bill image. Attach it when you create the bill, before you authorize the payout.

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.

1

Vendor already exists

If the vendor already exists and has exactly one ACH method stored, the system automatically uses that stored method. storedMethodId is not required.

{
  "entryPoint": "48acde49",
  "source": "api",
  "paymentMethod": {
    "method": "ach"
  },
  "paymentDetails": {
    "totalAmount": 150.00
  },
  "vendorData": {
    "vendorNumber": "ACME-12345"
  },
  "invoiceData": [
    {
      "billId": 6101
    }
  ]
}

If the vendor has multiple ACH methods stored, you must specify storedMethodId to indicate which account to use.

{
  "entryPoint": "48acde49",
  "source": "api",
  "paymentMethod": {
    "method": "ach",
    "storedMethodId": "4c6a4b78-72dc-4bdd-9455-b9d30f991ee1-138020"
  },
  "paymentDetails": {
    "totalAmount": 150.00
  },
  "vendorData": {
    "vendorNumber": "ACME-12345"
  },
  "invoiceData": [
    {
      "billId": 6101
    }
  ]
}
2

New vendor or vendor doesn't have a stored ACH method

Set up the vendor and its ACH method first, then authorize the payout referencing the vendor by vendorNumber.

  • New vendor: create the vendor with the account details in billingData, which saves the vendor and its ACH method together. Send a POST request to /api/Vendor/single/{entry}. See Create vendor.
  • Existing vendor without a stored method: add an ACH method to the vendor. Send a POST request to /api/TokenStorage/add with the account details in vendorData. See Save a payment method.

After the vendor has a stored method, authorize the payout the same way as a vendor with one stored method: reference the vendor by vendorNumber, and the system uses the stored method automatically.

  {
    "entryPoint": "48acde49",
    "source": "api",
    "paymentMethod": {
      "method": "ach"
    },
    "paymentDetails": {
      "totalAmount": 275.50
    },
    "vendorData": {
      "vendorNumber": "SUPPLIES-789"
    },
    "invoiceData": [
      {
        "billId": 6207
      }
    ]
  }

Apply vendor credits

To apply a vendor credit against a bill, record the credit with the bill’s discount field when you create the bill, before you authorize the payout. See Apply a credit to a bill.

Capture a payout transaction

If you didn’t set the autoCapture field to true in the payout authorization request, you need to capture the authorization manually. Send a GET request to /api/MoneyOut/capture/{referenceId} to capture an authorized payout transaction. See the API reference for full documentation.

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

GET
/api/MoneyOut/capture/:referenceId
curl https://api-sandbox.payabli.com/api/MoneyOut/capture/129-219 \
     -H "Authorization: Bearer <token>"
Try it

A successful request returns a JSON response. While a capture is in progress, the payout can briefly report a Capturing status before it moves to Captured. See Pay Out statuses.

Response
{
  "responseCode": 1,
  "pageIdentifier": null,
  "roomId": 0,
  "isSuccess": true,
  "responseText": "Success",
  "responseData": {
    "authCode": null,
    "referenceId": "129-219",
    "resultCode": 1,
    "resultText": "Captured",
    "avsResponseText": null,
    "cvvResponseText": null,
    "customerId": 456,
    "vendorId": 456,
    "methodReferenceId": null
  }
}

Risk policies can change the capture response:

  • Held for review: A velocity fraud alert returns a 202 response with responseCode 9051 and isSuccess: false. The capture is accepted and held for risk review rather than rejected. Contact the Support team to resolve fraud limits.
  • Blocked: A blocking risk policy returns a 422 response with responseCode 9005 and isSuccess: false. This is a terminal rejection. Contact the Support team to clarify the status of your paypoint.

Authorize and capture in one call

Send a POST request to /api/MoneyOut/payout to authorize and capture a payout in a single call. The response is the capture result, so you get the capture outcome synchronously instead of authorizing and then capturing in a separate request. Risk and fraud review still runs at both the authorize and capture stages. See the API reference for full documentation.

When to use each option

You want toUse
Authorize and capture together, and get the capture result backPOST /MoneyOut/payout
Authorize now and decide later whether to capturePOST /MoneyOut/authorize, then GET /MoneyOut/capture/{referenceId}
Authorize and capture together, but you don’t need the capture result in the responsePOST /MoneyOut/authorize with autoCapture: true

The request body is the same as Authorize a payout request. Payabli ignores autoCapture in the body, since this endpoint always captures inline.

POST
/api/MoneyOut/payout
curl -X POST https://api-sandbox.payabli.com/api/MoneyOut/payout \
     -H "Authorization: Bearer <token>" \
     -H "Content-Type: application/json" \
     -d '{
  "entryPoint": "8cfec329267",
  "paymentMethod": {
    "method": "managed"
  },
  "paymentDetails": {
    "totalAmount": 47
  },
  "vendorData": {
    "vendorNumber": "VEN-123"
  },
  "orderDescription": "Window Painting",
  "invoiceData": [
    {
      "billId": 54323
    }
  ]
}'
Try it

A successful request returns the capture response, including the referenceId of the captured payout.

Response
{
  "responseCode": 1,
  "pageIdentifier": null,
  "roomId": 0,
  "isSuccess": true,
  "responseText": "Success",
  "responseData": {
    "authCode": null,
    "referenceId": "129-219",
    "resultCode": 1,
    "resultText": "Captured",
    "avsResponseText": null,
    "cvvResponseText": null,
    "customerId": 456,
    "vendorId": 456,
    "methodReferenceId": null
  }
}

If the capture fails, the response is the capture error, but the authorization still stands. Payabli completes the authorization before the capture begins, so a failed capture leaves the payout authorized and you can still capture it. Retry with GET /MoneyOut/capture/{referenceId} using the referenceId from the error response, rather than resubmitting the payout, which would create a second one.

Cancel a payout transaction

Pay Out transactions don’t support refunds. You can cancel a payout before or shortly after capture, but once the payment status has changed to processed, the transaction can’t be reversed. To recoup funds from a processed payout, you’d need to collect a Pay In payment from the vendor. If you need to resend the payout with a different payment method, you can reissue the transaction instead.

Send a GET request to /api/MoneyOut/cancel/{referenceId} to cancel a payout transaction. See the API reference 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.

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

GET
/api/MoneyOut/cancel/:referenceId
curl https://api-sandbox.payabli.com/api/MoneyOut/cancel/129-219 \
     -H "Authorization: Bearer <token>"
Try it

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

Response
{
  "responseText": "Success",
  "isSuccess": true,
  "pageIdentifier": null,
  "responseData": {
    "AuthCode": null,
    "avsResponseText": null,
    "CustomerId": 456,
    "VendorId": 456,
    "cvvResponseText": null,
    "methodReferenceId": null,
    "ReferenceId": "129-219",
    "ResultCode": 1,
    "ResultText": "Approved"
  }
}

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