Outbound Payment Import

Outbound Payment Imports allow you to create multiple payments via a single API call.

The Workflow:

Create the outbound payment import.
Retrieve an authorisation link from the response.
Redirect the user to the link to authorise the import.
Once the user authorises the import, the individual outbound payments are automatically submitted.

Import entries are not processed as actual payments until they are reviewed and authorised in GoCardless Dashboard. Upon approval, a unique outbound payment is generated for every entry in the import.

Create an outbound payment import#

POST/outbound_payment_imports

HTTPRubyPythonJavaScriptPHPJavaGo.NET

POST https://api.gocardless.com/outbound_payment_imports HTTP/1.1
Content-Type: application/json
{
  "outbound_payment_imports": {
    "entry_items": [
      {
        "amount": 10,
        "scheme": "faster_payments",
        "reference": "MYX-123",
        "recipient_bank_account_id": "BA12343"
      },
      {
        "amount": 100,
        "scheme": "faster_payments",
        "reference": "MYX-222",
        "recipient_bank_account_id": "BA12343",
        "metadata": {
          "external_id": "123"
        }
      }
    ],
    "links": {
      "creditor": "CR123"
    }
  }
}

@client.outbound_payment_imports.create(
  params: {
    entry_items: [
      {
        amount: 1000,
        scheme: "faster_payments",
        reference: "Invoice 123",
        recipient_bank_account_id: "BA123"
      },
      {
        amount: 2000,
        scheme: "faster_payments",
        reference: "Invoice 124",
        recipient_bank_account_id: "BA456",
        metadata: {
          order_id: "ORD-789"
        }
      }
    ],
    links: {
      creditor: "CR123"
    }
  }
)

client.outbound_payment_imports.create(params={
  "entry_items": [
    {
      "amount": 1000,
      "scheme": "faster_payments",
      "reference": "Invoice 123",
      "recipient_bank_account_id": "BA123"
    },
    {
      "amount": 2000,
      "scheme": "faster_payments",
      "reference": "Invoice 124",
      "recipient_bank_account_id": "BA456",
      "metadata": {
        "order_id": "ORD-789"
      }
    }
  ],
  "links": {
    "creditor": "CR123"
  }
})

const outboundPaymentImport = await client.outboundPaymentImports.create({
  entry_items: [
    {
      amount: 1000,
      scheme: "faster_payments",
      reference: "Invoice 123",
      recipient_bank_account_id: "BA123"
    },
    {
      amount: 2000,
      scheme: "faster_payments",
      reference: "Invoice 124",
      recipient_bank_account_id: "BA456",
      metadata: {
        order_id: "ORD-789"
      }
    }
  ],
  links: {
    creditor: "CR123"
  }
});

$client->outboundPaymentImports()->create([
  "params" => [
    "entry_items" => [
      [
        "amount" => 1000,
        "scheme" => "faster_payments",
        "reference" => "Invoice 123",
        "recipient_bank_account_id" => "BA123"
      ],
      [
        "amount" => 2000,
        "scheme" => "faster_payments",
        "reference" => "Invoice 124",
        "recipient_bank_account_id" => "BA456",
        "metadata" => [
          "order_id" => "ORD-789"
        ]
      ]
    ],
    "links" => [
      "creditor" => "CR123"
    ]
  ]
]);

import com.gocardless.services.OutboundPaymentImportService.OutboundPaymentImportCreateRequest.EntryItems;
import com.gocardless.services.OutboundPaymentImportService.OutboundPaymentImportCreateRequest.EntryItems.Scheme;
import java.util.Arrays;
import java.util.HashMap;
import java.util.Map;

EntryItems entry1 = new EntryItems()
  .withAmount(1000)
  .withScheme(Scheme.FASTER_PAYMENTS)
  .withReference("Invoice 123")
  .withRecipientBankAccountId("BA123");

Map<String, String> metadata = new HashMap<>();
metadata.put("order_id", "ORD-789");

