GoCardlessDeveloper Docs
Create a sandbox account

Payment

View as Markdown

Payment objects represent payments from a customer to a creditor, taken against a Direct Debit mandate.

GoCardless will notify you via a webhook whenever the state of a payment changes.

Create a payment#

POST/payments

Creates a new payment object.

This fails with a mandate_is_inactive error if the linked mandate is cancelled or has failed. Payments can be created against mandates with status of: pending_customer_approval, pending_submission, submitted, and active.

POST https://api.gocardless.com/payments HTTP/1.1
Content-Type: application/json
{
  "payments": {
    "amount": 100,
    "currency": "GBP",
    "charge_date": "2014-05-19",
    "reference": "WINEBOX001",
    "metadata": {
      "order_dispatch_date": "2014-05-22"
    },
    "links": {
      "mandate": "MD123"
    }
  }
}
@client.payments.create(
  params: {
    amount: 1000,
    currency: "GBP",
    description: "Club membership fee",
    links: {
      mandate: "MD123"
    }
  },
  headers: {
    "Idempotency-Key" => "aaf50eb0-8ddb-4900-a97b-40ed794570a1"
  }
)
client.payments.create(params={
  "amount": 100,
  "currency": "GBP",
  "charge_date": "2014-05-19",
  "reference": "WINEBOX001",
  "metadata": {
    "order_dispatch_date": "2014-05-22"
  },
  "links": {
    "mandate": "MD123"
  }
})
const payment = await client.payments.create({
  amount: "100",
  currency: "GBP",
  charge_date: "2014-05-19",
  reference: "WINEBOX001",
  metadata: {
    order_dispatch_date: "2014-05-22"
  },
  links: {
    mandate: "MD123"
  }
});
$client->payments()->create([
  "params" => ["amount" => 100,
               "currency" => "GBP",
               "metadata" => [
                 "order_dispatch_date" => "2016-08-04"
               ],
               "links" => [
                 "mandate" => "MD123"
               ]]
]);
import com.gocardless.services.PaymentService.PaymentCreateRequest.Currency;

Payment payment = client.payments().create()
  .withAmount(100)
  .withCurrency(Currency.GBP)
  .withChargeDate("2014-05-19")
  .withReference("WINEBOX001")
  .withMetadata("order_dispatch_date", "2014-05-22")
  .withLinksMandate("MD123")
  .execute();
paymentCreateParams := gocardless.PaymentCreateParams{
  Amount:     100,
  Currency:   "GBP",
  ChargeDate: "2014-05-19",
  Reference:  "WINEBOX001",
  Metadata:   map[string]string{"order_dispatch_date": "2014-05-22"},
  Links: gocardless.PaymentCreateParamsLinks{
    Mandate: "MD123",
  },
}

payment, err := client.Payments.Create(ctx, paymentCreateParams)
var paymentRequest = new GoCardless.Services.PaymentCreateRequest()
{
    Amount = 1000,
    Currency = GoCardless.Services.PaymentCreateRequest.PaymentCurrency.GBP,
    Description = "Membership fee",
    Links = new GoCardless.Services.PaymentCreateRequest.PaymentLinks()
    {
        Mandate = "MD0123"
    }
};

var paymentResponse = await client.Payments.CreateAsync(paymentRequest);
GoCardless.Resources.Payment payment = paymentResponse.Payment;
Responsehttp
HTTP/1.1 201 Created
Location: /payments/PM123
Content-Type: application/json
{
  "payments": {
    "id": "PM123",
    "created_at": "2014-05-08T17:01:06.000Z",
    "charge_date": "2014-05-21",
    "amount": 100,
    "description": null,
    "currency": "GBP",
    "status": "pending_submission",
    "reference": "WINEBOX001",
    "metadata": {
      "order_dispatch_date": "2014-05-22"
    },
    "amount_refunded": 0,
    "fx": {
      "fx_currency": "EUR",
      "fx_amount": null,
      "exchange_rate": null,
      "estimated_exchange_rate": "1.1234567890"
    },
    "links": {
      "mandate": "MD123",
      "creditor": "CR123"
    },
    "retry_if_possible": false
  }
}
Request Body
paymentsobject
11 properties
amountobject

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

Minimum and maximum amounts vary by payment scheme. For more information, see Transaction limits

For Variable Recurring Payments (VRP), this must not exceed the mandate's max_amount_per_payment constraint.

currencystring

ISO 4217 currency code. Currently "AUD", "CAD", "DKK", "EUR", "GBP", "NZD", "SEK" and "USD" are supported.

AUDCADDKKEURGBPNZDSEKUSD
descriptionstring

A human-readable description of the payment. This will be included in the notification email GoCardless sends to your customer if your organisation does not send its own notifications (see compliance requirements).

charge_datestring

A future date on which the payment should be collected. If not specified, the payment will be collected as soon as possible. If the value is before the mandate's next_possible_charge_date creation will fail. If the value is not a working day it will be rolled forwards to the next available one.

referencestring

An optional reference that will appear on your customer's bank statement. The character limit for this reference is dependent on the scheme.
ACH - 10 characters
Autogiro - 11 characters
Bacs - 10 characters
BECS - 30 characters
BECS NZ - 12 characters
Betalingsservice - 30 characters
Faster Payments - 18 characters
PAD - scheme doesn't offer references
PayTo - 18 characters
SEPA - 140 characters
Note that this reference must be unique (for each merchant) for the BECS scheme as it is a scheme requirement.

