Create Subscription, Scheduled Payment, or Autopay

Intro

API Basics

Pay In Endpoints

MoneyIn
Subscription
TokenStorage
Invoice
LineItem
PaymentLink
PaymentMethodDomain
HostedPaymentPages
Cloud
Wallet: Apple Pay

Pay Out Endpoints

MoneyOut
Bill

Pay Ops Endpoints

Templates
Boarding
Chargebacks and ACH Returns
Entities
Notification
Query
Statistic
Export
Import

Object Models

Object Model References

POST

Subscription

add

curl --request POST \
  --url https://api-sandbox.payabli.com/api/Subscription/add \
  --header 'Content-Type: application/json' \
  --header 'requestToken: <api-key>' \
  --data '{
  "entryPoint": "f743aed24a",
  "paymentMethod": {
    "initiator": "payor",
    "cardHolder": "John Cassian",
    "cardzip": "12345",
    "cardcvv": "123",
    "cardexp": "02/25",
    "cardnumber": "4111111111111111",
    "method": "card"
  },
  "paymentDetails": {
    "totalAmount": 100,
    "serviceFee": 0
  },
  "customerData": {
    "customerId": 4440
  },
  "scheduleDetails": {
    "planId": 1,
    "startDate": "09-20-2024",
    "endDate": "03-20-2025",
    "frequency": "weekly"
  }
}'

{
  "isSuccess": true,
  "responseText": "Success",
  "responseData": "396",
  "CustomerId": "4440"
}

Authorizations

requestToken

string

header

required

Most endpoints require an organization token. Some endpoints require an application token, and those endpoints are noted.

Headers

idempotencyKey

string

A unique ID you can include to prevent duplicating objects or transactions if a request is sent more than once. This key is not generated in Payabli, you must generate it yourself.

Example:

"6B29FC40-CA47-1067-B31D-00DD010662DA"

Query Parameters

forceCustomerCreation

boolean

default:false

When true, the request creates a new customer record, regardless of whether customer identifiers match an existing customer.

Body

A subscription must be linked to a customer, so if you don't include `CustomerId`, and the identifier fields in `customerData` don't match an existing customer, then a new customer is created and associated with the subscription. If you are using a stored payment method, then make sure the `storedMethodId` passed in the paymentMethod object belongs to the customer provided in customerData.

entryPoint

string | null

required

The entrypoint identifier.

Maximum length: 50

Example:

"d193cf9a46"

subdomain

string | null

Refers to the payment page identifier. If provided, then the transaction is linked to the payment page.

Maximum length: 50

Example:

"mypage-1"

source

string | null

Custom identifier to indicate the transaction or request source.

Maximum length: 100

Example:

"api"

setPause

boolean

Flag indicating if subscription is paused. When a subscription is paused, no payments are processed until the subscription is unpaused, and the next payment date is not calculated automatically. If you want to skip a payment instead, set the totalAmount to 0 in the paymentDetails object.

Example:

false

paymentMethod

object

Information about the payment method for the transaction. Required and recommended fields for each payment method type are described in each schema below.

paymentDetails

object

Object describing details of the payment. To skip the payment, set the totalAmount to 0. Payments will be paused until the amount is updated to a non-zero value. When totalAmount is set to 0, the serviceFee must also be set to 0.

paymentDetails.totalAmount

number

required

Total amount to be charged. If a service fee is sent, then this amount should include the service fee."

Example:

100

paymentDetails.serviceFee

number | null

Service fee to be deducted from the total amount. This amount must be a number, percentages aren't accepted. If you are using a percentage-based fee schedule, you must calculate the value manually.

Example:

0

paymentDetails.currency

string | null

Currency code ISO-4217. If not code is provided the currency in the paypoint setting is taken. Default is USD.

Example:

"USD"

paymentDetails.checkNumber

string | null

A check number to be used in the ach transaction. Required for payment method = 'check'.

Example:

"107"

paymentDetails.checkImage

object | null

Object containing image of paper check.

paymentDetails.categories

object[] | null

Array of payment categories/line items describing the amount to be paid Note: These categories are for information only and are not validated against the total amount provided.

paymentDetails.splitFunding

object[] | null

Split funding instructions for the transaction. See Split a Transaction for more.

customerData

object

Object describing the customer/payor.

customerData.customerId

integer | null

