Create a payment instrument

A payment instrument is a saved funding source, like a customer's bank account, which can be used to request direct debit payments into your Wise account.

In order to use a payment instrument to request Direct Debit payments, you need to:

  1. Create the payment instrument using POST /v3/profiles/{{profileId}}/payment-instruments
  2. Connect the payments instrument using POST /v3/profiles/{{profileId}}/payment-instruments/{{paymentInstrumentId}}/manual-confirmation.

Create a new payment instrument

To create a new payment instrument, send a request to POST /v3/profiles/{{profileId} /payment-instruments.

In your request, you must provide the type - BACS_DIRECT_DEBIT for UK and SEPA - and bank details for the customer's account. The API returns a PENDING status, indicating it is not yet ready for use.

Sample request:

POST /v3/profiles/{{profileId}}/payment-instruments


{
"type": "BACS_DIRECT_DEBIT",
"branchCode": "00-00-00",
"bankCode": null,
"accountNumber": "12345678"
"reference": "REF01"
}

Sample response:

201
{
"id": "fabfcf6e-3ac3-4d5f-ac96-340b71e6be9e",
"type": "BACS_DIRECT_DEBIT",
"bankName": "HSBC",
"branchCode": "00-00-00",
"bankCode": null,
"accountNumber": "XXXX5678",
"reference": "REF01",
"status": "PENDING",
"disconnectionReason": "OTHER" | null,
"payerDetails": {
"companyName": "ACME Ltd."
"country": "US",
"state": "AZ",
"city": "Phoenix",
"postCode": "10025",
"firstLine": "50 Sunflower Ave"
}
}

Connect the payment instrument

After you complete the mandate setup with your customer, send a request to POST /v3/profiles/{{profileId}}/payment-instruments/{{paymentInstrumentId}}/manual-confirmation.

This action confirms to Wise that you have followed all scheme rules. The payment instrument's status changes to CONNECTED, and you can now use it to initiate payments.

Sample request:

POST /v3/profiles/{{profileId}}/payment-instruments/{{paymentInstrumentId}}/manual-confirmation

Sample response:

201
{
  "id": "fabfcf6e-3ac3-4d5f-ac96-340b71e6be9e",
  "type": "BACS_DIRECT_DEBIT",
  "bankName": "HSBC",
  "branchCode": "00-00-00",
  "bankCode": null,
  "accountNumber": "XXXX5678",
  "reference": "REF01",
  "status": "CONNECTED",
  "disconnectionReason": "OTHER" | null,
  "payerDetails": {
    "companyName": "ACME Ltd."
    "country": "US",
    "state": "AZ",
    "city": "Phoenix",
    "postCode": "10025",
    "firstLine": "50 Sunflower Ave"
  }
}

Track the Payment Instrument

You can retrieve the status of a payment instrument at any time by sending a request to GET /v3/profiles/{{profileId}}/payment-instruments/{{paymentInstrumentId}}. Possible statuses are CONNECTED, DISCONNECTED, or PENDING.

Sample request:

GET /v3/profiles/{{profileId}}/payment-instruments/{{paymentInstrumentId}}

Sample response:

200
{
  "id": "fabfcf6e-3ac3-4d5f-ac96-340b71e6be9e",
  "type": "BACS_DIRECT_DEBIT",
  "bankName": "HSBC",
  "branchCode": "00-00-00",
  "bankCode": null,
  "accountNumber": "12345678",
  "reference": "REF01",
  "status": "DISCONNECTED",
  "disconnectionReason": "OTHER" | null,
  "payerDetails": {
    "companyName": "ACME Ltd."
    "country": "US",
    "state": "AZ",
    "city": "Phoenix",
    "postCode": "10025",
    "firstLine": "50 Sunflower Ave"
  }
}