Payment Processing

Rest assured, you can hook up your own payment processing to Hurdlr's Invoicing API.

1. Getting started

Hurdlr recognizes that payment processing is critical to the business model of many FinTechs. As such, the Hurdlr API allows you to connect your existing accounts, from any payment processor, including but not limited to:

  1. Stripe
  2. ProPay
  3. PayPal
  4. Square
  5. Braintree
  6. WePay

The Hurdlr API team can help you securely connect your existing payment processing accounts; simply email us at [email protected]

2. How it works

If you have already implemented your own payment processing mechanism (e.g. to allow your users to accept credit card payments, ACH, etc.), then you'll want to follow the steps outlined below to get your payment processing integrated with the Hurdlr API.

Once integrated, your users will be able to send out invoices, and their clients will be able to pay those invoices using your payment processor of choice. Your back-end will communicate with the Hurdlr API to let it know of any updates to payments.

The Hurdlr API, as always, will take care of all the double-entry accounting behind the scenes. And the burden of creating a robust invoicing engine to pair with your payment processing is taken off of your dev team's shoulders.

👍

Automatic income reconciliation

Once you hook up your users' income data sources (e.g. bank accounts) to Hurdlr, Hurdlr's algorithms will automatically find and reconcile the bank deposits to the associated invoice payments (from your payment processor), in real-time.

3. Creating a merchant account for your user

When connecting a third party payment processor to the Hurdlr API, you own the experience around creating a merchant for your user. As such, the UX for creating a merchant account sits inside your product.

Once your user has been successfully set up to accept payments through your processor, you should set the thirdPartyPaymentsEnabled flag to true by POSTing the /invoiceSetup endpoint.

4. Processing a payment

Whenever you process a payment for a finalized invoice, you should let the Hurdlr API know that you've done so by assembling the following fields in a JSON object:

FieldDescriptionFormat
invoiceIdId of the invoice to mark paidNumeric
grossPaymentAmountTotal amount paid by the clientNumeric, with 2 decimal places
feePaymentAmountService fee to process the payment (subtracted out of the grossPaymentAmount)Numeric, with 2 decimal places
apiPaymentIdId of the payment in your DB (or from your payment processor)Any string
paymentSourceDisplay name for the paymentAny string (e.g. "Visa *4747 Charge")
statusStatus of the payment (especially useful for ACH)Must be one of the following:
"PENDING", "PROCESSED", "CANCELED", "REFUNDED", "FAILED"

To mark the invoice as paid, simply POST the above JSON object to the /payment endpoint:

curl \
  --request POST \
  --url https://sandbox.hurdlr.com/rest/v5/invoicing/payment \
  --header 'Authorization: Bearer ${access_token}' \
  --header 'Content-Type: application/json' \
  --data '{
    "payment": {
      "invoiceId": 21850,
      "grossPaymentAmount": 150.00,
      "feePaymentAmount": 4.50,
      "apiPaymentId": "ch_3KX9F5KkMq1CsF5K00DChQgZ",
      "paymentSource": "Visa *4747 Charge",
      "status": "PROCESSED"
    }
  }'

5. Refunding a payment

Whenever you issue a refund for a payment that you processed, you should let the Hurdlr API know that you've done so by assembling the following fields in a JSON object:

FieldDescriptionFormat
apiPaymentIdId of the payment in your DB (or from your payment processor)Numeric

To mark the payment as refunded, simply POST the above JSON object to the /payment endpoint:

curl \
  --request POST \
  --url https://sandbox.hurdlr.com/rest/v5/invoicing/payment \
  --header 'Authorization: Bearer ${access_token}' \
  --header 'Content-Type: application/json' \
  --data '{
    "payment": {
      "apiPaymentId": "ch_3KX9F5KkMq1CsF5K00DChQgZ",
      "status": "REFUNDED"
    }
  }'

6. Sending a payment receipt

To send a payment receipt to the client, you can simply make a POST call to the /sendReceipt endpoint:

curl \
  --request POST \
  --url https://sandbox.hurdlr.com/rest/v5/invoicing/sendReceipt \
  --header 'Authorization: Bearer ${access_token}' \
  --header 'Content-Type: application/json' \
  --data '{
    "invoiceIds": [
        21850
    ]
  }'

If you'd like these emails to originate from your own domain, simply email [email protected] and our API team will work with you to set that up.

7. Recurring Invoices

Hurdlr's Invoicing API makes creating recurring invoices easy, as detailed in the Creating an Invoice Draft section. The recurrence itself is managed via the Hurdlr, not your payment processor. So even if your payment processor doesn't support recurring payments, you can utilize Hurdlr's API on top of your payment processor to easily add that functionality.