Manage Payouts

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 for full documentation.

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

curl --request POST \
    --url 'https://api-sandbox.payabli.com/api/MoneyOut/authorize?forceVendorCreation=false' \
    --header 'accept: application/json' \
    --header 'content-type: application/*+json' \
    --header 'requestToken: <insert API token>' \
    --data '
{
    "paymentMethod": {
        "method": "managed"
    },
    "paymentDetails": {
        "totalAmount": 47
    },
    "vendorData": {
        "vendorNumber": "7895433"
    },
    "invoiceData": [ {
      "invoiceNumber": "54323-7",
      "netAmount": "47",
      "attachments": [
        {
          "ftype": "pdf",
          "filename": "the-bill.pdf",
          "furl": "https://mysite.com/the-bill.pdf"
        }
      ]
    }
    ],
    "entryPoint": "48acde49",
    "orderDescription": "paying Michelle!"
}
'

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.

{
  "responseText": "Success",
  "isSuccess": true,
  "responseData": {
    "referenceId": "129-219",
    "resultCode": 1,
    "resultText": "Authorized",
    "customerId": 53
  }
}

​

Send bill image with payout authorization

For the smoothest payout experience, Payabli recommends always sending an image of a vendor bill. If you use Payabli’s bill engine, 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

​

Capture a payout transaction

Send a POST 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.

curl --request GET \
     --url https://api-sandbox.payabli.com/api/MoneyOut/capture/129-219 \
     --header 'accept: application/json' \
     --header 'requestToken: <insert API token>'

A successful request returns a JSON response.

{
  "responseText": "Success",
  "isSuccess": true,
  "responseData": {
    "authCode": null,
    "referenceId": "129-219",
    "resultCode": 1,
    "resultText": "Captured",
    "avsResponseText": null,
    "cvvResponseText": null,
    "customerId": 53
  }
}

​

Cancel a payout transaction

Send a POST 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. 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.

curl --request GET \
     --url https://api-sandbox.payabli.com/api/MoneyOut/cancel/129-219 \
     --header 'accept: application/json' \
     --header 'requestToken: <insert API token>'

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

{
  "isSuccess": true,
  "responseText": "Success",
  "pageIdentifier": "string",
  "responseData": {
    "ReferenceId": "45-erre-324",
    "ResultCode": "1",
    "ResultText": "Approved",
    "CustomerId": 0
  }
}