Restricted: You can only specify a payment reference for Bacs payments (that is, when collecting from the UK) if you're on the GoCardless Plus, Pro or Enterprise packages.

Restricted: You can not specify a payment reference for Faster Payments.

app_feeobject

The amount to be deducted from the payment as the OAuth app's fee, in the lowest denomination for the currency (e.g. pence in GBP, cents in EUR).

retry_if_possibleboolean

On failure, automatically retry the payment using intelligent retries. Default is false.

Important: To be able to use intelligent retries, Success+ needs to be enabled in GoCardless dashboard.

faster_achboolean

Set this to true or false in the request to create an ACH payment to explicitly choose whether the payment should be processed through Faster ACH or standard ACH, rather than relying on the presence or absence of the charge date to indicate that.

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.

psu_interaction_typestring

Indicates how a Variable Recurring Payment (VRP) is initiated, by or on behalf of the payer.

  • in_session: The payer is actively participating in the payment creation session.
  • off_session: The payer is not present during the transaction, and the payment is initiated by the merchant based on an established consent (e.g., a recurring subscription payment).
in_sessionoff_session
linksobject
1 properties
mandatestring

ID of the mandate against which this payment should be collected.

Response 201

Resource created successfully

paymentsobject
15 properties
idstring

Unique identifier, beginning with "PM".

created_atstring

Fixed timestamp, recording when this resource was created.

amountobject

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

Minimum and maximum amounts vary by payment scheme. For more information, see Transaction limits

For Variable Recurring Payments (VRP), this must not exceed the mandate's max_amount_per_payment constraint.

amount_refundedobject

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

currencystring

ISO 4217 currency code. Currently "AUD", "CAD", "DKK", "EUR", "GBP", "NZD", "SEK" and "USD" are supported.

AUDCADDKKEURGBPNZDSEKUSD
descriptionstring

A human-readable description of the payment. This will be included in the notification email GoCardless sends to your customer if your organisation does not send its own notifications (see compliance requirements).

charge_datestring

A future date on which the payment should be collected. If not specified, the payment will be collected as soon as possible. If the value is before the mandate's next_possible_charge_date creation will fail. If the value is not a working day it will be rolled forwards to the next available one.

referencestring

An optional reference that will appear on your customer's bank statement. The character limit for this reference is dependent on the scheme.
ACH - 10 characters
Autogiro - 11 characters
Bacs - 10 characters
BECS - 30 characters
BECS NZ - 12 characters
Betalingsservice - 30 characters
Faster Payments - 18 characters
PAD - scheme doesn't offer references
PayTo - 18 characters
SEPA - 140 characters
Note that this reference must be unique (for each merchant) for the BECS scheme as it is a scheme requirement.

Restricted: You can only specify a payment reference for Bacs payments (that is, when collecting from the UK) if you're on the GoCardless Plus, Pro or Enterprise packages.

Restricted: You can not specify a payment reference for Faster Payments.

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.

statusstring

One of:

  • pending_customer_approval: we're waiting for the customer to approve this payment
  • pending_submission: the payment has been created, but not yet submitted to the banks
  • submitted: the payment has been submitted to the banks
  • confirmed: the payment has been confirmed as collected
  • paid_out: the payment has been included in a payout
  • cancelled: the payment has been cancelled
  • customer_approval_denied: the customer has denied approval for the payment. You should contact the customer directly
  • failed: the payment failed to be processed. Note that payments can fail after being confirmed if the failure message is sent late by the banks.
  • charged_back: the payment has been charged back
pending_customer_approvalpending_submissionsubmittedconfirmedpaid_outcancelledcustomer_approval_deniedfailedcharged_back
linksobject
5 properties
mandatestring

ID of the mandate against which this payment should be collected.

creditorstring

ID of creditor to which the collected payment will be sent.

payoutstring

ID of payout which contains the funds from this payment.
Note: this property will not be present until the payment has been successfully collected.

subscriptionstring

ID of subscription from which this payment was created.
Note: this property will only be present if this payment is part of a subscription.

instalment_schedulestring

ID of instalment_schedule from which this payment was created.
Note: this property will only be present if this payment is part of an instalment schedule.

faster_achboolean

This field indicates whether the ACH payment is processed through Faster ACH or standard ACH.

It is only present in the API response for ACH payments.

fxobject
4 properties
exchange_ratestring

Rate used in the foreign exchange of the amount into the fx_currency. Present only after a resource is paid out. Has up to 10 decimal places.

estimated_exchange_ratestring

Estimated rate that will be used in the foreign exchange of the amount into the fx_currency. This will vary based on the prevailing market rate until the moment that it is paid out. Present only before a resource is paid out. Has up to 10 decimal places.

fx_amountobject

Amount that was paid out in the fx_currency after foreign exchange. Present only after the resource has been paid out.

fx_currencystring

ISO 4217 code for the currency in which amounts will be paid out (after foreign exchange). Currently "AUD", "CAD", "DKK", "EUR", "GBP", "NZD", "SEK" and "USD" are supported. Present only if payouts will be (or were) made via foreign exchange.

AUDCADDKKEURGBPNZDSEKUSD
retry_if_possibleboolean

On failure, automatically retry the payment using intelligent retries. Default is false.

Important: To be able to use intelligent retries, Success+ needs to be enabled in GoCardless dashboard.

schemestring

