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
Authorize Transaction
Authorize a card transaction. This returns an authorization code and reserves funds for the merchant. Authorized transactions aren’t flagged for settlement until captured.
Note: Only card transactions can be authorized. This endpoint can’t be used for ACH transactions.
curl --request POST \
--url https://api-sandbox.payabli.com/api/MoneyIn/authorize \
--header 'Content-Type: application/json' \
--header 'requestToken: <api-key>' \
--data '{
"entryPoint": "f743aed24a",
"ipaddress": "255.255.255.255",
"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
}
}'
{
"responseText": "Success",
"isSuccess": true,
"pageIdentifier": null,
"responseData": {
"authCode": "123456",
"referenceId": "227-d30f8a47ddaf4fa989016d21d088ae5b",
"resultCode": 1,
"resultText": "Approved",
"avsResponseText": "No address or ZIP match only",
"cvvResponseText": "CVV2/CVC2 no match",
"customerId": 1409,
"methodReferenceId": null
}
}
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.
"6B29FC40-CA47-1067-B31D-00DD010662DA"
Query Parameters
When true
, the request creates a new customer record, regardless of whether customer identifiers match an existing customer.
Body
Model request body for Authorize Transaction.
The entrypoint identifier.
50
"d193cf9a46"
Object describing payment method to use for transaction.
Method to use for the transaction. For transactions with a credit or debit card, or a tokenized card, use card
.
card
"card"
The card number. Required when method is card
and a storedMethodId isn't included.
20
"4111111111111111"
Card expiration date in format MMYY or MM/YY. This field is required when using the card
method.
5
"02/25"
Card Verification Value (CVV) associated with the card number. We strongly recommend that you include this field when using card
as a method.
4
"123"
ZIP code for the billing address of cardholder. We strongly recommend that you include this field when using card
as a method.
50
"12345"
Cardholder name.
250
"John Cassian"
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.
"payor"
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
.
Refers to the payment page identifier. If provided, then the transaction is linked to the payment page.
50
"mypage-1"
Custom identifier to indicate the transaction or request source.
100
"api"
Custom identifier for the transaction.
250
"O-5140"
Text description of the transaction.
250
"Depost for materials for 123 Walnut St"
Payabli identifier of the subscription associated with the transaction.
123
Custom identifier for payment connector.
250
Details about the payment.
Total amount to be charged. If a service fee is sent, then this amount should include the service fee."
100
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.
0
Currency code ISO-4217. If not code is provided the currency in the paypoint setting is taken. Default is USD.
"USD"
A check number to be used in the ach transaction. Required for payment method = 'check'.
"107"
Object containing image of paper check.
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.
Name of item or category.
"Deposit"
Price/cost per unit of item or category.
1000
Description of item or category
"Deposit for materials"
Quatity of item or category
Split funding instructions for the transaction. See Split a Transaction for more.
The entrypoint the split should be sent to.
"41035afaa7"
The accountId for the account the split should be sent to.
"187-782"
A description for the split.
"Split for annual dues"
Amount from the transaction to sent to this recipient.
456.23
Object describing the customer/payor. Which fields are required depends on the paypoint's custom identifier settings. See PayorData Object Model for a complete reference.
The Payabli-generated unique ID for the customer.
4440
Customer/Payor first name.
250
"John"
Customer/Payor last name.
250
"Doe"
Customer's company name.
250
"Sunshine LLC"
User-provided unique identifier for the customer. This is typically the customer ID from your own system.
250
"3456-7645A"
Customer's billing address.
250
"123 Walnut Street"
Additional line for Customer's billing address.
100
"STE 900"
Customer's billing city.
250
"Johnson City"
Customer's billing state. Must be 2-letter state code for address in US.
250
"Johnson City"
Customer's billing ZIP code. For Pay In functions, this field supports 5-digit and 9-digit ZIP codes and alphanumeric Canadian postal codes. For example: "37615-1234" or "37615".
50
"37615"
Customer's billing country.
100
"US"
Customer's phone number.
50
"5555555555"
Customer's email address.
320
"example@email.com"
The shipping address.
250
"123 Walnut St"
Additional line for shipping address.
100
"STE 900"
Shipping city.
250
"Johnson City"
Shipping state or province.
"TN"
Shipping ZIP code. For Pay In functions, this field supports 5-digit and 9-digit ZIP codes and alphanumeric Canadian postal codes. For example: "37615-1234" or "37615".
50
"37619"
Shipping address country.
100
"US"
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"
}
}
{
"key1": "value1",
"key2": "value2",
"key3": "value3"
}
List of fields acting as customer identifiers, to be used instead of CustomerNumber.
["email"]
Invoice number. Identifies the invoice under a paypoint.
250
"INV-2345"
Invoice date in any of the accepted formats: YYYY-MM-DD, MM/DD/YYYY.
"2024-07-01"
Invoice due date in one of the accepted formats: YYYY-MM-DD, MM/DD/YYYY.
"2024-07-01"
Type of invoice. Only 0
for one-time invoices is currently supported.
0
Indicate the date to finish a scheduled invoice cycle (`invoiceType`` = 1) in any of the accepted formats: YYYY-MM-DD, MM/DD/YYYY.
"2024-07-01"
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
1
Frequency of scheduled invoice.
one-time
, weekly
, every2weeks
, every6months
, monthly
, every3months
, annually
"monthly"
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
"PIA"
Custom terms and conditions included in the invoice.
"Must be paid before work scheduled."
Notes included in the invoice.
"Example notes."
Tax rate in percent applied to the invoice.
2.05
Discount applied to the invoice.
10
Invoice total amount.
105
Freight/shipping amount.
10
Duty amount.
0
Purchase order number.
"PO-345"
First name of the recipient of the invoice.
"Chad"
Last name of the recipient of the invoice.
"Mercia"
Company name of the recipient of the invoice.
"ACME, INC"
The shipping address.
250
"123 Walnut St"
Additional line for shipping address.
100
"STE 900"
Shipping city.
250
"Johnson City"
Shipping state or province.
"TN"
Shipping ZIP code. For Pay In functions, this field supports 5-digit and 9-digit ZIP codes and alphanumeric Canadian postal codes. For example: "37615-1234" or "37615".
50
"37619"
Shipping address country.
"US"
Shipping recipient's contact email address.
320
"example@email.com"
Recipient phone number.
"5555555555"
Sender shipping ZIP code.
"30040"
Commodity code.
"501718"
Array of line items included in the invoice.
Item or product name. Max length of 250 characters.
250
"Materials deposit"
Item or product price per unit.
5
Quantity of item or product.
1
Item or product code. Max length of 250 characters.
250
"M-DEPOSIT"
Item or product description. Max length of 250 characters.
250
"Deposit for materials."
Item or product commodity code. Max length of 250 characters.
250
"010"
Unit of measurement. Max length of 100 characters.
100
"SqFt"
Internal class of item or product: value '0' is only for invoices , '1' for bills and, '2' common for both.
0
, 1
, 2
0
Array of tags classifying item or product.
Total amount in item or product.
Tax amount applied to item or product.
7
Tax rate applied to item or product.
0.075
Array of fileContent
objects with attached documents. Max upload size is 30 MB.
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"
}
}
{
"key1": "value1",
"key2": "value2",
"key3": "value3"
}
Response
General response for certain moneyIn and moneyOut endpoints.
Boolean indicating whether the operation was successful. A true
value indicates success. A false
value indicates failure.
true
Response text for operation: 'Success' or 'Declined'.
"Success"
Auxiliary validation used internally by payment pages and components.
null
The object containing the response data.
Authorization code for the transaction.
null
The transaction identifier in Payabli.
"45-erre-324"
Result code for the operation. Value 1 indicates a successful operation, values 2 and 3 indicate errors. A value of 10 indicates that an operation has been initiated and is pending.
1
Text describing the result. If ResultCode
= 1, will return 'Approved' or a general success message. If `ResultCode`` = 2 or 3, will contain the cause of the error or decline.
"Cancelled"
Text code describing the result for address validation (applies only for card transactions).
Text code describing the result for CVV validation (applies only for card transactions).
Payabli-generated unique ID of customer owner of transaction. Returns `0`` if the transaction was not assigned to an existing customer or no customer was created.
The stored method's identifier (sometimes referred to as 'token') in Payabli. When null
, the method wasn't created, or doesn't exist, depending on the operation performed.
"1ec55af9-7b5a-4ff0-81ed-c12d2f95e135-4440"
Was this page helpful?
curl --request POST \
--url https://api-sandbox.payabli.com/api/MoneyIn/authorize \
--header 'Content-Type: application/json' \
--header 'requestToken: <api-key>' \
--data '{
"entryPoint": "f743aed24a",
"ipaddress": "255.255.255.255",
"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
}
}'
{
"responseText": "Success",
"isSuccess": true,
"pageIdentifier": null,
"responseData": {
"authCode": "123456",
"referenceId": "227-d30f8a47ddaf4fa989016d21d088ae5b",
"resultCode": 1,
"resultText": "Approved",
"avsResponseText": "No address or ZIP match only",
"cvvResponseText": "CVV2/CVC2 no match",
"customerId": 1409,
"methodReferenceId": null
}
}