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
Create Subscription, Scheduled Payment, or Autopay
Creates a subscription or scheduled payment to run at a specified time and frequency.
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"
}
}'
Authorizations
Most endpoints require an organization
token. Some endpoints require an application
token, and those endpoints are noted.
Headers
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.
Query Parameters
When true
, the request creates a new customer record, regardless of whether customer identifiers match an existing customer.
Body
The entrypoint identifier.
50
Object describing the customer/payor.
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"
}
}
Customer's billing address.
250
Additional line for Customer's billing address.
100
Customer's billing city.
250
Customer's billing country.
100
Customer's email address.
250
Customer's phone number.
50
Customer's billing state. Must be 2-letter state code for address in US.
250
Customer's billing ZIP code.
50
Customer's company name.
250
The Payabli-generated unique ID for the customer.
User-provided unique identifier for the customer. This is typically the customer ID from your own system.
250
Customer/Payor first name.
250
List of fields acting as customer identifiers, to be used instead of CustomerNumber.
Customer/Payor last name.
250
The shipping address.
250
Additional line for shipping address.
100
Shipping city.
250
Shipping address country.
100
Shipping state or province.
Shipping ZIP code.
50
Object describing an Invoice linked to the subscription.
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"
}
}
Array of fileContent
objects with attached documents. Max upload size is 30 MB.
Company name of the recipient of the invoice.
Discount applied to the invoice.
Duty amount.
First name of the recipient of the invoice.
Freight/shipping amount.
Frequency of scheduled invoice.
one-time
, weekly
, every2weeks
, every6months
, monthly
, every3months
, annually
Invoice total amount.
Invoice date in any of the accepted formats: YYYY-MM-DD, MM/DD/YYYY.
Invoice due date in one of the accepted formats: YYYY-MM-DD, MM/DD/YYYY.
Indicate the date to finish a scheduled invoice cycle (`invoiceType`` = 1) in any of the accepted formats: YYYY-MM-DD, MM/DD/YYYY.
Invoice number. Identifies the invoice under a paypoint.
250
Status for invoice.
The accepted status values are:
- 0 draft
- 1 active
- 2 partially paid
- 4 paid/complete
- 99 cancelled
0
, 1
, 2
, 4
, 99
Type of invoice. Only 0
for one-time invoices is currently supported.
Array of line items included in the invoice.
Item or product price per unit.
Item or product name. Max length of 250 characters.
250
Quantity of item or product.
Array of tags classifying item or product.
Item or product commodity code. Max length of 250 characters.
250
Item or product description. Max length of 250 characters.
250
Internal class of item or product: value '0' is only for invoices , '1' for bills and, '2' common for both.
0
, 1
, 2
Item or product code. Max length of 250 characters.
250
Tax amount applied to item or product.
Tax rate applied to item or product.
Total amount in item or product.
Unit of measurement. Max length of 100 characters.
100
Last name of the recipient of the invoice.
Notes included in the invoice.
Payment terms for invoice. If no terms are defined, then reponse data for this field defaults to N30
.
PIA
, CIA
, UR
, NET10
, NET20
, NET30
, NET45
, NET60
, NET90
, EOM
, MFI
, 5MFI
, 10MFI
, 15MFI
, 20MFI
, 2/10NET30
, UF
, 10UF
, 20UF
, 25UF
, 50UF
Purchase order number.
The shipping address.
250
Additional line for shipping address.
100
Shipping city.
250
Shipping address country.
Shipping recipient's contact email address.
Sender shipping ZIP code.
Recipient phone number.
Shipping state or province.
Shipping ZIP code.
50
Commodity code.
Tax rate in percent applied to the invoice.
Custom terms and conditions included in the invoice.
Object describing details of the payment.
Total amount to be charged. If a service fee is sent, then this amount should include the service fee."
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.
Price/cost per unit of item or category.
Name of item or category.
Description of item or category
Quatity of item or category
Object containing image of paper check.
A check number to be used in the ach transaction. Required for payment method = 'check'.
Currency code ISO-4217. If not code is provided the currency in the paypoint setting is taken. Default is USD.
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.
Split funding instructions for the transaction. See Split a Transaction for more.
The accountId for the account the split should be sent to.
Amount from the transaction to sent to this recipient.
A description for the split.
The entrypoint the split should be sent to.
Information about the payment method for the transaction. Required and recommended fields for each payment method type are described in each schema below.
Card expiration date in format MMYY or MM/YY. This field is required when using the card
method.
5
The card number. Required when method is card
and a storedMethodId isn't included.
20
Method to use for the transaction. For transactions with a credit or debit card, or a tokenized card, use card
.
card
Card Verification Value (CVV) associated with the card number. We strongly recommend that you include this field when using card
as a method.
4
Cardholder name.
250
ZIP code for the billing address of cardholder. We strongly recommend that you include this field when using card
as a method.
50
Strongly recommended The cardholder-initiated transaction (CIT) or merchant-initiated transaction (MIT) indicator for the transaction. If you don't specify a value, Payabli defaults to merchant
.
Available values:
payor
: For cardholder-initiated transactionsmerchant
: For merchant-initiated transactions
See Understanding CIT and MIT Indicators for more information.
When true
, Payabli saves the payment method if the transaction is successful. The payment method ID is returned in the response as methodReferenceId
. Defaults to false
.
Object describing the schedule for subscription.
Subscription end date in any of the accepted formats: YYYY-MM-DD, MM/DD/YYYY or the value untilcancelled
to indicate a scheduled payment with infinite cycle.
Frequency of the subscription.
one-time
, weekly
, every2weeks
, every6months
, monthly
, every3months
, annually
This field is for future development, leave null. Identifier of subscription plan applied in the scheduled payment/subscription.
Subscription start date in any of the accepted formats: YYYY-MM-DD, MM/DD/YYYY. This must be a future date.
Flag indicating if subscription is paused.
Custom identifier to indicate the transaction or request source.
100
Refers to the payment page identifier. If provided, then the transaction is linked to the payment page.
50
Response
Payabli-generated unique ID of the customer the subscription belongs to.
Boolean indicating whether the operation was successful. A true
value indicates success. A false
value indicates failure.
If isSuccess
= true, this contains the identifier of the subscription.
If isSuccess
= false, this contains the reason for the failure."
Response text for operation: 'Success' or 'Declined'.
Was this page helpful?
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"
}
}'