EntryItems entry2 = new EntryItems()
  .withAmount(2000)
  .withScheme(Scheme.FASTER_PAYMENTS)
  .withReference("Invoice 124")
  .withRecipientBankAccountId("BA456")
  .withMetadata(metadata);

OutboundPaymentImport outboundPaymentImport = client.outboundPaymentImports().create()
  .withEntryItems(Arrays.asList(entry1, entry2))
  .withLinksCreditor("CR123")
  .execute();

outboundPaymentImportCreateParams := gocardless.OutboundPaymentImportCreateParams{
  EntryItems: []gocardless.OutboundPaymentImportCreateParamsEntryItems{
    {
      Amount: 1000,
      Scheme: "faster_payments",
      Reference: "Invoice 123",
      RecipientBankAccountId: "BA123",
    },
    {
      Amount: 2000,
      Scheme: "faster_payments",
      Reference: "Invoice 124",
      RecipientBankAccountId: "BA456",
      Metadata: map[string]string{
        "order_id": "ORD-789",
      },
    },
  },
  Links: &gocardless.OutboundPaymentImportCreateParamsLinks{
    Creditor: "CR123",
  },
}

outboundPaymentImport, err := client.OutboundPaymentImports.Create(ctx, outboundPaymentImportCreateParams)

var entryItems = new GoCardless.Services.OutboundPaymentImportCreateRequest.OutboundPaymentImportEntryItems[]
{
  new GoCardless.Services.OutboundPaymentImportCreateRequest.OutboundPaymentImportEntryItems
  {
    Amount = 1000,
    Scheme = GoCardless.Services.OutboundPaymentImportCreateRequest.OutboundPaymentImportEntryItems.OutboundPaymentImportScheme.FasterPayments,
    Reference = "Invoice 123",
    RecipientBankAccountId = "BA123"
  },
  new GoCardless.Services.OutboundPaymentImportCreateRequest.OutboundPaymentImportEntryItems
  {
    Amount = 2000,
    Scheme = GoCardless.Services.OutboundPaymentImportCreateRequest.OutboundPaymentImportEntryItems.OutboundPaymentImportScheme.FasterPayments,
    Reference = "Invoice 124",
    RecipientBankAccountId = "BA456",
    Metadata = new Dictionary<string, string>
    {
      { "order_id", "ORD-789" }
    }
  }
};

var importLinks = new GoCardless.Services.OutboundPaymentImportCreateRequest.OutboundPaymentImportLinks
{
  Creditor = "CR123"
};

var resp = await client.OutboundPaymentImports.CreateAsync(
  new GoCardless.Services.OutboundPaymentImportCreateRequest()
  {
    EntryItems = entryItems,
    Links = importLinks,
  }
);

GoCardless.Resources.OutboundPaymentImport outboundPaymentImport = resp.OutboundPaymentImport;

Responsehttp

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

Request Body

outbound_payment_importsobject

2 properties

entry_itemsarray

5 properties

schemestring

Bank payment scheme to process the outbound payment. Currently only "faster_payments" (GBP) is supported.

faster_payments

amountinteger

Amount, in the lowest denomination for the currency (e.g. pence in GBP, cents in EUR).

recipient_bank_account_idstring

ID of the customer bank account which receives the outbound payment.

referencestring

An optional reference for the outbound payment.

metadataobject

Key-value store of custom data. Up to 3 keys are permitted, with key names up to 50 characters and values up to 500 characters.

linksobject

1 properties

creditorstring

ID of the creditor who sends the outbound payments from the import.

Response 201

Resource created successfully

outbound_payment_importsobject

8 properties

idstring

Unique identifier, beginning with "IM".

created_atstring

Fixed timestamp, recording when this resource was created.

statusstring

The status of the outbound payment import.

