Articles in this section

Processing payments

Payment processing involves the following workflows:

Check payee status

  • Payable/Not Payable: Uploading a payment for a "Not Payable" payee results in a deferred status. To avoid this, check the payee's status first via IPN or API.
IPN API

payee_details_changed

Notifies you of details changed for a payee. Triggered on every iFrame step where the payee's details are updated.

  • Look for the "is_payable" variable set to TRUE.

GetExtendedPayeeDetailList

  • Look for the "Payable" variable set to TRUE.

Payment uploads to Tipalti (CSV or API)

Before clicking "Approve" or "Decline" in Tipalti:

  • When you upload a payment batch to Tipalti, each individual payment in the batch shows one of these statuses: Submitted, Deferred, or Deferred Internal. These statuses differ if you have a "No Approval" workflow on payments.
  • If you don't see one of these statuses, you may run into API error codes instead.
  • Both of the above points also apply to the payee cashout functionality.
IPN API
  • payment_submitted — triggered only for individual payments with the status "Submitted," not for the payment batch as a whole.
  • deferred — triggered only for an individual payment in a batch with the status "Deferred."

ProcessPayments

Pushes or uploads the payment batch to Tipalti. A payment batch can have a single payment or multiple payments.

Canceled payments

  • You can cancel a payment before clicking "Approve" in Tipalti. You can cancel individual payments in a batch before approving the batch. If a payment is scheduled, it can still be canceled up to one day before the planned date.
IPN API
payment_cancelled

Approve/decline payment batch

  • A payer can approve or decline a payment batch in Tipalti after uploading it.
  • You can't delete a payment batch or individual payments once uploaded. You can either decline the entire batch or cancel individual payments.
  • A payer can also request a no-approval workflow. We recommend leaving approvals on for the first few months until you're comfortable with the system. You can ask your implementation manager to turn off approvals for testing purposes.
IPNs APIs
payments_group_approved and payments_group_declined There's no API at present for the payment batch. Every payment you upload is a batch, even if it has a single payment.

Payment processing

After clicking "Approve" in Tipalti:

  • After you upload a payment batch to Tipalti, the payer has to approve it, unless you have a no-approval workflow.
  • After approval, individual payments show one of these statuses: Paid, Rejected, Voided Checks, or Deferred (for scheduled payments).
  • Once all payments in a batch are processed, the batch status shows "COMPLETED." Only individual payments carry the actual transaction status listed above. Transaction processing typically takes 1-2 business days, after which the status updates to Paid or Rejected.
Status API
  • Paid — you can ask your implementation manager to change the status to Paid for testing purposes in Sandbox.
  • Rejected/Voided Checks — you can ask your implementation manager to change the status for testing purposes in Sandbox.
  • Deferred — if the payee is "Not Payable," the status automatically changes to Deferred.

Compliance OFAC hit

  • This status change on individual payments can't be tested in Sandbox.
  • In Production, you can set up the following two IPNs to alert you when Tipalti has requested additional compliance documents from your payee.
IPNs

Payment processing can take more than 2 business days in this scenario. If you need more information on a transaction that's taking longer than 2 business days, create a support ticket.

Paper check payments (payment method)

  • When you upload a payment with the payment method type "Paper Check," the status changes to Paid immediately. This can be tested in Sandbox.
  • The status changes to "Cleared" after the payee cashes the check. This status change can't be tested in Sandbox.
IPN
Check Cashed