Manage payouts with the API

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.

1
curl -X POST https://api-sandbox.payabli.com/api/MoneyOut/authorize \
2
     -H "requestToken: <apiKey>" \
3
     -H "Content-Type: application/json" \
4
     -d '{
5
  "entryPoint": "48acde49",
6
  "paymentDetails": {
7
    "totalAmount": 47
8
  },
9
  "vendorData": {
10
    "vendorNumber": "7895433"
11
  },
12
  "invoiceData": [
13
    {
14
      "billId": 123
15
    }
16
  ],
17
  "orderDescription": "Window Painting",
18
  "paymentMethod": {
19
    "method": "managed"
20
  }
21
}'

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.

1
{
2
  "isSuccess": true,
3
  "pageIdentifier": "null",
4
  "responseData": {
5
    "ReferenceId": "10-99",
6
    "ResultCode": 1,
7
    "ResultText": "Authorized"
8
  },
9
  "responseText": "Success"
10
}

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:

1
curl -X POST https://api-sandbox.payabli.com/api/MoneyOut/authorize \
2
     -H "requestToken: <apiKey>" \
3
     -H "Content-Type: application/json" \
4
     -d '{
5
  "entryPoint": "48acde49",
6
  "paymentDetails": {
7
    "totalAmount": 47
8
  },
9
  "vendorData": {
10
    "vendorNumber": "7895433"
11
  },
12
  "invoiceData": [
13
    {
14
      "attachments": [
15
        {
16
          "filename": "bill.pdf",
17
          "ftype": "pdf",
18
          "furl": "https://example.com/bill.pdf"
19
        }
20
      ],
21
      "billId": 123
22
    }
23
  ],
24
  "orderDescription": "Window Painting",
25
  "paymentMethod": {
26
    "method": "managed"
27
  }
28
}'

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

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

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.

A successful request returns a JSON response.

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.

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

1
<EndpointResponseSnippet
2
  endpoint="POST /MoneyOut/cancel/{referenceId}"
3
  example="CancelPayout" />