A bank payment scheme. Currently "ach", "autogiro", "bacs", "becs", "becs_nz", "betalingsservice", "faster_payments", "pad", "pay_to", "sepa_core", "sepa_credit_transfer" and "sepa_instant_credit_transfer" are supported.

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
messagestring
request_idstring
typestring
metadataobject
linksobject

List payments#

GET/payments

Returns a cursor-paginated list of your payments.

GET https://api.gocardless.com/payments HTTP/1.1
@client.payments.list

@client.payments.list(params: { customer: "CU123" })

@client.payments.list.records.each { |payment| puts payment.inspect }
client.payments.list().records

client.payments.list(params={"customer": "CU123"}).records
const payments = await client.payments.list();

// List all payments past a certain date.
const filteredPayments = await client.payments.list({
  created_at: {
    gt: "2020-01-01T17:01:06.000Z"
  }
});
$client->payments()->list();

$client->payments()->list([
  "params" => ["customer" => "CU123"]
]);
for (Payment payment : client.payments().all().withCustomer("CU123").execute()) {
  System.out.println(payment.getId());
}
paymentListParams := gocardless.PaymentListParams{
  CreatedAt: &gocardless.PaymentListParamsCreatedAt{
    Gt: "2020-01-01T17:01:06.000Z",
  },
}

paymentListResult, err := client.Payments.List(ctx, paymentListParams)
for _, payment := range paymentListResult.Payments {
    fmt.Println(payment.Id)
}
var paymentRequest = new GoCardless.Services.PaymentListRequest()
{
    Customer = "CU000123"
};

var paymentListResponse = client.Payments.All(paymentRequest);
foreach (GoCardless.Resources.Payment payment in paymentListResponse)
{
    Console.WriteLine(payment.Id);
}
Responsehttp
HTTP/1.1 200 OK
Content-Type: application/json
{
  "meta": {
    "cursors": {
      "before": null,
      "after": null
    },
    "limit": 50
  },
  "payments": [{
    "id": "PM123",
    "created_at": "2014-05-08T17:01:06.000Z",
    "charge_date": "2014-05-15",
    "amount": 100,
    "description": null,
    "currency": "GBP",
    "status": "pending_submission",
    "reference": "WINEBOX001",
    "metadata": {
      "order_dispatch_date": "2014-05-22"
    },
    "amount_refunded": 0,
    "fx": {
      "fx_currency": "EUR",
      "fx_amount": null,
      "exchange_rate": null,
      "estimated_exchange_rate": "1.1234567890"
    },
    "links": {
      "mandate": "MD123",
      "creditor": "CR123"
    },
    "retry_if_possible": false
  }]
}
Response 200

Successful response

paymentsarray
15 properties
idstring

Unique identifier, beginning with "PM".

created_atstring

Fixed timestamp, recording when this resource was created.

amountobject

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

Minimum and maximum amounts vary by payment scheme. For more information, see Transaction limits

For Variable Recurring Payments (VRP), this must not exceed the mandate's max_amount_per_payment constraint.

amount_refundedobject

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

currencystring

ISO 4217 currency code. Currently "AUD", "CAD", "DKK", "EUR", "GBP", "NZD", "SEK" and "USD" are supported.

AUDCADDKKEURGBPNZDSEKUSD
descriptionstring

A human-readable description of the payment. This will be included in the notification email GoCardless sends to your customer if your organisation does not send its own notifications (see compliance requirements).

charge_datestring

A future date on which the payment should be collected. If not specified, the payment will be collected as soon as possible. If the value is before the mandate's next_possible_charge_date creation will fail. If the value is not a working day it will be rolled forwards to the next available one.

referencestring

An optional reference that will appear on your customer's bank statement. The character limit for this reference is dependent on the scheme.
ACH - 10 characters
Autogiro - 11 characters
Bacs - 10 characters
BECS - 30 characters
BECS NZ - 12 characters
Betalingsservice - 30 characters
Faster Payments - 18 characters
PAD - scheme doesn't offer references
PayTo - 18 characters
SEPA - 140 characters
Note that this reference must be unique (for each merchant) for the BECS scheme as it is a scheme requirement.

Restricted: You can only specify a payment reference for Bacs payments (that is, when collecting from the UK) if you're on the GoCardless Plus, Pro or Enterprise packages.

Restricted: You can not specify a payment reference for Faster Payments.

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.

statusstring

One of:

  • pending_customer_approval: we're waiting for the customer to approve this payment
  • pending_submission: the payment has been created, but not yet submitted to the banks
  • submitted: the payment has been submitted to the banks
  • confirmed: the payment has been confirmed as collected
  • paid_out: the payment has been included in a payout
  • cancelled: the payment has been cancelled
  • customer_approval_denied: the customer has denied approval for the payment. You should contact the customer directly
  • failed: the payment failed to be processed. Note that payments can fail after being confirmed if the failure message is sent late by the banks.
  • charged_back: the payment has been charged back
pending_customer_approvalpending_submissionsubmittedconfirmedpaid_outcancelledcustomer_approval_deniedfailedcharged_back
linksobject
5 properties
mandatestring

ID of the mandate against which this payment should be collected.

creditorstring

ID of creditor to which the collected payment will be sent.

payoutstring

ID of payout which contains the funds from this payment.
Note: this property will not be present until the payment has been successfully collected.

subscriptionstring

ID of subscription from which this payment was created.
Note: this property will only be present if this payment is part of a subscription.

instalment_schedulestring

ID of instalment_schedule from which this payment was created.
Note: this property will only be present if this payment is part of an instalment schedule.

