Partners

Introduction Connect your merchants Getting your users verified Setting up mandates Supporting mandates set up outside of your product Sending money Importing outbound payments Webhooks for partners Integration Guide UX Guides & Resources Partners: Go-live checklist

Partners: Importing outbound payments

View as Markdown

The Outbound Payment Import API lets you create a batch of outbound payments in a single API call, then have your merchant approve the entire batch through the GoCardless dashboard. This is designed for partner integrations and removes two requirements that apply to individual outbound payments.

No API request signing — import endpoints do not require request signing.
No per-payment approval — the merchant approves all payments in the batch at once, instead of approving each payment individually.

Prerequisites

Before creating an import, ensure the following are in place:

Your merchant must be fully onboarded with GoCardless and have Outbound Payments enabled at the merchant level.
The merchant's payment account must be funded with a sufficient balance to cover the total import amount.
Recipient bank accounts must already exist for each payee — see Create a recipient
The person authorising the import on the dashboard must have a GoCardless Dashboard user account with read-write or admin permissions and SMS-based two-factor authentication enabled.
You must have a valid access token for the merchant — see Making API calls on behalf of your merchant.

How it works

The import workflow has four stages:

1. Create the import

Submit all payment entries in a single API call. GoCardless begins validating the entries and running bank account holder verification checks.

2. Wait for validation

Poll the API until all entries have been validated and verification checks are complete.

3. Authorise the import

Share the authorisation link with your merchant. They review the import on the GoCardless dashboard and approve it by completing Strong Customer Authentication (SCA) via SMS.

4. Track the result

Once authorised, each entry is automatically converted into an individual outbound payment. Use webhooks to track the status of each payment.

Import statuses

Status	Description
`created`	The import has been received.
`validating`	Entry validation and bank account holder verification are in progress.
`valid`	All entries passed validation and verification checks are complete. Ready for approval.
`invalid`	One or more entries failed validation. The import cannot be authorised.
`processing`	Approval received. Payments are being created.
`processed`	All entries have been converted into outbound payments.
`cancelled`	The import was cancelled. Unused imports expire after 3 calendar days. Imports abandoned during approval are cancelled within 5 minutes of the approval starting (when we send the SMS).

Create the import

Imports are capped at 1000 entries. If you need to send more payments, create multiple imports.

Submit a Create an outbound payment import request with an array of payment entries. For information on the entry parameters, please refer to the API reference linked.

Action: Call the Create an outbound payment import endpoint.

The top-level links.creditor field is optional. If omitted, the creditor is inferred from the access token used to make the request. You can set it explicitly when calling on behalf of a specific merchant.

The response includes:

authorisation_url — The link to the GoCardless dashboard where the merchant reviews and authorises the import. Save this URL — you will share it with the merchant in Step 3.
status — Initially validating while GoCardless checks each entry and runs bank account holder verification.
entry_counts — A summary of validation and verification results, updated as checks complete.

Wait for validation

After creation, GoCardless validates each entry and runs bank account holder verification checks. The import remains in validating status until all checks are complete, then transitions to valid or invalid.

There are no webhook notifications for import status changes. You must poll the API to check when validation completes.

Validation takes about half a minute to a minute

Action: Poll the Get an outbound payment import endpoint until the status changes from validating

When validation and verification checks are complete, the response will show the updated status and verification counts:

HTTP/1.1 200 OK
Content-Type: application/json
{
  "outbound_payment_imports": {
    "id": "IM123",
    "created_at": "2024-09-05T12:20:04.397Z",
    "status": "valid",
    "amount_sum": 3500,
    "currency": "GBP",
    "authorisation_url": "https://manage.gocardless.com/imports/IM123",
    "entry_counts": {
      "total": 2,
      "valid": 2,
      "invalid": 0,
      "verified": 2,
      "verified_with_full_match": 1,
      "verified_with_partial_match": 1,
      "verified_with_no_match": 0,
      "verified_with_unable_to_match": 0,
      "processed": 0,
      "failed_to_process": 0
    },
    "links": {
      "creditor": "CR123"
    }
  }
}

Bank account holder verification

Bank account holder verification runs automatically during validation. The entry_counts object on the import provides a summary of results:

Field	Meaning
verified	Total number of entries verified.
verified_with_full_match	The recipient's name fully matches the name on the bank account.
verified_with_partial_match	The recipient name is a close but not an exact match.
verified_with_no_match	The recipient's name does not match the name on the bank account.
verified_with_unable_to_match	The verification could not return a definitive result. This is because the recipient's bank does not support the verification check, or the verification service is unavailable.

Verification results do not block an import from reaching valid status. Even entries with a no_match result can proceed — the verification results are displayed on the dashboard during authorisation, so the approver can make an informed decision.

You can also retrieve individual verification results by using the List outbound payment import entries endpoint.

