Cookbooks and recipes home

/// Step 1: Get your API token

Navigate to PartnerHub > Developers > API Tokens and create a new organization token. Your API tokens carry privileges, so keep them secure!

Your token will look something like this: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

/// Step 2: Add token to request headers

Send the API token in the request header with the key requestToken. All API requests must be made over HTTPS.

$
curl -X POST "https://api.payabli.com/api/ExampleEndpoint/authorize" \
>
  -H "Content-Type: application/json" \
>
  -H "requestToken: YOUR_API_TOKEN"

/// Step 3: Add idempotency key (recommended)

Include a unique idempotencyKey header to prevent duplicate transactions. This key persists for 2 minutes.

$
curl -X POST "https://api.payabli.com/api/ExampleEndpoint/authorize" \
>
  -H "Content-Type: application/json" \
>
  -H "requestToken: YOUR_API_TOKEN" \
>
  -H "idempotencyKey: unique-request-id-123"

Learn more about authentication, API tokens, and idempotency in API overview.

/// Overview

This complete end-to-end workflow walks through how to send a payment to a vendor using ACH.

/// Step 1: Create a vendor

First, make sure that you have a vendor record. If you already have a vendorNumber, you can skip to step 2.

To create a vendor, send a POST request to /api/Vendor/single/{entry}.

$
curl -X POST "https://api.payabli.com/api/Vendor/single/your-entry-point" \
>
  -H "Content-Type: application/json" \
>
  -H "requestToken: YOUR_API_TOKEN" \
>
  -d '{
>
    "vendorNumber": "V-001",
>
    "name1": "My First Vendor",
>
    "email": "vendor@example.com",
>
    "paymentMethod": "ach",
>
    "vendorStatus": 1
>
  }'

You need the vendorNumber you set for the vendor in the next step.

See Create vendor for the full API reference.

/// Step 2: Create a bill for the vendor

Send a POST request to /api/Bill/single/{entry} to add a bill that represents the invoice you need to pay. This is optional but strongly recommended for tracking.

$
curl -X POST "https://api.payabli.com/api/Bill/single/your-entry-point" \
>
  -H "Content-Type: application/json" \
>
  -H "requestToken: YOUR_API_TOKEN" \
>
  -d '{
>
    "billNumber": "Test-234782",
>
    "netAmount": 2500.00,
>
    "billDate": "2025-01-08",
>
    "dueDate": "2025-02-08",
>
    "comments": "Q1 supplies order",
>
    "vendor": {
>
        "vendorNumber": "V-001"
>
    }
>
  }'

The billId is returned in responseData. Copy this to use in the next step.

1
{
2
  "responseText": "Success",
3
  "responseCode": 1,
4
  "pageIdentifier": null,
5
  "roomId": 0,
6
  "isSuccess": true,
7
  "responseData": 6101
8
}

See Create bill for the full API reference.

/// Step 3: Authorize the payout transaction

Authorizing a payout creates the transaction, which is captured for processing later.

To authorize a payout, send a POST request to /api/MoneyOut/authorize.

$
curl -X POST "https://api.payabli.com/api/MoneyOut/authorize" \
>
  -H "Content-Type: application/json" \
>
  -H "requestToken: YOUR_API_TOKEN" \
>
  -d '{
>
    "entryPoint": "your-entry-point",
>
    "paymentMethod": {
>
      "method": "ach", // For managed payouts, used 'managed' here, and omit ACH fields
>
      "achHolder": "My First Vendor",
>
      "achRouting": "021000021",
>
      "achAccount": "123456789",
>
      "achAccountType": "Checking"
>
    },
>
    "paymentDetails": {
>
      "totalAmount": 2500.00,
>
      "orderDescription": "First payout test"
>
    },
>
    "vendorData": {
>
      "vendorNumber": "V-001"
>
    },
>
    "invoiceData": [
>
      {
>
        "billId": 6101
>
      }
>
    ]
>
  }'

The response includes a referenceId (for example, "129-001") that you need to capture the payout for processing in the next step.

1
{
2
  "responseCode": 1,
3
  "pageIdentifier": null,
4
  "roomId": 0,
5
  "isSuccess": true,
6
  "responseText": "Success",
7
  "responseData": {
8
    "authCode": null,
9
    "referenceId": "129-001",
10
    "resultCode": 1,
11
    "resultText": "Authorized",
12
    "avsResponseText": null,
13
    "cvvResponseText": null,
14
    "customerId": 0,
15
    "methodReferenceId": null
16
  }
17
}