faster_achboolean

This field indicates whether the ACH payment is processed through Faster ACH or standard ACH.

It is only present in the API response for ACH payments.

fxobject
4 properties
exchange_ratestring

Rate used in the foreign exchange of the amount into the fx_currency. Present only after a resource is paid out. Has up to 10 decimal places.

estimated_exchange_ratestring

Estimated rate that will be used in the foreign exchange of the amount into the fx_currency. This will vary based on the prevailing market rate until the moment that it is paid out. Present only before a resource is paid out. Has up to 10 decimal places.

fx_amountobject

Amount that was paid out in the fx_currency after foreign exchange. Present only after the resource has been paid out.

fx_currencystring

ISO 4217 code for the currency in which amounts will be paid out (after foreign exchange). Currently "AUD", "CAD", "DKK", "EUR", "GBP", "NZD", "SEK" and "USD" are supported. Present only if payouts will be (or were) made via foreign exchange.

AUDCADDKKEURGBPNZDSEKUSD
retry_if_possibleboolean

On failure, automatically retry the payment using intelligent retries. Default is false.

Important: To be able to use intelligent retries, Success+ needs to be enabled in GoCardless dashboard.

schemestring

A bank payment scheme. Currently "ach", "autogiro", "bacs", "becs", "becs_nz", "betalingsservice", "faster_payments", "pad", "pay_to", "sepa_core", "sepa_credit_transfer" and "sepa_instant_credit_transfer" are supported.

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
messagestring
request_idstring
typestring
metadataobject
linksobject

Get a single payment#

GET/payments/{payment_id}

Retrieves the details of a single existing payment.

Path Parameters

NameTypeDescription
payment_idrequiredstring

The payment id

GET https://api.gocardless.com/payments/PM123 HTTP/1.1
@client.payments.get("PM123")
client.payments.get("PM123")
const payment = await client.payments.find("PM123");
$client->payments()->get("PM123");
Payment payment = client.payments().get("PM123").execute();
payment, err := client.Payments.Get(ctx, "PM123")
var paymentResponse = await client.Payments.GetAsync("PM0123");
GoCardless.Resources.Payment payment = paymentResponse.Payment;
Responsehttp
HTTP/1.1 200 OK
Content-Type: application/json
{
  "payments": {
    "id": "PM123",
    "created_at": "2014-05-08T17:01:06.000Z",
    "charge_date": "2014-05-15",
    "amount": 100,
    "description": null,
    "currency": "GBP",
    "status": "pending_submission",
    "reference": "WINEBOX001",
    "metadata": {
      "order_dispatch_date": "2014-05-22"
    },
    "amount_refunded": 0,
    "fx": {
      "fx_currency": "EUR",
      "fx_amount": null,
      "exchange_rate": null,
      "estimated_exchange_rate": "1.1234567890"
    },
    "links": {
      "mandate": "MD123",
      "creditor": "CR123"
    },
    "retry_if_possible": false
  }
}
Response 200

Successful response

paymentsobject
15 properties
idstring

Unique identifier, beginning with "PM".

created_atstring

Fixed timestamp, recording when this resource was created.

amountobject

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

Minimum and maximum amounts vary by payment scheme. For more information, see Transaction limits

For Variable Recurring Payments (VRP), this must not exceed the mandate's max_amount_per_payment constraint.

amount_refundedobject

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

currencystring

ISO 4217 currency code. Currently "AUD", "CAD", "DKK", "EUR", "GBP", "NZD", "SEK" and "USD" are supported.

AUDCADDKKEURGBPNZDSEKUSD
descriptionstring

A human-readable description of the payment. This will be included in the notification email GoCardless sends to your customer if your organisation does not send its own notifications (see compliance requirements).

charge_datestring

A future date on which the payment should be collected. If not specified, the payment will be collected as soon as possible. If the value is before the mandate's next_possible_charge_date creation will fail. If the value is not a working day it will be rolled forwards to the next available one.

referencestring

An optional reference that will appear on your customer's bank statement. The character limit for this reference is dependent on the scheme.
ACH - 10 characters
Autogiro - 11 characters
Bacs - 10 characters
BECS - 30 characters
BECS NZ - 12 characters
Betalingsservice - 30 characters
Faster Payments - 18 characters
PAD - scheme doesn't offer references
PayTo - 18 characters
SEPA - 140 characters
Note that this reference must be unique (for each merchant) for the BECS scheme as it is a scheme requirement.

Restricted: You can only specify a payment reference for Bacs payments (that is, when collecting from the UK) if you're on the GoCardless Plus, Pro or Enterprise packages.

Restricted: You can not specify a payment reference for Faster Payments.

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.

statusstring

One of:

  • pending_customer_approval: we're waiting for the customer to approve this payment
  • pending_submission: the payment has been created, but not yet submitted to the banks
  • submitted: the payment has been submitted to the banks
  • confirmed: the payment has been confirmed as collected
  • paid_out: the payment has been included in a payout
  • cancelled: the payment has been cancelled
  • customer_approval_denied: the customer has denied approval for the payment. You should contact the customer directly
  • failed: the payment failed to be processed. Note that payments can fail after being confirmed if the failure message is sent late by the banks.
  • charged_back: the payment has been charged back
pending_customer_approvalpending_submissionsubmittedconfirmedpaid_outcancelledcustomer_approval_deniedfailedcharged_back
linksobject
5 properties
mandatestring

