ProAbono Metadata in GoCardless

Overview

A business collecting through GoCardless holds the same transactions in two places: the ProAbono invoices and the GoCardless payments that settle them. Every object created in GoCardless by ProAbono carries metadata prefixed pa_ — pa_ for ProAbono — which ties it to the ProAbono objects behind it: invoice, customer, payment. That metadata is what makes operations traceable between the two platforms.

The traceability serves several purposes:

bank reconciliation: matching a GoCardless payout with the ProAbono invoices it settles;
business intelligence (BI): combining GoCardless and ProAbono data in the same analyses;
checks: verifying, for instance, that every GoCardless payment ties back to a ProAbono invoice;
investigation: tracing a GoCardless payment or customer back to its origin in ProAbono, to look into a bug or a situation reported by a customer.

How It Works

Metadata on a GoCardless Customer

Metadata	Example	Description
`pa_request_id`	`2334264`	Unique internal identifier of the payment request: the request sent to GoCardless to collect a payment, also called a payment attempt. An attempt can succeed or fail, and each one carries its own identifier. Technical use only.
`pa_customer_id`	`133700`	Unique internal identifier of the ProAbono customer. Technical use only.
`pa_customer_ref`	`cust-42`	Customer reference in ProAbono. Uniquely identifies the customer and is printed on the invoices sent to that customer.

Metadata on a GoCardless Payment

Metadata	Example	Description
`pa_invoice_id`	`4574980`	Unique internal identifier of the ProAbono invoice, distinct from the invoice number printed on the document. It is enough to retrieve the invoice, number included, through the ProAbono API.
`pa_request_id`	`2482873`	Unique internal identifier of the payment request — the payment attempt — this payment comes from. Technical use only.
`pa_customer_ref`	`cust-42`	Customer reference in ProAbono, the same value as on the customer.

Two keys are worth keeping apart: pa_customer_ref is public — it appears on the customer’s invoices — while every identifier ending in _id is internal to ProAbono and appears nowhere on a document.

Bank Reconciliation

A payment operator does not transfer each transaction separately. Payments are collected, then paid out in an aggregated payout: one transfer bundling many transactions, which reaches the bank account as a single statement line with no breakdown. A payout contains payments, refunds and, depending on the operator, fees of its own, such as its commissions.

Matching a payout with the ProAbono invoices can start from either side.

On the GoCardless side, the breakdown of the payout is read in the GoCardless dashboard: the payments it bundles are listed, and each payment carries its ProAbono metadata. The number of each invoice is then obtained with a simple request to the ProAbono API, from pa_invoice_id; the reference read in pa_customer_ref can be searched as it stands in Subscribers. This route can be fully automated, since the GoCardless API returns the same metadata in the metadata object of a payment or a customer.

On the ProAbono side, the reconciliation relies on the Automated Transactions list: each transaction appears with the customer reference, the invoice number and, in the last column, the transaction identifier at the payment operator — GoCardless here. Like every ProAbono list, the Automated Transactions list can be exported as a CSV or JSON file, or extracted through the API BackOffice. Separate from the API Live, that API is meant above all for data extraction.

Payouts, on the other hand, are not visible in ProAbono: GoCardless makes them directly to the business’s bank account. A full payout is therefore matched by joining two files — the list of its payments exported from GoCardless, and the automated transactions — on the GoCardless transaction identifier, rather than opening payments one by one.

Both routes can be automated through the APIs: see How to Automate Bank Reconciliation.