The Payabli-generated unique ID for the customer.

Example:

4440

customerData.firstName

string | null

Customer/Payor first name.

Maximum length: 250

Example:

"John"

customerData.lastName

string | null

Customer/Payor last name.

Maximum length: 250

Example:

"Doe"

customerData.company

string | null

Customer's company name.

Maximum length: 250

Example:

"Sunshine LLC"

customerData.customerNumber

string | null

User-provided unique identifier for the customer. This is typically the customer ID from your own system.

Maximum length: 250

Example:

"3456-7645A"

customerData.billingAddress1

string | null

Customer's billing address.

Maximum length: 250

Example:

"123 Walnut Street"

customerData.billingAddress2

string | null

Additional line for Customer's billing address.

Maximum length: 100

Example:

"STE 900"

customerData.billingCity

string | null

Customer's billing city.

Maximum length: 250

Example:

"Johnson City"

customerData.billingState

string | null

Customer's billing state. Must be 2-letter state code for address in US.

Maximum length: 250

Example:

"Johnson City"

customerData.billingZip

string | null

Customer's billing ZIP code.

Maximum length: 50

Example:

"37615"

customerData.billingCountry

string | null

Customer's billing country.

Maximum length: 100

Example:

"US"

customerData.billingPhone

string | null

Customer's phone number.

Maximum length: 50

Example:

"5555555555"

customerData.billingEmail

string | null

Customer's email address.

Maximum length: 320

Example:

"example@email.com"

customerData.shippingAddress1

string | null

The shipping address.

Maximum length: 250

Example:

"123 Walnut St"

customerData.shippingAddress2

string | null

Additional line for shipping address.

Maximum length: 100

Example:

"STE 900"

customerData.shippingCity

string | null

Shipping city.

Maximum length: 250

Example:

"Johnson City"

customerData.shippingState

string | null

Shipping state or province.

Example:

"TN"

customerData.shippingZip

string | null

Shipping ZIP code.

Maximum length: 50

Example:

"37619"

customerData.shippingCountry

string | null

Shipping address country.

Maximum length: 100

Example:

"US"

customerData.additionalData

object

Custom dictionary of key:value pairs. You can use this field to store any data related to the object or for your system. If you are using custom identifiers, pass those in this object. Example usage:

{
  "additionalData": {
    "CustomIdentifier": "value",
    "key2": "value2",
    "key3": "value3"
  }
}

Example:

{
  "key1": "value1",
  "key2": "value2",
  "key3": "value3"
}

customerData.identifierFields

(string | null)[] | null

List of fields acting as customer identifiers, to be used instead of CustomerNumber.

Example:

["email"]

invoiceData

object

Object describing an Invoice linked to the subscription.

invoiceData.invoiceNumber

string | null

Invoice number. Identifies the invoice under a paypoint.

Maximum length: 250

Example:

"INV-2345"

invoiceData.invoiceDate

string | null

Invoice date in any of the accepted formats: YYYY-MM-DD, MM/DD/YYYY.

Example:

"2024-07-01"

invoiceData.invoiceDueDate

string | null

Invoice due date in one of the accepted formats: YYYY-MM-DD, MM/DD/YYYY.

Example:

"2024-07-01"

invoiceData.invoiceType

integer | null

Type of invoice. Only 0 for one-time invoices is currently supported.

Example:

0

invoiceData.invoiceEndDate

string | null