ID of the mandate against which this payment should be collected.

creditorstring

ID of creditor to which the collected payment will be sent.

payoutstring

ID of payout which contains the funds from this payment.
Note: this property will not be present until the payment has been successfully collected.

subscriptionstring

ID of subscription from which this payment was created.
Note: this property will only be present if this payment is part of a subscription.

instalment_schedulestring

ID of instalment_schedule from which this payment was created.
Note: this property will only be present if this payment is part of an instalment schedule.

faster_achboolean

This field indicates whether the ACH payment is processed through Faster ACH or standard ACH.

It is only present in the API response for ACH payments.

fxobject
4 properties
exchange_ratestring

Rate used in the foreign exchange of the amount into the fx_currency. Present only after a resource is paid out. Has up to 10 decimal places.

estimated_exchange_ratestring

Estimated rate that will be used in the foreign exchange of the amount into the fx_currency. This will vary based on the prevailing market rate until the moment that it is paid out. Present only before a resource is paid out. Has up to 10 decimal places.

fx_amountobject

Amount that was paid out in the fx_currency after foreign exchange. Present only after the resource has been paid out.

fx_currencystring

ISO 4217 code for the currency in which amounts will be paid out (after foreign exchange). Currently "AUD", "CAD", "DKK", "EUR", "GBP", "NZD", "SEK" and "USD" are supported. Present only if payouts will be (or were) made via foreign exchange.

AUDCADDKKEURGBPNZDSEKUSD
retry_if_possibleboolean

On failure, automatically retry the payment using intelligent retries. Default is false.

Important: To be able to use intelligent retries, Success+ needs to be enabled in GoCardless dashboard.

schemestring

A bank payment scheme. Currently "ach", "autogiro", "bacs", "becs", "becs_nz", "betalingsservice", "faster_payments", "pad", "pay_to", "sepa_core", "sepa_credit_transfer" and "sepa_instant_credit_transfer" are supported.

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
messagestring
request_idstring
typestring
metadataobject
linksobject

Update a payment#

PUT/payments/{payment_id}

Updates a payment object. This accepts only the metadata parameter.

Path Parameters

NameTypeDescription
payment_idrequiredstring

The payment id

PUT https://api.gocardless.com/payments/PM123 HTTP/1.1
Content-Type: application/json
{
  "payments": {
    "metadata": {
      "key": "value"
    }
  }
}
@client.payments.update(
  "PM123",
  params: {
    metadata: { order_id: "transaction-0HE9WQ0WDE" }
  }
)
client.payments.update("PM123", params={
  "metadata": {"key": "value"}
})
const payment = await client.payments.update(
  "PM123",
  {
    metadata: {
      key: "value"
    }
  }
);
$client->payments()->update("PM123", [
  "params" => ["metadata" => ["internal_id" => "XX123"]]
]);
client.payments().update("PM123")
  .withMetadata("order_id", "transaction-0HE9WQ0WDE")
  .execute();
paymentUpdateParams := gocardless.PaymentUpdateParams{
  Metadata: map[string]string{"key": "value"},
}

payment, err := client.Payments.Update(ctx, "PM123", paymentUpdateParams)
var paymentRequest = new GoCardless.Services.PaymentUpdateRequest()
{
    Metadata = new Dictionary<string, string>()
    {
        {"invoice_id", "INVOICE338"}
    }
};

var paymentResponse = await client.Payments.UpdateAsync("PM0123", paymentRequest);
Responsehttp
HTTP/1.1 200 OK
Content-Type: application/json
{
  "payments": {
    "id": "PM123",
    "created_at": "2014-05-08T17:01:06.000Z",
    "charge_date": "2014-05-15",
    "amount": 100,
    "description": null,
    "currency": "GBP",
    "status": "pending_submission",
    "reference": "WINEBOX001",
    "metadata": {
      "key": "value"
    },
    "amount_refunded": 0,
    "fx": {
      "fx_currency": "EUR",
      "fx_amount": null,
      "exchange_rate": null,
      "estimated_exchange_rate": "1.1234567890"
    },
    "links": {
      "mandate": "MD123",
      "creditor": "CR123"
    },
    "retry_if_possible": false
  }
}
Request Body
paymentsobject
2 properties
retry_if_possibleboolean

On failure, automatically retry the payment using intelligent retries. Default is false.

Important: To be able to use intelligent retries, Success+ needs to be enabled in GoCardless dashboard.

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.

Response 200

Successful response

paymentsobject
15 properties
idstring

Unique identifier, beginning with "PM".

created_atstring

Fixed timestamp, recording when this resource was created.

amountobject

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

Minimum and maximum amounts vary by payment scheme. For more information, see Transaction limits

For Variable Recurring Payments (VRP), this must not exceed the mandate's max_amount_per_payment constraint.

amount_refundedobject

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

currencystring

ISO 4217 currency code. Currently "AUD", "CAD", "DKK", "EUR", "GBP", "NZD", "SEK" and "USD" are supported.

AUDCADDKKEURGBPNZDSEKUSD
descriptionstring

A human-readable description of the payment. This will be included in the notification email GoCardless sends to your customer if your organisation does not send its own notifications (see compliance requirements).

charge_datestring

A future date on which the payment should be collected. If not specified, the payment will be collected as soon as possible. If the value is before the mandate's next_possible_charge_date creation will fail. If the value is not a working day it will be rolled forwards to the next available one.

referencestring

