Importing outbound payments#

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:

Import statuses#

Create the import#

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.

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.

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:

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.

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.

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#

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#

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:

1. List the import's entries using the List outbound payment import entries endpoint.
2. Check the validation_errors field on each entry for per-field error details.
3. Fix the issues in your data.
4. 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.

Monitoring your imports#

Use the List outbound payment imports endpoint to check status and see whether an import is ready to be approved. Use the List outbound payment import entries endpoint to inspect individual entries, including any validation_errors on an invalid import.

Expiry and cancellation#

Imports in valid status that are not authorised within 3 calendar days of creation are automatically cancelled by the system.

There is no API endpoint to cancel an import. If you need to discard an import, create a new one and let the old one expire.

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

What's Next?#