created: The initial state of a new import.
validating: Import validation in progress.
invalid: Import validation failed.
valid: Import validation succeeded.
processing: Authorisation received; payments are being generated.
processed: All entries have been successfully converted into outbound payments.
cancelled: The import was cancelled by a user or automatically expired by the system.

createdvalidatingvalidinvalidprocessingprocessedcancelled

amount_suminteger

The sum of all import entry amounts, in the lowest denomination for the currency (e.g. pence in GBP, cents in EUR).

currencystring

ISO 4217 currency. Currently only "GBP" is supported.

GBP

authorisation_urlstring

The link to the GoCardless dashboard to review and authorise the import

entry_countsobject

10 properties

totalinteger

The total number of entries included in the import.

validinteger

Count of entries that passed validation checks.

invalidinteger

Count of entries that failed validation checks.

processedinteger

Count of entries successfully converted into outbound payments after the import was authorised.

failed_to_processinteger

Count of entries that encountered a terminal error during the outbound payment generation process.

verifiedinteger

Total count of entries checked against bank account holder verification services (e.g., CoP).

verified_with_full_matchinteger

Count of entries where the account holder name was a direct match.

verified_with_partial_matchinteger

Count of entries where the account holder name was a close match.

verified_with_no_matchinteger

Count of entries where the account holder name did not match the records.

verified_with_unable_to_matchinteger

Count of entries where the verification service could not return a definitive result.

linksobject

1 properties

creditorstring

ID of the creditor who sends the outbound payments from the import.

Errors 400401404422500

400

Bad Request

401

Unauthorised

404

Not found

422

Validation Error

500

Internal Error

Error Body

codeinteger

documentation_urlstring

errorsarray

2 properties

reasonstring

messagestring

request_idstring

typestring

metadataobject

linksobject

List outbound payment imports#

GET/outbound_payment_imports

Returns a cursor-paginated list of your outbound payment imports.

HTTPRubyPythonJavaScriptPHPJavaGo.NET

GET https://api.gocardless.com/outbound_payment_imports HTTP/1.1

@client.outbound_payment_imports.list(params: { limit: 10 })

client.outbound_payment_imports.list(params={"limit": 10})

const resp = await client.outboundPaymentImports.list({
  limit: "10"
});

$client->outboundPaymentImports()->list([
  "params" => ["limit" => 10]
]);

client.outboundPaymentImports().list()
  .withLimit(10)
  .execute();

outboundPaymentImportListParams := gocardless.OutboundPaymentImportListParams{
  Limit: 10,
}

outboundPaymentImportListResult, err := client.OutboundPaymentImports.List(ctx, outboundPaymentImportListParams)

var request = new GoCardless.Services.OutboundPaymentImportListRequest()
{
  Limit = 10
};

var resp = await client.OutboundPaymentImports.ListAsync(request);

Responsehttp

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

Response 200

Successful response

outbound_payment_importsarray

8 properties

idstring

Unique identifier, beginning with "IM".

created_atstring

Fixed timestamp, recording when this resource was created.

statusstring

The status of the outbound payment import.

created: The initial state of a new import.
validating: Import validation in progress.
invalid: Import validation failed.
valid: Import validation succeeded.
processing: Authorisation received; payments are being generated.
processed: All entries have been successfully converted into outbound payments.
cancelled: The import was cancelled by a user or automatically expired by the system.

createdvalidatingvalidinvalidprocessingprocessedcancelled

amount_suminteger

The sum of all import entry amounts, in the lowest denomination for the currency (e.g. pence in GBP, cents in EUR).

currencystring

ISO 4217 currency. Currently only "GBP" is supported.

GBP

authorisation_urlstring

The link to the GoCardless dashboard to review and authorise the import

entry_countsobject

10 properties

totalinteger

The total number of entries included in the import.

validinteger

Count of entries that passed validation checks.

invalidinteger

Count of entries that failed validation checks.

processedinteger

Count of entries successfully converted into outbound payments after the import was authorised.

failed_to_processinteger

Count of entries that encountered a terminal error during the outbound payment generation process.

