Create payment consent

POST /payment_initiation/consent/create

The /payment_initiation/consent/create endpoint is used to create a payment consent, which can be used to initiate payments on behalf of the user. Payment consents are created with UNAUTHORISED status by default and must be authorised by the user before payments can be initiated.

Consents can be limited in time and scope, and have constraints that describe limitations for payments.

Request Body

Required

PaymentInitiationConsentCreateRequest defines the request schema for /payment_initiation/consent/create

Parameters

client_id
string
Your Plaid API client_id. The client_id is required and may be provided either in the PLAID-CLIENT-ID header or as part of a request body.
secret
string
Your Plaid API secret. The secret is required and may be provided either in the PLAID-SECRET header or as part of a request body.
recipient_id
required, string
The ID of the recipient the payment consent is for. The created consent can be used to transfer funds to this recipient only.
reference
required, string
A reference for the payment consent. This must be an alphanumeric string with at most 18 characters and must not contain any special characters.
scopes
array[string]
An array of payment consent scopes.
type
string
Payment consent type. Defines possible use case for payments made with the given consent. SWEEPING: Allows moving money between accounts owned by the same user. COMMERCIAL: Allows initiating payments from the user’s account to third parties.
constraints
required, object
Limitations that will be applied to payments initiated using the payment consent.
valid_date_time
object
Life span for the payment consent. After the to date the payment consent expires and can no longer be used for payment initiation.
from
string
The date and time from which the consent should be active, in ISO 8601 format.
to
string
The date and time at which the consent expires, in ISO 8601 format.
max_payment_amount
required, object
Maximum amount of a single payment initiated using the payment consent.
periodic_amounts
required, array[object]
A list of amount limitations per period of time.
amount
required, object
Maximum cumulative amount for all payments in the specified interval.
interval
required, string
Payment consent periodic interval.
alignment
required, string
Where the payment consent period should start. If the institution is Monzo, only CONSENT alignments are supported. CALENDAR: line up with a calendar. CONSENT: on the date of consent creation.
options
object
(Deprecated) Additional payment consent options. Please use payer_details to specify the account.
request_refund_details
boolean
When true, Plaid will attempt to request refund details from the payee’s financial institution. Support varies between financial institutions and will not always be available. If refund details could be retrieved, they will be available in the /payment_initiation/payment/get response.
iban
string
The International Bank Account Number (IBAN) for the payer’s account. Where possible, the end user will be able to set up payment consent using only the specified bank account if provided.
bacs
object
An optional object used to restrict the accounts used for payments. If provided, the end user will be able to send payments only from the specified bank account.
payer_details
object
An object representing the payment consent payer details. Payer name and account numbers are required to lock the account to which the consent can be created.
name
required, string
The name of the payer as it appears in their bank account
numbers
required, object
The counterparty’s bank account numbers. Exactly one of IBAN or BACS data is required.
bacs
object
An optional object used to restrict the accounts used for payments. If provided, the end user will be able to send payments only from the specified bank account.
iban
string
International Bank Account Number (IBAN).
address
object
The optional address of the payment recipient’s bank account. Required by most institutions outside of the UK.
street
required, array[string]
An array of length 1-2 representing the street address where the recipient is located. Maximum of 70 characters.
city
required, string
The city where the recipient is located. Maximum of 35 characters.
postal_code
required, string
The postal code where the recipient is located. Maximum of 16 characters.
country
required, string
The ISO 3166-1 alpha-2 country code where the recipient is located.
date_of_birth
string
The payer’s birthdate, in ISO 8601 (YYYY-MM-DD) format.
phone_numbers
array[string]
The payer’s phone numbers in E.164 format: +{countrycode}{number}
emails
array[string]
The payer’s emails

Response

PaymentInitiationConsentCreateResponse defines the response schema for /payment_initiation/consent/create

Response Properties

consent_id
required, string
A unique ID identifying the payment consent.
status
required, string
The status of the payment consent. UNAUTHORISED: Consent created, but requires user authorisation. REJECTED: Consent authorisation was rejected by the user and/or the bank. AUTHORISED: Consent is active and ready to be used. REVOKED: Consent has been revoked and can no longer be used. EXPIRED: Consent is no longer valid.
request_id
required, string
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.