Indicate the date to finish a scheduled invoice cycle (`invoiceType`` = 1) in any of the accepted formats: YYYY-MM-DD, MM/DD/YYYY.

Example:

"2024-07-01"

invoiceData.invoiceStatus

enum<integer> | null

Status for invoice.

The accepted status values are:

0 draft
1 active
2 partially paid
4 paid/complete
99 cancelled

Available options:

0,

1,

2,

4,

99

Example:

1

invoiceData.frequency

enum<string> | null

Frequency of scheduled invoice.

Available options:

one-time,

weekly,

every2weeks,

every6months,

monthly,

every3months,

annually

Example:

"monthly"

invoiceData.paymentTerms

enum<string> | null

Payment terms for invoice. If no terms are defined, then reponse data for this field defaults to N30.

Available options:

PIA,

CIA,

UR,

NET10,

NET20,

NET30,

NET45,

NET60,

NET90,

EOM,

MFI,

5MFI,

10MFI,

15MFI,

20MFI,

2/10NET30,

UF,

10UF,

20UF,

25UF,

50UF

Example:

"PIA"

invoiceData.termsConditions

string | null

Custom terms and conditions included in the invoice.

Example:

"Must be paid before work scheduled."

invoiceData.notes

string | null

Notes included in the invoice.

Example:

"Example notes."

invoiceData.tax

number | null

Tax rate in percent applied to the invoice.

Example:

2.05

invoiceData.discount

number | null

Discount applied to the invoice.

Example:

10

invoiceData.invoiceAmount

number | null

Invoice total amount.

Example:

105

invoiceData.freightAmount

number | null

Freight/shipping amount.

Example:

10

invoiceData.dutyAmount

number | null

Duty amount.

Example:

0

invoiceData.purchaseOrder

string | null

Purchase order number.

Example:

"PO-345"

invoiceData.firstName

string | null

First name of the recipient of the invoice.

Example:

"Chad"

invoiceData.lastName

string | null

Last name of the recipient of the invoice.

Example:

"Mercia"

invoiceData.company

string | null

Company name of the recipient of the invoice.

Example:

"ACME, INC"

invoiceData.shippingAddress1

string | null

The shipping address.

Maximum length: 250

Example:

"123 Walnut St"

invoiceData.shippingAddress2

string | null

Additional line for shipping address.

Maximum length: 100

Example:

"STE 900"

invoiceData.shippingCity

string | null

Shipping city.

Maximum length: 250

Example:

"Johnson City"

invoiceData.shippingState

string | null

Shipping state or province.

Example:

"TN"

invoiceData.shippingZip

string | null

Shipping ZIP code.

Maximum length: 50

Example:

"37619"

invoiceData.shippingCountry

string | null

Shipping address country.

Example:

"US"

invoiceData.shippingEmail

string | null

Shipping recipient's contact email address.

Maximum length: 320

Example:

"example@email.com"

invoiceData.shippingPhone

string | null

Recipient phone number.

Example:

"5555555555"

invoiceData.shippingFromZip

string | null

Sender shipping ZIP code.

Example:

"30040"

invoiceData.summaryCommodityCode

string | null

Commodity code.

Example:

"501718"

invoiceData.items

object[] | null

Array of line items included in the invoice.

invoiceData.attachments

object | null

Array of fileContent objects with attached documents. Max upload size is 30 MB.

invoiceData.AdditionalData

string | null

Custom dictionary of key:value pairs. You can use this field to store any data related to the object or for your system. Example usage:

{
  "additionalData": {
    "key1": "value1",
    "key2": "value2",
    "key3": "value3"
  }
}

Example:

{
  "key1": "value1",
  "key2": "value2",
  "key3": "value3"
}

scheduleDetails

object

Object describing the schedule for subscription.

Response

200

application/json

Success

isSuccess

boolean

Boolean indicating whether the operation was successful. A true value indicates success. A false value indicates failure.

Example:

true

responseText

string | null

Response text for operation: 'Success' or 'Declined'.

Example:

"Success"

responseData

object | null

If isSuccess = true, this contains the identifier of the subscription.

If isSuccess = false, this contains the reason for the failure."

Example:

"396"

CustomerId

integer | null

Payabli-generated unique ID of the customer the subscription belongs to.

Example:

"4440"

Was this page helpful?

Reverse ACH Credit Get Subscription

curl --request POST \
  --url https://api-sandbox.payabli.com/api/Subscription/add \
  --header 'Content-Type: application/json' \
  --header 'requestToken: <api-key>' \
  --data '{
  "entryPoint": "f743aed24a",
  "paymentMethod": {
    "initiator": "payor",
    "cardHolder": "John Cassian",
    "cardzip": "12345",
    "cardcvv": "123",
    "cardexp": "02/25",
    "cardnumber": "4111111111111111",
    "method": "card"
  },
  "paymentDetails": {
    "totalAmount": 100,
    "serviceFee": 0
  },
  "customerData": {
    "customerId": 4440
  },
  "scheduleDetails": {
    "planId": 1,
    "startDate": "09-20-2024",
    "endDate": "03-20-2025",
    "frequency": "weekly"
  }
}'

{
  "isSuccess": true,
  "responseText": "Success",
  "responseData": "396",
  "CustomerId": "4440"
}