See Authorize a transaction for payout for the full API reference.

/// Step 4: Capture the payout for settlement

Capturing an authorized payout adds it to a batch for processing.

To capture the payout, send a GET request to /api/MoneyOut/capture/{referenceId}.

$
curl -X GET "https://api.payabli.com/api/MoneyOut/capture/129-001" \
>
  -H "requestToken: YOUR_API_TOKEN"

The payout is now captured and will process with the next batch at 5 PM ET.

See Capture an authorized payout transaction for the full API reference.

/// Step 5: Monitor transaction status

Check the transaction status as it progresses through the payment lifecycle.

To get the transaction details, send a GET request to /api/MoneyOut/details/{referenceId}.

$
curl -X GET "https://api.payabli.com/api/MoneyOut/details/129-001" \
>
  -H "requestToken: YOUR_API_TOKEN"

Watch for the status to progress: 1 (Captured) → 2 (Processing) → 3 (Processed) → 5 (Paid).

• Learn more about Pay Out statuses.
• See Get details for a processed payout transaction for the full API reference.

/// What’s next

Congratulations! You just processed your first payout. Next, get to know payables and learn more about managing payouts.

/// Overview

Add a new vendor record with bank account details for ACH payments.

/// Prerequisites

Before you start, gather the following information. Payabli supports US and Canadian vendors only.

• Vendor business information: name, email, phone, and address
• A vendorNumber to identify the vendor in your system
• Bank account details for ACH payments: routing number, account number, account type, and account holder name

Including bank account details in billingData is not supported if you use managed payouts.

/// Step 1: Create the vendor

Send a POST request to /api/Vendor/single/{entry} to create the vendor. The entry parameter is your entrypoint identifier.

$
curl -X POST "https://api.payabli.com/api/Vendor/single/your-entry-point" \
>
  -H "Content-Type: application/json" \
>
  -H "requestToken: YOUR_API_TOKEN" \
>
  -d '{
>
    "vendorNumber": "V-001",
>
    "name1": "Acme Supplies Inc",
>
    "email": "ap@acme.com",
>
    "phone": "5125551234",
>
    "address1": "123 Main Street",
>
    "city": "Austin",
>
    "state": "TX",
>
    "zip": "78701",
>
    "country": "US",
>
    "paymentMethod": "ach",
>
    "vendorStatus": 1,
>
    "billingData": {
>
      "routingAccount": "021000021",
>
      "accountNumber": "123456789",
>
      "typeAccount": "Checking",
>
      "bankAccountHolderName": "Acme Supplies Inc",
>
      "bankAccountHolderType": "Business",
>
      "bankName": "Chase Bank"
>
    }
>
  }'

The response returns the Payabli-generated vendorId in responseData.

1
{
2
  "responseText": "Success",
3
  "isSuccess": true,
4
  "responseCode": 1,
5
  "responseData": 3890
6
}

See Create vendor for the full API reference.

/// Overview

Send a payment to a vendor via ACH bank transfer with full transaction lifecycle. This recipe is for on-demand payouts and is not supported with managed payouts.

/// Prerequisites

Before you start, make sure you have the following:

• A vendorNumber for the vendor you’re paying
• The vendor’s ACH information: account holder name, routing number, account number, and account type (checking or savings)
• A billId if you’re paying against a bill (recommended)

/// Step 1: Authorize the payout

Authorize the payout. This queues the transaction but doesn’t process it until captured.

To authorize a payout, send a POST request to /api/MoneyOut/authorize.

$
curl -X POST "https://api.payabli.com/api/MoneyOut/authorize" \
>
  -H "Content-Type: application/json" \
>
  -H "requestToken: YOUR_API_TOKEN" \
>
  -d '{
>
    "entryPoint": "your-entry-point",
>
    "paymentMethod": {
>
      "method": "ach",
>
      "achHolder": "Acme Supplies",
>
      "achRouting": "021000021",
>
      "achAccount": "123456789",
>
      "achAccountType": "Checking"
>
    },
>
    "paymentDetails": {
>
      "totalAmount": 1500.00,
>
      "orderDescription": "Invoice payment"
>
    },