An optional reference that will appear on your customer's bank statement. The character limit for this reference is dependent on the scheme.
ACH - 10 characters
Autogiro - 11 characters
Bacs - 10 characters
BECS - 30 characters
BECS NZ - 12 characters
Betalingsservice - 30 characters
Faster Payments - 18 characters
PAD - scheme doesn't offer references
PayTo - 18 characters
SEPA - 140 characters
Note that this reference must be unique (for each merchant) for the BECS scheme as it is a scheme requirement.

Restricted: You can only specify a payment reference for Bacs payments (that is, when collecting from the UK) if you're on the GoCardless Plus, Pro or Enterprise packages.

Restricted: You can not specify a payment reference for Faster Payments.

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.

statusstring

One of:

  • pending_customer_approval: we're waiting for the customer to approve this payment
  • pending_submission: the payment has been created, but not yet submitted to the banks
  • submitted: the payment has been submitted to the banks
  • confirmed: the payment has been confirmed as collected
  • paid_out: the payment has been included in a payout
  • cancelled: the payment has been cancelled
  • customer_approval_denied: the customer has denied approval for the payment. You should contact the customer directly
  • failed: the payment failed to be processed. Note that payments can fail after being confirmed if the failure message is sent late by the banks.
  • charged_back: the payment has been charged back
pending_customer_approvalpending_submissionsubmittedconfirmedpaid_outcancelledcustomer_approval_deniedfailedcharged_back
linksobject
5 properties
mandatestring

ID of the mandate against which this payment should be collected.

creditorstring

ID of creditor to which the collected payment will be sent.

payoutstring

ID of payout which contains the funds from this payment.
Note: this property will not be present until the payment has been successfully collected.

subscriptionstring

ID of subscription from which this payment was created.
Note: this property will only be present if this payment is part of a subscription.

instalment_schedulestring

ID of instalment_schedule from which this payment was created.
Note: this property will only be present if this payment is part of an instalment schedule.

faster_achboolean

This field indicates whether the ACH payment is processed through Faster ACH or standard ACH.

It is only present in the API response for ACH payments.

fxobject
4 properties
exchange_ratestring

Rate used in the foreign exchange of the amount into the fx_currency. Present only after a resource is paid out. Has up to 10 decimal places.

estimated_exchange_ratestring

Estimated rate that will be used in the foreign exchange of the amount into the fx_currency. This will vary based on the prevailing market rate until the moment that it is paid out. Present only before a resource is paid out. Has up to 10 decimal places.

fx_amountobject

Amount that was paid out in the fx_currency after foreign exchange. Present only after the resource has been paid out.

fx_currencystring

ISO 4217 code for the currency in which amounts will be paid out (after foreign exchange). Currently "AUD", "CAD", "DKK", "EUR", "GBP", "NZD", "SEK" and "USD" are supported. Present only if payouts will be (or were) made via foreign exchange.

AUDCADDKKEURGBPNZDSEKUSD
retry_if_possibleboolean

On failure, automatically retry the payment using intelligent retries. Default is false.

Important: To be able to use intelligent retries, Success+ needs to be enabled in GoCardless dashboard.

schemestring

A bank payment scheme. Currently "ach", "autogiro", "bacs", "becs", "becs_nz", "betalingsservice", "faster_payments", "pad", "pay_to", "sepa_core", "sepa_credit_transfer" and "sepa_instant_credit_transfer" are supported.

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
messagestring
request_idstring
typestring
metadataobject
linksobject

Cancel a payment#

POST/payments/{payment_id}/actions/cancel

Cancels the payment if it has not already been submitted to the banks. Any metadata supplied to this endpoint will be stored on the payment cancellation event it causes.

This will fail with a cancellation_failed error unless the payment's status is pending_submission.

Path Parameters

NameTypeDescription
payment_idrequiredstring

The payment id

POST https://api.gocardless.com/payments/PM123/actions/cancel HTTP/1.1
Content-Type: application/json
{
  "data": {
    "metadata": {
      "ticket_id": "TK123"
    }
  }
}
@client.payments.cancel("PM123")
client.payments.cancel("PM123")
const paymentResponse = await client.payments.cancel("PM123");
$client->payments()->cancel("PM123");
client.payments().cancel("PM123").execute();
paymentCancelParams := gocardless.PaymentCancelParams{}
payment, err := client.Payments.Cancel(ctx, "PM123", paymentCancelParams)
var paymentResponse = await client.Payments.CancelAsync("PM0123");
Responsehttp
HTTP/1.1 200 OK
Content-Type: application/json
{
  "payments": {
    "id": "PM123",
    "created_at": "2014-05-08T17:01:06.000Z",
    "charge_date": "2014-05-21",
    "amount": 100,
    "description": null,
    "currency": "GBP",
    "status": "cancelled",
    "reference": "WINEBOX001",
    "metadata": {
      "order_dispatch_date": "2014-05-22"
    },
    "amount_refunded": 0,
    "fx": {
      "fx_currency": "EUR",
      "fx_amount": null,
      "exchange_rate": null,
      "estimated_exchange_rate": "1.1234567890"
    },
    "links": {
      "mandate": "MD123",
      "creditor": "CR123"
    },
    "retry_if_possible": false
  }
}
Request Body
paymentsobject
1 properties
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.

Response 200

Action completed successfully

paymentsobject
15 properties
idstring

Unique identifier, beginning with "PM".

created_atstring

Fixed timestamp, recording when this resource was created.

amountobject

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

