Collecting Payments#

In your platform, a payment usually belongs to an invoice, transaction or accounts receivable. For how your other records map to GoCardless, see how partner integrations work.

Collecting payments takes four steps:

1. Choose your payment method.
2. Create the payment.
3. Link the payment to your records.
4. Handle failed payments and refunds.

1. Choose your payment method#

Once a payer has a mandate, your user can charge them by Direct Debit without asking again. With Pay by Bank, the payer approves each payment instead.

To charge a fixed amount on a regular schedule, use subscriptions. To compare all the options, see what payment types you need.

2. Create the payment#

• You can create a Direct Debit payment as soon as the mandate is set up. You don't need to wait for it to become active.
• Create Direct Debit payments a few working days before they're due, so they're collected on the due date. Set charge_date to the due date. It must be on or after the mandate's next_possible_charge_date. For typical timings, see one-off Direct Debit.
• Create payments close to when they're needed. Once created, a payment's amount and date can't be changed: you can only update its metadata. If your user changes the transaction, cancel the payment while it's still pending_submission, and create a new one.
• Pay by Bank payments don't use a mandate. Create a Billing Request with a payment_request, and the payer approves it in their banking app. See Pay by Bank.
• Use idempotency keys so retrying a request never creates a duplicate payment.
• Each payment must be between £1 and £5,000. For higher amounts, contact the partnerships team.

The payer may get an email for each one-off payment, depending on your user's notification settings.

3. Link the payment to your records#

Link each payment to its transaction in both directions, so you can always find one from the other:

• From your platform to GoCardless: save the payment ID against your transaction.
• From GoCardless to your platform: add your own transaction ID to the payment's metadata, for example {"transaction_id": "TX-123"}. If a Billing Request creates the payment, use payment_request[metadata].

Show payments in your product#

Show each payment's status on your transaction list and on each transaction. For examples, see the UX guide.

A payment's status can change after it's been collected: it can fail late or be charged back. Listen for payment events to keep it up to date, and see when payments go wrong for what to show your user.

4. Handle failed payments and refunds#

When payments go wrong#

Payments can fail, fail late or be charged back, even after they're confirmed:

Each situation comes in as a webhook. For the events to listen for, see payment webhooks. For examples, see the UX guide.

Retries#

Success+ retries payments that failed for insufficient funds, and it's on by default for payments you create. Your user can also retry a payment themselves, up to 3 times, but only for payments that failed for insufficient funds.

Refunds#

Let your user refund a payment in full or in part. By default, a Direct Debit payment can't be refunded until 7 days after its charge date, so you don't refund a payment that later fails. We can switch this off on request. Pay by Bank payments can be refunded straight away.

What's next#