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:
- Stripe
- ProPay
- PayPal
- Square
- Braintree
- 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:
Field | Description | Format |
---|---|---|
invoiceId | Id of the invoice to mark paid | Numeric |
grossPaymentAmount | Total amount paid by the client | Numeric, with 2 decimal places |
feePaymentAmount | Service fee to process the payment (subtracted out of the grossPaymentAmount ) | Numeric, with 2 decimal places |
apiPaymentId | Id of the payment in your DB (or from your payment processor) | Any string |
paymentSource | Display name for the payment | Any string (e.g. "Visa *4747 Charge") |
status | Status 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:
Field | Description | Format |
---|---|---|
apiPaymentId | Id 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.
Updated 10 months ago