>
    "vendorData": {
>
      "vendorNumber": "V-001"
>
    },
>
    "invoiceData": [
>
      {
>
        "billId": 6101
>
      }
>
    ]
>
  }'

The response includes a referenceId that you need to capture or cancel the transaction.

1
{
2
  "isSuccess": true,
3
  "responseData": {
4
    "authCode": null,
5
    "referenceId": "129-219",
6
    "resultCode": 1,
7
    "resultText": "Authorized"
8
  }
9
}

See Authorize a transaction for payout for the full API reference.

/// Step 2: Capture the payout

Capture the authorized transaction to add it to a batch for processing. Batches close at 5 PM ET.

To capture the payout, send a GET request to /api/MoneyOut/capture/{referenceId}.

$
curl -X GET "https://api.payabli.com/api/MoneyOut/capture/129-219" \
>
  -H "requestToken: YOUR_API_TOKEN"

See Capture an authorized payout transaction for the full API reference.

/// Step 3: Monitor transaction status

Check the transaction details to monitor the payout through its lifecycle: Captured → Processing → Processed → Paid.

To get the transaction details, send a GET request to /api/MoneyOut/details/{referenceId}.

$
curl -X GET "https://api.payabli.com/api/MoneyOut/details/129-219" \
>
  -H "requestToken: YOUR_API_TOKEN"

See Get details for a processed payout transaction for the full API reference.

/// Step 4: (Optional) Cancel if needed

You can cancel authorized or captured transactions before the batch closes at 5 PM ET.

To cancel a payout, send a DELETE request to /api/MoneyOut/cancel/{referenceId}.

$
curl -X DELETE "https://api.payabli.com/api/MoneyOut/cancel/129-219" \
>
  -H "requestToken: YOUR_API_TOKEN"

See Cancel a payout transaction for the full API reference.

/// Overview

This recipe walks through issuing a single-use virtual card to a vendor and sending the card link via email. This recipe is for on-demand payouts and is not supported with managed payouts.

/// Prerequisites

Before you start, make sure you have the following:

• A vendorNumber for the vendor you’re paying
• The vendor’s email address to send the card link to

/// Step 1: Create the virtual card payout

Authorize a payout with method: "vcard". This creates a single-use virtual card for the vendor.

To authorize the payout, send a POST request to /api/MoneyOut/authorize.

$
curl -X POST "https://api.payabli.com/api/MoneyOut/authorize" \
>
  -H "Content-Type: application/json" \
>
  -H "requestToken: YOUR_API_TOKEN" \
>
  -d '{
>
    "entryPoint": "your-entry-point",
>
    "paymentMethod": {
>
      "method": "vcard"
>
    },
>
    "paymentDetails": {
>
      "totalAmount": 500.00
>
    },
>
    "vendorData": {
>
      "vendorNumber": "V-001",
>
      "email": "vendor@example.com"
>
    }
>
  }'

The response includes a referenceId that you need to capture the payout transaction.

1
{
2
  "isSuccess": true,
3
  "responseData": {
4
    "authCode": null,
5
    "referenceId": "129-220",
6
    "resultCode": 1,
7
    "resultText": "Authorized"
8
  }
9
}

See Authorize a transaction for payout for the full API reference.

/// Step 2: Capture the transaction

Capture the authorized vCard payout to issue the card.

To capture the payout, send a GET request to /api/MoneyOut/capture/{referenceId}.

$
curl -X GET "https://api.payabli.com/api/MoneyOut/capture/129-220" \
>
  -H "requestToken: YOUR_API_TOKEN"

See Capture an authorized payout transaction for the full API reference.

/// Step 3: Send the card link

Send the vendor an email with a secure link to view their virtual card details.

To send the card link, send a POST request to /api/vcard/send-card-link.

$
curl -X POST "https://api.payabli.com/api/vcard/send-card-link" \
>
  -H "Content-Type: application/json" \
>
  -H "requestToken: YOUR_API_TOKEN" \
>
  -d '{
>
    "transId": "129-220"
>
  }'

See Send vCard link for the full API reference.

/// Step 4: Monitor for payment

When the vendor uses the vCard, the transaction status changes to Paid. vCards remain open for 180 days if not used.

Learn more about Pay Out statuses.