Each entry in the response includes a verification_result field with one of: full_match, partial_match, no_match, unable_to_match, or null (if verification has not yet been completed).

For more details, see Bank account holder verification.

Authorise the import

Once the import reaches valid status, it must be authorised through the GoCardless dashboard. The authorisation_url from the import creation response is a standard web link. You can present it in your application as a redirect or new window, or share it via email or a notification in your platform.

Action: Share the authorisation_url with the user who will authorise the import.

Imports that are not authorised within 3 calendar days of creation are automatically cancelled.

What the approver sees

When the approver visits the authorisation link, they sign in to the GoCardless dashboard and are taken to the import review pages.

1. Sign in to GoCardless

The approver enters their GoCardless dashboard credentials.

2. Review the import summary

The import process page displays a summary of the import, including:

The total number of payments
The total value of valid payments
The available balance on the source payment account

A summary of bank account holder verification results by category (full match, partial match, no match, unable to match).

3. Review individual entries

From the summary page, the approver can click through to review individual entries on the import detail page. This page shows a paginated table of all entries with the amount, recipient, reference, and bank account holder verification result for each.

4. Complete SCA and approve

When the approver is satisfied, they click the approve button. GoCardless sends an SMS code to the approver's registered phone number. The approver enters this code to complete Strong Customer Authentication (SCA) and authorise all payments in the import.

After entering the code, the import is authorised and transitions to processing. Each entry is automatically converted into an individual outbound payment — the resulting payments are submitted immediately and do not require separate approval.

Authorisation is all-or-nothing. You cannot approve or reject individual entries within an import. If any entries need to be corrected or removed, you must create a new import without those entries.

Track the result

After authorisation, the import moves through processing to processed. The import counts will contain `processed` and `failed_to_process`, indicating whether all payments were created successfully. To track the progress of the created payments, it is recommended to use webhooks.

Check processing status

Action: Poll the Get an outbound payment import endpoint until status is processed.

GET https://api.gocardless.com/outbound_payment_import_entries?import=IM123 HTTP/1.1
HTTP/1.1 200 OK
Content-Type: application/json
{
  "outbound_payment_import_entries": [
    {
      "id": "IE123",
      "created_at": "2024-09-05T12:20:04.397Z",
      "processed_at": "2024-09-05T12:35:10.000Z",
      "entry_number": 1,
      "amount": 1000,
      "scheme": "faster_payments",
      "reference": "INV-001",
      "verification_result": "full_match",
      "validation_errors": null,
      "links": {
        "import": "IM123",
        "outbound_payment": "OUT00456",
        "recipient_bank_account": "BA0001234"
      }
    },
    {
      "id": "IE124",
      "created_at": "2024-09-05T12:20:04.397Z",
      "processed_at": "2024-09-05T12:35:10.000Z",
      "entry_number": 2,
      "amount": 2500,
      "scheme": "faster_payments",
      "reference": "INV-002",
      "verification_result": "partial_match",
      "validation_errors": null,
      "links": {
        "import": "IM123",
        "outbound_payment": "OUT00457",
        "recipient_bank_account": "BA0005678"
      }
    }
  ],
  "meta": {
    "cursors": {
      "before": null,
      "after": null
    },
    "limit": 50
  }
}

Track the progress of created payments

Action: set up webhooks using this getting started guide. This is the recommended way of tracking the state of individual payments.

Once individual outbound payments are created from an import, they follow the standard outbound payment lifecycle and generate webhook events as their status changes. Each outbound payment includes the ID of the import that created it in links.outbound_payment_import.

Alternatively, list outbound payment import entries using the List outbound payment import entries endpoint. The links.outbound_payment field on each entry contains the ID of the created outbound payment. This ID can be used to track individual payment statuses through the standard outbound payment APIs.

Handling invalid imports

If any entry fails validation, the entire import transitions to invalid and cannot be authorised. To identify the errors and recover:

List the import's entries using the List outbound payment import entries endpoint.
Check the validation_errors field on each entry for per-field error details.
Fix the issues in your data.
Create a new import with the corrected entries.

An entry with validation errors looks like this:

{
  "id": "IE125",
  "created_at": "2024-09-05T12:20:04.397Z",
  "processed_at": null,
  "entry_number": 3,
  "amount": null,
  "scheme": null,
  "reference": null,
  "verification_result": null,
  "validation_errors": {
    "outbound_payment": {
      "amount": ["must be greater than 0"],
      "scheme": ["is not included in the list"]
    }
  },
  "links": {
    "import": "IM124",
    "outbound_payment": null,
    "recipient_bank_account": "BA0009999"
  }
}

The validation_errors.outbound_payment object contains error messages keyed by field name: amount, scheme, recipient_bank_account, or reference.

Invalid imports cannot be partially processed or edited. You must create a new import with corrected entries.

Once an import is cancelled — whether by expiry or otherwise — it cannot be reactivated. Create a new import instead.

Need help?

Connect as a partner