verifiedinteger

Total count of entries checked against bank account holder verification services (e.g., CoP).

verified_with_full_matchinteger

Count of entries where the account holder name was a direct match.

verified_with_partial_matchinteger

Count of entries where the account holder name was a close match.

verified_with_no_matchinteger

Count of entries where the account holder name did not match the records.

verified_with_unable_to_matchinteger

Count of entries where the verification service could not return a definitive result.

linksobject

1 properties

creditorstring

ID of the creditor who sends the outbound payments from the import.

metaobject

2 properties

limitinteger

cursorsobject

2 properties

beforestring

Cursor pointing to the end of the desired set.

afterstring

Cursor pointing to the start of the desired set.

Errors 400401404422500

400

Bad Request

401

Unauthorised

404

Not found

422

Validation Error

500

Internal Error

Error Body

codeinteger

documentation_urlstring

errorsarray

2 properties

reasonstring

messagestring

request_idstring

typestring

metadataobject

linksobject

Get an outbound payment import#

GET/outbound_payment_imports/{outbound_payment_import_id}

Returns a single outbound payment import.

Path Parameters

Name	Type	Description
`outbound_payment_import_id`required	string	The outbound payment import id

HTTPRubyPythonJavaScriptPHPJavaGo.NET

GET https://api.gocardless.com/outbound_payment_imports/IM123 HTTP/1.1

@client.outbound_payment_imports.get("IM123")

client.outbound_payment_imports.get("IM123")

const resp = await client.outboundPaymentImports.find("IM123");

$client->outboundPaymentImports()->get("IM123");

client.outboundPaymentImports().get("IM123").execute();

outboundPaymentImport, err := client.OutboundPaymentImports.Get(ctx, "IM123", gocardless.OutboundPaymentImportGetParams{})

var resp = await client.OutboundPaymentImports.GetAsync("IM123");

Responsehttp

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

Response 200

Successful response

outbound_payment_importsobject

8 properties

idstring

Unique identifier, beginning with "IM".

created_atstring

Fixed timestamp, recording when this resource was created.

statusstring

The status of the outbound payment import.

created: The initial state of a new import.
validating: Import validation in progress.
invalid: Import validation failed.
valid: Import validation succeeded.
processing: Authorisation received; payments are being generated.
processed: All entries have been successfully converted into outbound payments.
cancelled: The import was cancelled by a user or automatically expired by the system.

createdvalidatingvalidinvalidprocessingprocessedcancelled

amount_suminteger

The sum of all import entry amounts, in the lowest denomination for the currency (e.g. pence in GBP, cents in EUR).

currencystring

ISO 4217 currency. Currently only "GBP" is supported.

GBP

authorisation_urlstring

The link to the GoCardless dashboard to review and authorise the import

entry_countsobject

10 properties

totalinteger

The total number of entries included in the import.

validinteger

Count of entries that passed validation checks.

invalidinteger

Count of entries that failed validation checks.

processedinteger

Count of entries successfully converted into outbound payments after the import was authorised.

failed_to_processinteger

Count of entries that encountered a terminal error during the outbound payment generation process.

verifiedinteger

Total count of entries checked against bank account holder verification services (e.g., CoP).

verified_with_full_matchinteger

Count of entries where the account holder name was a direct match.

verified_with_partial_matchinteger

Count of entries where the account holder name was a close match.

verified_with_no_matchinteger

Count of entries where the account holder name did not match the records.

verified_with_unable_to_matchinteger

Count of entries where the verification service could not return a definitive result.

linksobject

1 properties

creditorstring

ID of the creditor who sends the outbound payments from the import.

Errors 400401404422500

400

Bad Request

401

Unauthorised

404

Not found

422

Validation Error

500

Internal Error

Error Body

codeinteger

documentation_urlstring

errorsarray

2 properties

reasonstring

messagestring

request_idstring

typestring

metadataobject

linksobject