Direct Debit Payments

Overview

Direct debit allows you to take payments directly from your customer's bank account. It operates on a slower schedule, but is far cheaper than credit card payments. This is ideal for recurring bills or background payments. Since payments are not immediate, there are a few more steps you need to take to find the status of your payment.

This guide shows you our most popular workflow for integrating direct debit into your products.

Workflow Summary

Here's the list of steps to take to ensure a complete integration.

1. Get an Access Token. See Authentication
2. Save a Payer. Capture your customer's bank account information for later use. See Create or Update Payer
3. Schedule a Payment. You can schedule a payment for today, or any time in the future. All payments process overnight. See Save scheduled payment
4. Poll for new Events. Events tell you when things happen in the background, such as a payment failing or succeeding. See List all events
5. Lookup Bank Results events for failed payments. See Get Event
6. Lookup Transfer event for successful payments. See Get Event and List transfer line items

Detailed Steps

1. Get an Access Token

Our API uses Bearer Authentication, which means you need to ask for an access token to make calls to our API. See Authentication for details of how to fetch one.

Once you have your token, include it as a header with each API call like so:

Authorization: Bearer <token>

2. Save a Payer

All payments within Pinch need to be associated with a Payer. This is the customer that you will be taking funds from.

See Create or Update Payer for the details to submit.

Submit as much information about the payer as you can and be sure to save the Payer ID (pyr_123456789) from the response.

3. Schedule a Payment

Direct debit payments are processed each day, once in the morning and once in the evening. They are sent to the bank overnight and can take several business days to be completed.

You can submit a payment for a payer using the Save scheduled payment endpoint.

It's a good idea to keep track of the Payment ID (pmt_123456789) that is returned in the response.

4. Poll for new Events

Since direct debit payments can take a few days to process, you'll need a way to be notified when they are either successful or failed (dishonoured). To do this we have an events system for all background processes.

Use the List all events endpoint to retrieve a list of all events. You can look at the type property to determine which kind of event it is. The events you'll want to look at are:

• bank-results - Returns a list of failed payments
• transfer - Lets you know when a Transfer has been created

You'll use these two events in the next steps.

5. Lookup bank results for failed payments

When a payment is dishonoured (meaning it failed), it will be part of a Bank-Results event containing all the failed payments for that day.

You can use the Get Event endpoint to retrieve the event data, which will contain a list of failed payments and their IDs. These will match the payment IDs you saved earlier.

It's up to you to schedule a new payment when one fails.

6. Lookup transfer event for successful payments

A transfer is created whenever there are payments ready to be settled to your merchant bank account. Each transfer contains the details of any successful payments, failed payments, application charges and the fees related to any of these.

Firstly, use the Get Event endpoint to lookup the details of your new transfer event. Specifically, you'll want the Transfer ID (tra_123456789).

Next, fetch the transfer details from the List transfer line items endpoint. This will return a list of Payment IDs and their status (type: 'Settlement' for successful, type: 'Dishonour' for failed.).

You've now successfully integrated Direct Debit payments into your system.