Minimum and maximum amounts vary by payment scheme. For more information, see Transaction limits

For Variable Recurring Payments (VRP), this must not exceed the mandate's max_amount_per_payment constraint.

amount_refundedobject

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

currencystring

ISO 4217 currency code. Currently "AUD", "CAD", "DKK", "EUR", "GBP", "NZD", "SEK" and "USD" are supported.

AUDCADDKKEURGBPNZDSEKUSD
descriptionstring

A human-readable description of the payment. This will be included in the notification email GoCardless sends to your customer if your organisation does not send its own notifications (see compliance requirements).

charge_datestring

A future date on which the payment should be collected. If not specified, the payment will be collected as soon as possible. If the value is before the mandate's next_possible_charge_date creation will fail. If the value is not a working day it will be rolled forwards to the next available one.

referencestring

An optional reference that will appear on your customer's bank statement. The character limit for this reference is dependent on the scheme.
ACH - 10 characters
Autogiro - 11 characters
Bacs - 10 characters
BECS - 30 characters
BECS NZ - 12 characters
Betalingsservice - 30 characters
Faster Payments - 18 characters
PAD - scheme doesn't offer references
PayTo - 18 characters
SEPA - 140 characters
Note that this reference must be unique (for each merchant) for the BECS scheme as it is a scheme requirement.

Restricted: You can only specify a payment reference for Bacs payments (that is, when collecting from the UK) if you're on the GoCardless Plus, Pro or Enterprise packages.

Restricted: You can not specify a payment reference for Faster Payments.

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.

statusstring

One of:

  • pending_customer_approval: we're waiting for the customer to approve this payment
  • pending_submission: the payment has been created, but not yet submitted to the banks
  • submitted: the payment has been submitted to the banks
  • confirmed: the payment has been confirmed as collected
  • paid_out: the payment has been included in a payout
  • cancelled: the payment has been cancelled
  • customer_approval_denied: the customer has denied approval for the payment. You should contact the customer directly
  • failed: the payment failed to be processed. Note that payments can fail after being confirmed if the failure message is sent late by the banks.
  • charged_back: the payment has been charged back
pending_customer_approvalpending_submissionsubmittedconfirmedpaid_outcancelledcustomer_approval_deniedfailedcharged_back
linksobject
5 properties
mandatestring

ID of the mandate against which this payment should be collected.

creditorstring

ID of creditor to which the collected payment will be sent.

payoutstring

ID of payout which contains the funds from this payment.
Note: this property will not be present until the payment has been successfully collected.

subscriptionstring

ID of subscription from which this payment was created.
Note: this property will only be present if this payment is part of a subscription.

instalment_schedulestring

ID of instalment_schedule from which this payment was created.
Note: this property will only be present if this payment is part of an instalment schedule.

faster_achboolean

This field indicates whether the ACH payment is processed through Faster ACH or standard ACH.

It is only present in the API response for ACH payments.

fxobject
4 properties
exchange_ratestring

Rate used in the foreign exchange of the amount into the fx_currency. Present only after a resource is paid out. Has up to 10 decimal places.

estimated_exchange_ratestring

Estimated rate that will be used in the foreign exchange of the amount into the fx_currency. This will vary based on the prevailing market rate until the moment that it is paid out. Present only before a resource is paid out. Has up to 10 decimal places.

fx_amountobject

Amount that was paid out in the fx_currency after foreign exchange. Present only after the resource has been paid out.

fx_currencystring

ISO 4217 code for the currency in which amounts will be paid out (after foreign exchange). Currently "AUD", "CAD", "DKK", "EUR", "GBP", "NZD", "SEK" and "USD" are supported. Present only if payouts will be (or were) made via foreign exchange.

AUDCADDKKEURGBPNZDSEKUSD
retry_if_possibleboolean

On failure, automatically retry the payment using intelligent retries. Default is false.

Important: To be able to use intelligent retries, Success+ needs to be enabled in GoCardless dashboard.

schemestring

A bank payment scheme. Currently "ach", "autogiro", "bacs", "becs", "becs_nz", "betalingsservice", "faster_payments", "pad", "pay_to", "sepa_core", "sepa_credit_transfer" and "sepa_instant_credit_transfer" are supported.

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
messagestring
request_idstring
typestring
metadataobject
linksobject

Retry a payment#

POST/payments/{payment_id}/actions/retry

Retries a failed payment if the underlying mandate is active. You will receive a resubmission_requested webhook, but after that retrying the payment follows the same process as its initial creation, so you will receive a submitted webhook, followed by a confirmed or failed event. Any metadata supplied to this endpoint will be stored against the payment submission event it causes.

This will return a retry_failed error if the payment has not failed.

Payments can be retried up to 3 times.

Path Parameters

NameTypeDescription
payment_idrequiredstring

The payment id

