# 

A Payment Instrument is a saved funding source, like a customer's bank account,
which can be used to request direct debit Payins to fund transfers.

In order to set up a Payment Instrument (to allow submissions for Payins), you need to:

1. Create the Payment Instrument using `POST /v3/profiles/{{profileId}}/payment-instruments`
2. Connect the Payment 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`.
The API returns a `PENDING` status, indicating it is not yet ready for use.

In your request, you must provide:

- **Payment Instrument `type`**
  - `BACS` for the Direct Debit scheme for GBP accounts
  - `SEPA` for the Direct Debit scheme for EUR accounts
- **Bank Account Details**
  - For Bacs the `accountNumber` should be the customers bank account number and the `branchCode` should be their sort code
  - For SEPA only the `accountNumber` field is required as it represents the customers IBAN number
- **Email**
  - For Bacs and SEPA the email used for communication with the Payment Instrument owner must be provided
  - This is the email that is used for sending mandate creation notification and advanced payment notices


In your request, you may optionally provide:

- **Account Holder Name**
  - If not provided, the associated business profile's company name is used when creating the Payment Instrument
- **Reference**
  - This is the reference that is displayed in the debtor's bank statement (alongside the reference provided during Payin creation)
  - If not provided, this is set to a random alphanumeric text field


### BACS Example

Sample request:


```json
{
    "type": "BACS",
    "accountHolderName": "John Smith",
    "accountNumber": "12345678",
    "branchCode": "00-00-00",
    "reference": "REFERENCE01",
    "accountOwnerDetails" : {
        "email": "test@email.com"
    }

}
```

Sample response:


```json
{
    "id": "6713050b-e64f-4da7-0770-5b0583f81739",
    "type": "BACS",
    "bankName": "BARCLAYS BANK PLC",
    "bankCode": null,
    "branchCode": "00-00-00",
    "accountNumber": "XXXX5678",
    "status": "PENDING",
    "accountOwnerDetails": {
        "companyName": "ABC Logistics Ltd",
        "country": "GB",
        "state": null,
        "city": "London",
        "postCode": "EC2A 4JE",
        "firstLine": "65 Clifton St"
    },
    "reference": "REFERENCE01"
}
```

### SEPA Example

Sample request:


```json
{
    "type": "SEPA",
    "accountHolderName": "John Smith",
    "accountNumber": "EE382200221020145685",
    "reference": "REFERENCE01",
    "accountOwnerDetails" : {
        "email": "test@email.com"
    }
}
```

Sample response:


```json
{
    "id": "c1dca180-2939-461b-913c-d9638e6a93ee",
    "type": "SEPA",
    "bankName": "SWEDBANK AS",
    "bankCode": null,
    "branchCode": null,
    "accountNumber": "XXXXXXXXXXXXXXXX5685",
    "status": "PENDING",
    "accountOwnerDetails": {
        "companyName": "ABC Logistics Ltd",
        "country": "EE",
        "state": null,
        "city": "Tallinn",
        "postCode": "10135",
        "firstLine": "Veerenni tn 24"
    },
    "reference": "REFERENCE01"
}
```

## 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`,
indicating you can now use it to initiate Payins.

Sample response:


```json
{
    "id": "6713050b-e64f-4da7-0770-5b0583f81739",
    "type": "BACS",
    "bankName": "BARCLAYS BANK PLC",
    "bankCode": null,
    "branchCode": "00-00-00",
    "accountNumber": "XXXX5678",
    "status": "CONNECTED",
    "accountOwnerDetails": {
        "companyName": "ABC Logistics Ltd",
        "country": "GB",
        "state": null,
        "city": "London",
        "postCode": "EC2A 4JE",
        "firstLine": "65 Clifton St"
    },
    "reference": "REFERENCE01"
}
```

## 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}}`.

We also expose updates to the Payment Instrument via webhooks, see the [Webhooks](/guides/product/send-money/funding/direct-debit/webhooks) section for more details.

## Payment Instrument Status Breakdown 

- **`PENDING`** - The Payment Instrument requires user confirmation before becoming CONNECTED.
- **`CONNECTED`** - The Payment Instrument is authorised and ready to be used for Payin creation.
- **`DISCONNECTED`** - The Payment Instrument is no longer authorised (due to failure or manual disconnection) and cannot be used for Payin creation.


### Handling a Disconnected Payment Instrument 

A Payment Instrument may become disconnected for various reasons
(e.g. customer bank account is not active,
customer cancels their authorisation via their bank,
Payment Instrument cancelled via the API request above).
These cases all lead to the Payment Instrument being marked as `DISCONNECTED` -
it can no longer be used for initiating Payins.

The current API does not expose the `disconnectionReason` however this is being actively worked on.