Pay In cookbook
Quickstart recipes for accepting payments, refunds, and invoices
Use these recipes to get started with Pay In features and functions. See Pay In overview for more.
New to the API? Start with the authentication guide on the cookbooks home.
This end-to-end workflow walks through how to run a card sale transaction using the API. The getpaid endpoint authorizes and captures the transaction in one step, so it’s immediately captured for settlement. This recipe uses the v2 transaction API, which all new integrations should use.
/// Prerequisites
Before you start, make sure you have the following:
entryPoint valuecustomerId for the customer making the payment. If you don’t have one, create a customer first.PCI compliance note: This recipe passes raw card data directly through the API for demonstration purposes. In production, use an embedded component to collect card details, or use a stored payment method, which keeps your PCI scope minimal. If you handle raw card data directly, your PCI scope is expanded and you must secure cardholder data and customer IP addresses.
/// Step 1: Run the sale transaction
Send a POST request to /api/v2/MoneyIn/getpaid with the payment method, amount, and customer information. This authorizes and captures the transaction in one step.
A successful response returns code A0000 (Approved) and a paymentTransId in the data object that you can use to look up the transaction later.
See Make a transaction (v2) for the full API reference.
/// Step 2: Check the transaction status
Use the paymentTransId from the previous step to check the transaction’s status and details.
Send a GET request to /api/MoneyIn/details/{paymentTransId}.
Since the getpaid endpoint authorizes and captures in one step, the transStatus is Captured (1). To track settlement progress, watch the settlementStatus field as it moves from Pending (0) through In Transit (1), Transferred (2), and Funded (3). See the Pay In lifecycle for more.
See Get details for a processed transaction for the full API reference.
/// What’s next
Congratulations! You just ran your first sale transaction. Next, learn about the Pay In transaction lifecycle and explore running transactions with other payment methods.
Create a customer record in Payabli to track payers, store payment methods, and manage subscriptions. Customer records require at least one identifier field.
/// Prerequisites
Before you start, make sure you have the following:
entrypoint valuefirstname and lastname, email, or a custom identifierCheck your identifier settings in Settings > Custom Fields in PartnerHub. See custom identifiers for more.
/// Create the customer
Send a POST request to /api/Customer/single/{entry} with the customer’s details. Include identifier fields so Payabli can match against existing records.
The response includes a customerId that you can use with other endpoints to manage the customer and run transactions.
See Add customer for the full API reference.
/// What’s next
Congratulations! You’ve created a customer record. Learn more about managing customers with the API and customer entities in Payabli.
Refund a settled Pay In transaction to return funds to the customer. You can refund the full amount or a partial amount. This recipe uses the v2 API.
/// Prerequisites
Before you start, make sure you have the following:
referenceId of a settled transaction (also called the transId)If the transaction hasn’t settled yet, void it instead.
/// Refund the transaction
For a full refund, send a POST request to /api/v2/MoneyIn/refund/{transId}. For a partial refund, append the amount: /api/v2/MoneyIn/refund/{transId}/{amount}. The refund amount excludes any service fee charged on the original transaction.
This example refunds the full transaction amount:
A successful refund returns a code of A0004 with a reason of “Refunded”. The data object contains the full transaction details.
To refund a partial amount, include the amount in the path. This example refunds $100.99:
See Refund a settled transaction (v2) for the full API reference.
/// What’s next
Congratulations! You’ve refunded a Pay In transaction. Learn about choosing between void and refund and the Enhanced Refund Flow.
Void an unsettled Pay In transaction to cancel it before the batch closes. Voids cancel the full transaction amount — partial voids aren’t supported. This recipe uses the v2 API.
/// Prerequisites
Before you start, make sure you have the following:
referenceId of an unsettled transaction (also called the transId)If the transaction has already settled, refund it instead.
/// Void the transaction
Send a POST request to /api/v2/MoneyIn/void/{transId}.
A successful void returns a code of A0003 with a reason of “Canceled”. The data object contains the full transaction details.
If you try to void a transaction that has already been settled or voided, the API returns a 400 status.
See Void a transaction (v2) for the full API reference.
/// What’s next
Congratulations! You’ve voided a Pay In transaction. Learn about choosing between void and refund and explore other cancellation methods.
Charge a returning customer using a payment method you’ve already tokenized and stored, without collecting their card or bank account details again. This recipe uses the v2 transaction API, which all new integrations should use.
/// Prerequisites
Before you start, make sure you have the following:
storedMethodId for the customer’s saved payment method. If you haven’t saved one yet, see Save a payment method.customerId for the customer who owns the stored methodentryPoint valuecard or ach method, so you can set the method field correctly/// Step 1: Run the transaction
Send a POST request to /api/v2/MoneyIn/getpaid with the storedMethodId in the paymentMethod object instead of raw card or bank account details.
Set initiator to payor for customer-initiated transactions, or merchant for merchant-initiated transactions. See CIT and MIT overview for guidance on which to use.
A successful response returns code A0000 (Approved) and a paymentTransId in the data object that you can use to look up the transaction later.
See Make a transaction (v2) for the full API reference.
/// Step 2: Check the transaction status
Use the paymentTransId from the previous step to check the transaction’s status and details.
Send a GET request to /api/MoneyIn/details/{paymentTransId}.
Since the getpaid endpoint authorizes and captures in one step, the transStatus is Captured (1). To track settlement progress, watch the settlementStatus field as it moves from Pending (0) through In Transit (1), Transferred (2), and Funded (3). See Pay In lifecycle for more.
See Get details for a processed transaction for the full API reference.
/// What’s next
Congratulations! You just charged a saved payment method. Next, learn about tokenization and explore other ways to make transactions.
Generate a payment link from an existing invoice and send it to a customer via email. Payment links direct customers to a hosted payment page where they can pay using your accepted methods.
/// Prerequisites
Before you start, make sure you have the following:
idInvoice for an invoice created via the API. If you haven’t created one yet, see Manage invoices.entryPoint value/// Step 1: Generate the payment link
Create a payment link from your invoice. You can customize the hosted payment page’s branding, accepted payment methods, and layout.
Send a POST request to /api/PaymentLink/{idInvoice}.
The response includes the payment link ID in responseData. You need this ID to send the link in the next step.
See Create payment link from invoice for the full API reference.
/// Step 2: Send the payment link
Send the payment link to the customer via email. You can include additional recipients and attach a PDF invoice.
Send a POST request to /api/PaymentLink/push/{payLinkId}.
A successful response returns the payLinkId and a success message.
See Send payment link for the full API reference.
/// What’s next
Congratulations! You just sent a payment link to your customer. Next, learn about choosing an invoice delivery strategy and explore all the ways to manage payment links.
Create a one-time invoice for a customer and send it via email with an attached PDF. This recipe covers the two-call workflow: create the invoice, then send it.
/// Prerequisites
Before you start, make sure you have the following:
entryPoint valuecustomerId for an existing customer. If you haven’t created one yet, see Manage customers./// Step 1: Create the invoice
Create the invoice linked to an existing customer. The request includes customer identification, line items, amount, and invoice metadata.
Send a POST request to /api/Invoice/{entry}.
The response includes the invoice ID in responseData. You need this to send the invoice in the next step.
See Add invoice for the full API reference.
/// Step 2: Send the invoice
Email the invoice to the customer. Use attachfile=true to include a PDF copy, and mail2 to specify the recipient email address. If you omit mail2, Payabli sends the invoice to the email address on file for the customer.
Send a GET request to /api/Invoice/send/{idInvoice}.
See Send invoice via email for the full API reference.
/// What’s next
Congratulations! You just created and sent an invoice. Next, explore the full invoice lifecycle in Manage invoices with the API and learn how to choose an invoice delivery strategy.
Retrieve a list of batches and transfers for a paypoint to monitor settlement activity. A batch is a group of transactions that are settled together at the end of a processing cycle. A transfer is the actual movement of funds from the batch into the paypoint’s bank account.
/// Prerequisites
Before you start, make sure you have the following:
entrypoint identifier/// Step 1: Get batches for the paypoint
Query the batches endpoint to retrieve settlement batches for a paypoint. Each batch groups transactions and, once transferred, includes a Transfer object with deposit details.
Send a GET request to /api/Query/batches/{entry}.
The response includes batch records. If a batch has been transferred, the Transfer object contains the transfer details. If Transfer is null, the batch hasn’t been transferred yet.
See List batches for paypoint for the full API reference.
/// Step 2: Get transfers for the paypoint
Query the transfers endpoint to get deposit records with adjustment details like chargebacks, ACH returns, and fees.
Send a GET request to /api/Query/transfers/{entry}.
The response includes transfer records with gross amounts, deductions, and the net amount deposited.
See List transfers for the full API reference.
/// What’s next
You’ve retrieved batches and transfers for a paypoint. To track chargebacks and ACH returns within transfers, see Reconcile adjustments in transfers. For more on how batches and transfers relate, see How money moves.
Find chargebacks, ACH returns, and other adjustments in a Pay In transfer so you can reconcile deposits with your accounting records. This recipe drills into a single transfer — to list batches and transfers without focusing on adjustments, see the Retrieve batches and transfers recipe.
/// Prerequisites
Before you start, make sure you have the following:
entrypoint identifiertransferId for a specific transfer you want to reconcile/// Step 1: List transfers and spot adjustments
Query the transfers endpoint to retrieve deposit records for a paypoint. Each record shows the transfer’s gross amount, any adjustments deducted, and the net amount deposited to the merchant’s bank account.
Send a GET request to /api/Query/transfers/{entry}.
In the response, look for non-zero values in chargeBackAmount, returnedAmount, holdAmount, billingFeesAmount, and adjustmentsAmount. Any non-zero value means the transfer included that type of adjustment. Copy the transferId for any transfer you want to break down further.
See List transfers for the full API reference.
/// Step 2: Get the transaction-level breakdown
For each transfer with adjustments, query the transfer details endpoint to see which individual transactions contributed to the chargebacks, ACH returns, or other adjustments.
Send a GET request to /api/Query/transferDetails/{entry}/{transferId}.
The Summary rolls up the adjustments across the whole transfer. The Records array has one entry per transaction included in the transfer — use the category field to identify which transactions were adjustments. The value is return for an ACH return and chargeback for a chargeback. Match transactionId against your own records to tie each adjustment back to a customer, invoice, or order.
See List transfer details for the full API reference.
/// What’s next
You’ve reconciled the adjustments in a transfer. To start from a batch instead of a transfer, see Reconcile adjustments in transfers. To work with chargebacks specifically, see Retrieve and manage chargebacks.
List chargebacks for a paypoint, retrieve the details of a specific case, and submit a response with supporting documentation. To work with ACH returns instead, see the retrieve ACH returns recipe.
/// Prerequisites
Before you start, make sure you have the following:
entrypoint identifier/// Step 1: List chargebacks for the paypoint
Query the disputes endpoint with a method filter of card to exclude ACH returns from the results. The endpoint returns both chargebacks and ACH returns, so filtering by method gives you only credit card chargebacks.
Send a GET request to /api/Query/chargebacks/{entry}.
The response includes one record per chargeback. Use Id to retrieve full details or submit a response in the next steps. Status tracks the chargeback lifecycle: 0 is open, 1 is pending, 2 is closed-won, and 3 is closed-lost. ReplyBy is the deadline for your response.
See List disputes by paypoint for the full API reference, including all available filters and pagination options.
/// Step 2: Retrieve details for a chargeback
Use the Id from the list response to fetch the full chargeback record, including the original transaction, any prior responses, and the case message timeline.
Send a GET request to /api/ChargeBacks/read/{Id}.
The response contains the full chargeback object. Confirm Status and ReplyBy before submitting a response, and check Responses to see whether one has already been submitted.
See Get chargeback or ACH return record for the full API reference.
/// Step 3: Respond to the chargeback
Submit your response with supporting documentation before the ReplyBy date. Each attachment is a base64-encoded file in the attachments array. Include receipts, contracts, customer correspondence, and any other evidence that supports your case.
Send a POST request to /api/ChargeBacks/response/{Id}.
A successful response returns the response identifier in responseData. Save it if you need to reference the submission later.
See Add response to chargeback or return for the full API reference.
/// What’s next
You’ve responded to a chargeback. To stay on top of new cases as they come in, subscribe to the ReceivedChargeBack webhook event — see Manage notifications. For more on documentation requirements and prevention, see the payment disputes guide.
Set up recurring automatic payments on an invoice by creating a subscription that references it. In this example, a customer owes 150 per month over 12 months. Each subscription payment automatically posts against the invoice.
/// Prerequisites
Before you start, make sure you have the following:
entryPoint valuecustomerId for an existing customer. If you haven’t created one yet, see Manage customers.storedMethodId for the customer’s saved payment method. To save a method, see Save a payment method./// Step 1: Create the invoice
Create a one-time invoice for the customer. This is the invoice that subscription payments will post against.
Send a POST request to /api/Invoice/{entry}.
In the next step, you use the same invoiceNumber to link the subscription to this invoice.
See Add invoice for the full API reference.
/// Step 2: Create a subscription with the invoice
Create a subscription that charges 1,800 invoice from step 1. The invoiceNumber in the subscription request must match the one you set when creating the invoice — this is what ties the payments to the invoice. The scheduleDetails.frequency controls when payments run, while invoiceData.frequency describes the invoice itself — keep the invoice as "onetime" and let the subscription handle the recurrence.
Send a POST request to /api/Subscription/add.
The response includes the subscription ID in responseData and the linked customerId.
See Create subscription for the full API reference.
/// What’s next
Congratulations! You just set up autopay on an invoice. Next, learn how to manage and update subscriptions and explore the full invoice lifecycle in Manage invoices with the API.
Set up a recurring payment (also called a subscription, autopay, or scheduled payment) for a customer using a saved payment method, so the customer is charged automatically on a schedule. This recipe covers the merchant-initiated case, where the customer authorizes recurring billing up front and Payabli runs each payment without further customer action.
/// Prerequisites
Before you start, make sure you have the following:
entryPoint valuecustomerId for an existing customer. If you haven’t created one yet, see Manage customers.storedMethodId for the customer’s saved payment method. To save one, see Save a payment method.weekly, monthly, annually, etc.)/// Step 1: Create the subscription
Send a POST request to /api/Subscription/add with the stored payment method, schedule, and amount. Set initiator to merchant and storedMethodUsageType to recurring to flag this as merchant-initiated recurring billing.
A successful response includes the new subscription’s ID in responseData. Save it. You’ll need it to update, pause, or delete the subscription later.
See Create subscription for the full API reference.
/// Step 2: Confirm the subscription
Verify the subscription was created correctly by retrieving it. Use the responseData value from the previous step as the subId path parameter.
Send a GET request to /api/Subscription/{subId}.
The response includes the schedule, payment method, customer details, and the NextDate field showing when the next scheduled payment will run. Subscription and autopay transactions typically run between 2:30 and 3:30 AM Eastern time on the scheduled date.
See Get subscription for the full API reference.
/// What’s next
Congratulations! You just set up a recurring payment for a customer. If you want each scheduled payment to post against an invoice instead, see the “Set up autopay on an invoice” recipe in the Pay In cookbook. To pause, update, or cancel the schedule later, see Manage subscriptions with the API, and explore subscription utilities for handling failed payments.