POST https://api.gocardless.com/payments/PM123/actions/retry HTTP/1.1
Content-Type: application/json
{
  "data": {
    "metadata": {
      "reason": "Customer request"
    }
  }
}
@client.payments.retry("PM123")
client.payments.retry("PM123")
const paymentResponse = await client.payments.retry("PM123");
$client->payments()->retry("PM123");
client.payments().retry("PM123").execute();
paymentRetryParams := gocardless.PaymentRetryParams{}
payment, err := client.Payments.Retry(ctx, "PM123", paymentRetryParams)
var paymentResponse = await client.Payments.RetryAsync("PM0123");
Responsehttp
HTTP/1.1 200 OK
Content-Type: application/json
{
  "payments": {
    "id": "PM123",
    "created_at": "2014-05-08T17:01:06.000Z",
    "charge_date": "2014-05-21",
    "amount": 100,
    "description": null,
    "currency": "GBP",
    "status": "submitted",
    "reference": "WINEBOX001",
    "metadata": {
      "order_dispatch_date": "2014-05-22"
    },
    "amount_refunded": 0,
    "fx": {
      "fx_currency": "EUR",
      "fx_amount": null,
      "exchange_rate": null,
      "estimated_exchange_rate": "1.1234567890"
    },
    "links": {
      "mandate": "MD123",
      "creditor": "CR123"
    },
    "retry_if_possible": false
  }
}
Request Body
paymentsobject
2 properties
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.

charge_datestring

A future date on which the payment should be collected. If not specified, the payment will be collected as soon as possible. If the value is before the mandate's next_possible_charge_date creation will fail. If the value is not a working day it will be rolled forwards to the next available one.

Response 200

Action completed successfully

paymentsobject
15 properties
idstring

Unique identifier, beginning with "PM".

created_atstring

Fixed timestamp, recording when this resource was created.

amountobject

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

Minimum and maximum amounts vary by payment scheme. For more information, see Transaction limits

For Variable Recurring Payments (VRP), this must not exceed the mandate's max_amount_per_payment constraint.

amount_refundedobject

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

currencystring

ISO 4217 currency code. Currently "AUD", "CAD", "DKK", "EUR", "GBP", "NZD", "SEK" and "USD" are supported.

AUDCADDKKEURGBPNZDSEKUSD
descriptionstring

A human-readable description of the payment. This will be included in the notification email GoCardless sends to your customer if your organisation does not send its own notifications (see compliance requirements).

charge_datestring

A future date on which the payment should be collected. If not specified, the payment will be collected as soon as possible. If the value is before the mandate's next_possible_charge_date creation will fail. If the value is not a working day it will be rolled forwards to the next available one.

referencestring

An optional reference that will appear on your customer's bank statement. The character limit for this reference is dependent on the scheme.
ACH - 10 characters
Autogiro - 11 characters
Bacs - 10 characters
BECS - 30 characters
BECS NZ - 12 characters
Betalingsservice - 30 characters
Faster Payments - 18 characters
PAD - scheme doesn't offer references
PayTo - 18 characters
SEPA - 140 characters
Note that this reference must be unique (for each merchant) for the BECS scheme as it is a scheme requirement.

Restricted: You can only specify a payment reference for Bacs payments (that is, when collecting from the UK) if you're on the GoCardless Plus, Pro or Enterprise packages.

Restricted: You can not specify a payment reference for Faster Payments.

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.

statusstring

One of:

  • pending_customer_approval: we're waiting for the customer to approve this payment
  • pending_submission: the payment has been created, but not yet submitted to the banks
  • submitted: the payment has been submitted to the banks
  • confirmed: the payment has been confirmed as collected
  • paid_out: the payment has been included in a payout
  • cancelled: the payment has been cancelled
  • customer_approval_denied: the customer has denied approval for the payment. You should contact the customer directly
  • failed: the payment failed to be processed. Note that payments can fail after being confirmed if the failure message is sent late by the banks.
  • charged_back: the payment has been charged back
pending_customer_approvalpending_submissionsubmittedconfirmedpaid_outcancelledcustomer_approval_deniedfailedcharged_back
linksobject
5 properties
mandatestring

ID of the mandate against which this payment should be collected.

creditorstring

ID of creditor to which the collected payment will be sent.

payoutstring

ID of payout which contains the funds from this payment.
Note: this property will not be present until the payment has been successfully collected.

subscriptionstring

ID of subscription from which this payment was created.
Note: this property will only be present if this payment is part of a subscription.

instalment_schedulestring

ID of instalment_schedule from which this payment was created.
Note: this property will only be present if this payment is part of an instalment schedule.

faster_achboolean

This field indicates whether the ACH payment is processed through Faster ACH or standard ACH.

It is only present in the API response for ACH payments.

fxobject
4 properties
exchange_ratestring

Rate used in the foreign exchange of the amount into the fx_currency. Present only after a resource is paid out. Has up to 10 decimal places.

estimated_exchange_ratestring

Estimated rate that will be used in the foreign exchange of the amount into the fx_currency. This will vary based on the prevailing market rate until the moment that it is paid out. Present only before a resource is paid out. Has up to 10 decimal places.

fx_amountobject

Amount that was paid out in the fx_currency after foreign exchange. Present only after the resource has been paid out.

fx_currencystring

ISO 4217 code for the currency in which amounts will be paid out (after foreign exchange). Currently "AUD", "CAD", "DKK", "EUR", "GBP", "NZD", "SEK" and "USD" are supported. Present only if payouts will be (or were) made via foreign exchange.

AUDCADDKKEURGBPNZDSEKUSD
retry_if_possibleboolean

On failure, automatically retry the payment using intelligent retries. Default is false.

Important: To be able to use intelligent retries, Success+ needs to be enabled in GoCardless dashboard.

schemestring

A bank payment scheme. Currently "ach", "autogiro", "bacs", "becs", "becs_nz", "betalingsservice", "faster_payments", "pad", "pay_to", "sepa_core", "sepa_credit_transfer" and "sepa_instant_credit_transfer" are supported.

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
messagestring
request_idstring
typestring
metadataobject
linksobject
SupportDashboard