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.

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
  "paymentMethod": {
7
    "method": "managed"
8
  },
9
  "paymentDetails": {
10
    "totalAmount": 47
11
  },
12
  "vendorData": {
13
    "vendorNumber": "7895433"
14
  },
15
  "invoiceData": [
16
    {
17
      "billId": 54323
18
    }
19
  ],
20
  "orderDescription": "Window Painting"
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
  "responseCode": 1,
3
  "pageIdentifier": null,
4
  "roomId": 0,
5
  "isSuccess": true,
6
  "responseText": "Success",
7
  "responseData": {
8
    "authCode": null,
9
    "referenceId": "129-219",
10
    "resultCode": 1,
11
    "resultText": "Authorized",
12
    "avsResponseText": null,
13
    "cvvResponseText": null,
14
    "customerId": 0,
15
    "methodReferenceId": null
16
  }
17
}

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
  "paymentMethod": {
7
    "method": "managed"
8
  },
9
  "paymentDetails": {
10
    "totalAmount": 47
11
  },
12
  "vendorData": {
13
    "vendorNumber": "7895433"
14
  },
15
  "invoiceData": [
16
    {
17
      "billId": 54323
18
    }
19
  ],
20
  "orderDescription": "Window Painting"
21
}'

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.

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
{
2
  "entryPoint": "48acde49",
3
  "source": "api",
4
  "paymentMethod": {
5
    "method": "ach"
6
  },
7
  "paymentDetails": {
8
    "totalAmount": 150.00
9
  },
10
  "vendorData": {
11
    "vendorNumber": "ACME-12345"
12
  }
13
}

1
{
2
  "entryPoint": "48acde49",
3
  "source": "api",
4
  "paymentMethod": {
5
    "method": "ach",
6
    "storedMethodId": "4c6a4b78-72dc-4bdd-9455-b9d30f991ee1-138020"
7
  },
8
  "paymentDetails": {
9
    "totalAmount": 150.00
10
  },
11
  "vendorData": {
12
    "vendorNumber": "ACME-12345"
13
  }
14
}

1
  {
2
    "entryPoint": "48acde49",
3
    "source": "api",
4
    "paymentMethod": {
5
      "method": "ach"
6
    },
7
    "paymentDetails": {
8
      "totalAmount": 275.50
9
    },
10
    "vendorData": {
11
      "vendorNumber": "SUPPLIES-789",
12
      "name1": "Metro Office Supplies Inc",
13
      "name2": "Commercial Division",
14
      "ein": "12-3456789",
15
      "phone": "555-123-4567",
16
      "email": "billing@metroofficesupplies.com",
17
      "address1": "1425 Business Park Drive",
18
      "address2": "Suite 200",
19
      "city": "Austin",
20
      "state": "TX",
21
      "zip": "78759",
22
      "country": "US",
23
      "mcc": "5943",
24
      "remitAddress1": "1425 Business Park Drive",
25
      "remitAddress2": "Accounts Payable",
26
      "remitCity": "Austin",
27
      "remitState": "TX",
28
      "remitZip": "78759",
29
      "remitCountry": "US",
30
      "vendorStatus": 1,
31
      "billingData": {
32
        "bankName": "Wells Fargo Bank",
33
        "routingAccount": "121000248",
34
        "accountNumber": "9876543210",
35
        "typeAccount": "Checking",
36
        "bankAccountHolderName": "Metro Office Supplies Inc"
37
      }
38
    }
39
  }

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" />