# Payment Initiation APIs ## Overview Draft Swagger specification for Payment Initiation ### Version information *Version* : v1.0-rc1 ### Contact information *Contact* : Craig Greenhouse *Contact Email* : craig.greenhouse@openbanking.org.uk ### License information *License* : open-licence *License URL* : https://www.openbanking.org.uk/open-licence *Terms of service* : https://www.openbanking.org.uk/terms ### URI scheme *BasePath* : /open-banking *Schemes* : HTTPS ### Tags * Payments : Payments endpoints ### Produces * `application/vnd.api+json` ## Paths *** ### Create a payment submission ``` POST /payment-submissions ``` #### Description Submit a previously setup payment #### Body parameter Setup a single immediate payment *Name* : body *Flags* : required |Name|Schema| |---|---| |**Data**
*required*|[Payment Submission](#payment-submission)| **Payment Submission** |Name|Description|Schema| |---|---|---| |**Initiation**
*required*|The Initiation payload is sent by the initiating party to the ASPSP. It is used to request movement of funds from the debtor account to a creditor.|[Initiation](#payment-submissions-post-initiation)| |**PaymentId**
*required*|OB: Unique identification as assigned by the ASPSP to uniquely identify the payment setup resource.
**Length** : `1 - 40`|string| **Initiation** |Name|Description|Schema| |---|---|---| |**CreditorAccount**
*required*|Unambiguous identification of the account of the creditor to which a credit entry will be posted as a result of the payment transaction.|[Creditor Account](#creditor-account)| |**CreditorAgent**
*required*|Financial institution servicing an account for the creditor.|[Creditor Agent](#creditor-agent)| |**DebtorAccount**
*optional*|Unambiguous identification of the account of the debtor to which a debit entry will be made as a result of the transaction.|[Debtor Account](#debtor-account)| |**DebtorAgent**
*optional*|Financial institution servicing an account for the debtor.|[DebtorAgent](#debtoragent)| |**EndToEndIdentification**
*required*|Unique identification assigned by the initiating party to unambiguously identify the transaction. This identification is passed on, unchanged, throughout the entire end-to-end chain. Usage: The end-to-end identification can be used for reconciliation or to link tasks relating to the transaction. It can be included in several messages related to the transaction. OB: The Faster Payments Scheme can only access 31 characters for the EndToEndIdentification field.
**Length** : `1 - 35`|string| |**InstructedAmount**
*required*|Amount of money to be moved between the debtor and creditor, before deduction of charges, expressed in the currency as ordered by the initiating party. Usage: This amount has to be transported unchanged through the transaction chain.|[InstructedAmount](#payment-submissions-post-initiation-instructedamount)| |**InstructionIdentification**
*required*|Unique identification as assigned by an instructing party for an instructed party to unambiguously identify the instruction. Usage: the instruction identification is a point to point reference that can be used between the instructing party and the instructed party to refer to the individual instruction. It can be included in several messages related to the instruction.
**Length** : `1 - 35`|string| |**RemittanceInformation**
*optional*|Information supplied to enable the matching of an entry with the items that the transfer is intended to settle, such as commercial invoices in an accounts' receivable system.|[Remittance Information](#remittance-information)| **Creditor Account** |Name|Description|Schema| |---|---|---| |**Identification**
*required*|Identification assigned by an institution to identify an account. This identification is known by the account owner.
**Length** : `1 - 34`|string| |**Name**
*required*|Name of the account, as assigned by the account servicing institution, in agreement with the account owner in order to provide an additional means of identification of the account. Usage: The account name is different from the account owner name. The account name is used in certain user communities to provide a means of identifying the account, in addition to the account owner's identity and the account number.
**Length** : `1 - 70`|string| |**SchemeName**
*required*|Name of the identification scheme, in a coded form as published in an external list.|enum (BBAN, IBAN)| |**SecondaryIdentification**
*optional*|Identification assigned by an institution to identify an account. This identification is known by the account owner.
**Length** : `1 - 34`|string| **Creditor Agent** |Name|Description|Schema| |---|---|---| |**Identification**
*required*|Unique and unambiguous identification of a person.
**Length** : `1 - 35`|string| |**SchemeName**
*required*|Name of the identification scheme, in a coded form as published in an external list.|enum (BICFI, UKSortCode)| **Debtor Account** |Name|Description|Schema| |---|---|---| |**Identification**
*required*|Identification assigned by an institution to identify an account. This identification is known by the account owner.
**Length** : `1 - 34`|string| |**Name**
*optional*|Name of the account, as assigned by the account servicing institution, in agreement with the account owner in order to provide an additional means of identification of the account. Usage: The account name is different from the account owner name. The account name is used in certain user communities to provide a means of identifying the account, in addition to the account owner's identity and the account number.
**Length** : `1 - 70`|string| |**SchemeName**
*required*|Name of the identification scheme, in a coded form as published in an external list.|enum (BBAN, IBAN)| |**SecondaryIdentification**
*optional*|Identification assigned by an institution to identify an account. This identification is known by the account owner.
**Length** : `1 - 34`|string| **DebtorAgent** |Name|Description|Schema| |---|---|---| |**Identification**
*required*|Unique and unambiguous identification of a person.
**Length** : `1 - 35`|string| |**SchemeName**
*required*|Name of the identification scheme, in a coded form as published in an external list.|enum (BICFI, UKSortCode)| **InstructedAmount** |Name|Description|Schema| |---|---|---| |**Amount**
*required*|**Pattern** : `"^-?\\d{1,13}\\.\\d{1,5}$"`|string| |**Currency**
*required*|A code allocated to a currency by a Maintenance Agency under an international identification scheme, as described in the latest edition of the international standard ISO 4217 - Codes for the representation of currencies and funds.
**Pattern** : `"[A-Z]{3}"`|string| **Remittance Information** |Name|Description|Schema| |---|---|---| |**Reference**
*optional*|Unique and unambiguous identification of a person.
**Length** : `1 - 35`|string| |**Unstructured**
*optional*|Name of the identification scheme, in a coded form as published in an external list.
**Length** : `1 - 140`|string| #### Responses |HTTP Code|Description|Schema| |---|---|---| |**201**|Payment submit resource successfully created|[Payment Submit POST 201 Response](#payment-submit-post-201-response)| |**400**|Bad Request|No Content| |**401**|Unauthorized|No Content| |**403**|Forbidden|No Content| |**409**|Conflict|No Content| |**500**|Internal Server Error|No Content| **Payment Submit POST 201 Response** |Name|Description|Schema| |---|---|---| |**CreationDateTime**
*required*|Date and time at which the resource was created.|string (date-time)| |**Links**
*required*|Link URIs relevant to the payload|[Links](#payment-submissions-post-links)| |**Meta**
*required*|Meta Data Relevant to the payload|[Meta](#payment-submissions-post-meta)| |**PaymentId**
*required*|OB: Unique identification as assigned by the ASPSP to uniquely identify the payment setup resource.
**Length** : `1 - 40`|string| |**PaymentSubmissionId**
*required*|OB: Unique identification as assigned by the ASPSP to uniquely identify the payment submission resource.
**Length** : `1 - 40`|string| |**Status**
*optional*|Specifies the status of the payment submission resource.|enum (AcceptedSettlementCompleted, AcceptedSettlementInProcess, Pending, Rejected)| **Links** |Name|Schema| |---|---| |**first**
*optional*|string (uri)| |**last**
*optional*|string (uri)| |**next**
*optional*|string (uri)| |**prev**
*optional*|string (uri)| |**self**
*required*|string (uri)| **Meta** |Name|Schema| |---|---| |**total-pages**
*optional*|integer (int32)| #### Consumes * `application/vnd.api+json` #### Produces * `application/vnd.api+json` #### Tags * Payments #### Security |Type|Name|Scopes| |---|---|---| |**oauth2**|**[PSUOAuth2Security](#psuoauth2security)**|payment| *** ### Create a single immediate payment ``` POST /payments ``` #### Description Create a single immediate payment #### Parameters |Type|Name|Description|Schema| |---|---|---|---| |**Header**|**x-idempotency-key**
*required*|Every request will be processed only once per x-idempotency-key|string| #### Body parameter Setup a single immediate payment *Name* : body *Flags* : required |Name|Schema| |---|---| |**Data**
*required*|[Payment Setup](#payment-setup)| |**Risk**
*required*|[Risk](#risk)| **Payment Setup** |Name|Schema| |---|---| |**Initiation**
*required*|[Initiation](#payments-post-initiation)| **Initiation** |Name|Description|Schema| |---|---|---| |**CreditorAccount**
*required*|Unambiguous identification of the account of the creditor to which a credit entry will be posted as a result of the payment transaction.|[Creditor Account](#creditor-account)| |**CreditorAgent**
*required*|Financial institution servicing an account for the creditor.|[Creditor Agent](#creditor-agent)| |**DebtorAccount**
*optional*|Unambiguous identification of the account of the debtor to which a debit entry will be made as a result of the transaction.|[Debtor Account](#debtor-account)| |**DebtorAgent**
*optional*|Financial institution servicing an account for the debtor.|[DebtorAgent](#debtoragent)| |**EndToEndIdentification**
*required*|Unique identification assigned by the initiating party to unambiguously identify the transaction. This identification is passed on, unchanged, throughout the entire end-to-end chain. Usage: The end-to-end identification can be used for reconciliation or to link tasks relating to the transaction. It can be included in several messages related to the transaction. OB: The Faster Payments Scheme can only access 31 characters for the EndToEndIdentification field.
**Length** : `1 - 35`|string| |**InstructedAmount**
*required*|Amount of money to be moved between the debtor and creditor, before deduction of charges, expressed in the currency as ordered by the initiating party. Usage: This amount has to be transported unchanged through the transaction chain.|[InstructedAmount](#payments-post-initiation-instructedamount)| |**InstructionIdentification**
*required*|Unique identification as assigned by an instructing party for an instructed party to unambiguously identify the instruction. Usage: the instruction identification is a point to point reference that can be used between the instructing party and the instructed party to refer to the individual instruction. It can be included in several messages related to the instruction.
**Length** : `1 - 35`|string| |**RemittanceInformation**
*optional*|Information supplied to enable the matching of an entry with the items that the transfer is intended to settle, such as commercial invoices in an accounts' receivable system.|[Remittance Information](#remittance-information)| **Creditor Account** |Name|Description|Schema| |---|---|---| |**Identification**
*required*|Identification assigned by an institution to identify an account. This identification is known by the account owner.
**Length** : `1 - 34`|string| |**Name**
*required*|Name of the account, as assigned by the account servicing institution, in agreement with the account owner in order to provide an additional means of identification of the account. Usage: The account name is different from the account owner name. The account name is used in certain user communities to provide a means of identifying the account, in addition to the account owner's identity and the account number.
**Length** : `1 - 70`|string| |**SchemeName**
*required*|Name of the identification scheme, in a coded form as published in an external list.|enum (BBAN, IBAN)| |**SecondaryIdentification**
*optional*|Identification assigned by an institution to identify an account. This identification is known by the account owner.
**Length** : `1 - 34`|string| **Creditor Agent** |Name|Description|Schema| |---|---|---| |**Identification**
*required*|Unique and unambiguous identification of a person.
**Length** : `1 - 35`|string| |**SchemeName**
*required*|Name of the identification scheme, in a coded form as published in an external list.|enum (BICFI, UKSortCode)| **Debtor Account** |Name|Description|Schema| |---|---|---| |**Identification**
*required*|Identification assigned by an institution to identify an account. This identification is known by the account owner.
**Length** : `1 - 34`|string| |**Name**
*optional*|Name of the account, as assigned by the account servicing institution, in agreement with the account owner in order to provide an additional means of identification of the account. Usage: The account name is different from the account owner name. The account name is used in certain user communities to provide a means of identifying the account, in addition to the account owner's identity and the account number.
**Length** : `1 - 70`|string| |**SchemeName**
*required*|Name of the identification scheme, in a coded form as published in an external list.|enum (BBAN, IBAN)| |**SecondaryIdentification**
*optional*|Identification assigned by an institution to identify an account. This identification is known by the account owner.
**Length** : `1 - 34`|string| **DebtorAgent** |Name|Description|Schema| |---|---|---| |**Identification**
*required*|Unique and unambiguous identification of a person.
**Length** : `1 - 35`|string| |**SchemeName**
*required*|Name of the identification scheme, in a coded form as published in an external list.|enum (BICFI, UKSortCode)| **InstructedAmount** |Name|Description|Schema| |---|---|---| |**Amount**
*required*|**Pattern** : `"^-?\\d{1,13}\\.\\d{1,5}$"`|string| |**Currency**
*required*|A code allocated to a currency by a Maintenance Agency under an international identification scheme, as described in the latest edition of the international standard ISO 4217 - Codes for the representation of currencies and funds.
**Pattern** : `"[A-Z]{3}"`|string| **Remittance Information** |Name|Description|Schema| |---|---|---| |**Reference**
*optional*|Unique and unambiguous identification of a person.
**Length** : `1 - 35`|string| |**Unstructured**
*optional*|Name of the identification scheme, in a coded form as published in an external list.
**Length** : `1 - 140`|string| **Risk** |Name|Description|Schema| |---|---|---| |**DeliveryAddress**
*optional*|Information that locates and identifies a specific address, as defined by postal services or in free format text.|[DeliveryAddress](#payments-post-deliveryaddress)| |**MerchantCategoryCode**
*optional*|Category code conform to ISO 18245, related to the type of services or goods the merchant provides for the transaction
**Length** : `3 - 4`|string| |**MerchantCustomerIdentification**
*optional*|The unique customer identifier of the PSU with the merchant.
**Length** : `1 - 70`|string| |**PaymentContextCode**
*optional*|Specifies the payment context|enum (BillPayment, EcommerceGoods, EcommerceServices, Other, PersonToPerson)| **DeliveryAddress** |Name|Description|Schema| |---|---|---| |**AddressLine**
*optional*|Information that locates and identifies a specific address, as defined by postal services, that is presented in free format text.|< string > array| |**BuildingNumber**
*optional*|Number that identifies the position of a building on a street.
**Length** : `1 - 16`|string| |**Country**
*required*|Nation with its own government, occupying a particular territory.
**Pattern** : `"[A-Z]{2}"`|string| |**CountrySubDivision**
*optional*|Identifies a subdivision of a country, for instance state, region, county.|< string > array| |**PostCode**
*optional*|Identifier consisting of a group of letters and/or numbers that is added to a postal address to assist the sorting of mail
**Length** : `1 - 16`|string| |**StreetName**
*optional*|Name of a street or thoroughfare
**Length** : `1 - 70`|string| |**TownName**
*required*|Name of a built-up area, with defined boundaries, and a local government.
**Length** : `1 - 35`|string| #### Responses |HTTP Code|Description|Schema| |---|---|---| |**201**|Payment setup resource successfully created|[Payment setup POST response](#payment-setup-post-response)| |**400**|Bad Request|No Content| |**401**|Unauthorized|No Content| |**403**|Forbidden|No Content| |**409**|Conflict|No Content| |**500**|Internal Server Error|No Content| **Payment setup POST response** |Name|Description|Schema| |---|---|---| |**Data**
*required*|Reflection of The Main Data Payload, with Created Resource ID, Status and Timestamp|[Payment Setup Response](#payment-setup-response)| |**Links**
*required*|Link URIs relevant to the payload|[Links](#payments-post-links)| |**Meta**
*required*|Meta Data Relevant to the payload|[Meta](#payments-post-meta)| |**Risk**
*required*|Reflection of POSTed Risk profile|[Risk](#risk)| **Payment Setup Response** |Name|Description|Schema| |---|---|---| |**CreationDateTime**
*required*|Date and time at which the resource was created.|string (date-time)| |**Initiation**
*required*|The Initiation payload is sent by the initiating party to the ASPSP. It is used to request movement of funds from the debtor account to a creditor.|[Initiation](#payment-setup-response-initiation)| |**PaymentId**
*required*|OB: Unique identification as assigned by the ASPSP to uniquely identify the payment setup resource.
**Length** : `1 - 40`|string| |**Status**
*optional*|Specifies the status of the payment resource.|enum (AcceptedCustomerProfile, AcceptedTechnicalValidation, Pending, Rejected)| **Initiation** |Name|Description|Schema| |---|---|---| |**CreditorAccount**
*required*|Unambiguous identification of the account of the creditor to which a credit entry will be posted as a result of the payment transaction.|[Creditor Account](#creditor-account)| |**CreditorAgent**
*required*|Financial institution servicing an account for the creditor.|[Creditor Agent](#creditor-agent)| |**DebtorAccount**
*optional*|Unambiguous identification of the account of the debtor to which a debit entry will be made as a result of the transaction.|[Debtor Account](#debtor-account)| |**DebtorAgent**
*optional*|Financial institution servicing an account for the debtor.|[DebtorAgent](#debtoragent)| |**EndToEndIdentification**
*required*|Unique identification assigned by the initiating party to unambiguously identify the transaction. This identification is passed on, unchanged, throughout the entire end-to-end chain. Usage: The end-to-end identification can be used for reconciliation or to link tasks relating to the transaction. It can be included in several messages related to the transaction. OB: The Faster Payments Scheme can only access 31 characters for the EndToEndIdentification field.
**Length** : `1 - 35`|string| |**InstructedAmount**
*required*|Amount of money to be moved between the debtor and creditor, before deduction of charges, expressed in the currency as ordered by the initiating party. Usage: This amount has to be transported unchanged through the transaction chain.|[InstructedAmount](#payment-setup-response-initiation-instructedamount)| |**InstructionIdentification**
*required*|Unique identification as assigned by an instructing party for an instructed party to unambiguously identify the instruction. Usage: the instruction identification is a point to point reference that can be used between the instructing party and the instructed party to refer to the individual instruction. It can be included in several messages related to the instruction.
**Length** : `1 - 35`|string| |**RemittanceInformation**
*optional*|Information supplied to enable the matching of an entry with the items that the transfer is intended to settle, such as commercial invoices in an accounts' receivable system.|[Remittance Information](#remittance-information)| **Creditor Account** |Name|Description|Schema| |---|---|---| |**Identification**
*required*|Identification assigned by an institution to identify an account. This identification is known by the account owner.
**Length** : `1 - 34`|string| |**Name**
*required*|Name of the account, as assigned by the account servicing institution, in agreement with the account owner in order to provide an additional means of identification of the account. Usage: The account name is different from the account owner name. The account name is used in certain user communities to provide a means of identifying the account, in addition to the account owner's identity and the account number.
**Length** : `1 - 70`|string| |**SchemeName**
*required*|Name of the identification scheme, in a coded form as published in an external list.|enum (BBAN, IBAN)| |**SecondaryIdentification**
*optional*|Identification assigned by an institution to identify an account. This identification is known by the account owner.
**Length** : `1 - 34`|string| **Creditor Agent** |Name|Description|Schema| |---|---|---| |**Identification**
*required*|Unique and unambiguous identification of a person.
**Length** : `1 - 35`|string| |**SchemeName**
*required*|Name of the identification scheme, in a coded form as published in an external list.|enum (BICFI, UKSortCode)| **Debtor Account** |Name|Description|Schema| |---|---|---| |**Identification**
*required*|Identification assigned by an institution to identify an account. This identification is known by the account owner.
**Length** : `1 - 34`|string| |**Name**
*optional*|Name of the account, as assigned by the account servicing institution, in agreement with the account owner in order to provide an additional means of identification of the account. Usage: The account name is different from the account owner name. The account name is used in certain user communities to provide a means of identifying the account, in addition to the account owner's identity and the account number.
**Length** : `1 - 70`|string| |**SchemeName**
*required*|Name of the identification scheme, in a coded form as published in an external list.|enum (BBAN, IBAN)| |**SecondaryIdentification**
*optional*|Identification assigned by an institution to identify an account. This identification is known by the account owner.
**Length** : `1 - 34`|string| **DebtorAgent** |Name|Description|Schema| |---|---|---| |**Identification**
*required*|Unique and unambiguous identification of a person.
**Length** : `1 - 35`|string| |**SchemeName**
*required*|Name of the identification scheme, in a coded form as published in an external list.|enum (BICFI, UKSortCode)| **InstructedAmount** |Name|Description|Schema| |---|---|---| |**Amount**
*required*|**Pattern** : `"^-?\\d{1,13}\\.\\d{1,5}$"`|string| |**Currency**
*required*|A code allocated to a currency by a Maintenance Agency under an international identification scheme, as described in the latest edition of the international standard ISO 4217 - Codes for the representation of currencies and funds.
**Pattern** : `"[A-Z]{3}"`|string| **Remittance Information** |Name|Description|Schema| |---|---|---| |**Reference**
*optional*|Unique and unambiguous identification of a person.
**Length** : `1 - 35`|string| |**Unstructured**
*optional*|Name of the identification scheme, in a coded form as published in an external list.
**Length** : `1 - 140`|string| **Links** |Name|Schema| |---|---| |**first**
*optional*|string (uri)| |**last**
*optional*|string (uri)| |**next**
*optional*|string (uri)| |**prev**
*optional*|string (uri)| |**self**
*required*|string (uri)| **Meta** |Name|Schema| |---|---| |**total-pages**
*optional*|integer (int32)| **Risk** |Name|Description|Schema| |---|---|---| |**DeliveryAddress**
*optional*|Information that locates and identifies a specific address, as defined by postal services or in free format text.|[DeliveryAddress](#risk-deliveryaddress)| |**MerchantCategoryCode**
*optional*|Category code conform to ISO 18245, related to the type of services or goods the merchant provides for the transaction
**Length** : `3 - 4`|string| |**MerchantCustomerIdentification**
*optional*|The unique customer identifier of the PSU with the merchant.
**Length** : `1 - 70`|string| |**PaymentContextCode**
*optional*|Specifies the payment context|enum (BillPayment, EcommerceGoods, EcommerceServices, Other, PersonToPerson)| **DeliveryAddress** |Name|Description|Schema| |---|---|---| |**AddressLine**
*optional*|Information that locates and identifies a specific address, as defined by postal services, that is presented in free format text.|< string > array| |**BuildingNumber**
*optional*|Number that identifies the position of a building on a street.
**Length** : `1 - 16`|string| |**Country**
*required*|Nation with its own government, occupying a particular territory.
**Pattern** : `"[A-Z]{2}"`|string| |**CountrySubDivision**
*optional*|Identifies a subdivision of a country, for instance state, region, county.|< string > array| |**PostCode**
*optional*|Identifier consisting of a group of letters and/or numbers that is added to a postal address to assist the sorting of mail
**Length** : `1 - 16`|string| |**StreetName**
*optional*|Name of a street or thoroughfare
**Length** : `1 - 70`|string| |**TownName**
*required*|Name of a built-up area, with defined boundaries, and a local government.
**Length** : `1 - 35`|string| #### Consumes * `application/vnd.api+json` #### Produces * `application/vnd.api+json` #### Tags * Payments #### Security |Type|Name|Scopes| |---|---|---| |**oauth2**|**[TPPOAuth2Security](#tppoauth2security)**|tpp_client_credential| ## Security ### TPPOAuth2Security TPP client credential authorisation flow with the ASPSP *Type* : oauth2 *Flow* : application *Token URL* : /token |Name|Description| |---|---| |tpp_client_credential|TPP Client Credential Scope| ### PSUOAuth2Security OAuth flow, it is required when the PSU needs to perform SCA with the ASPSP when a TPP wants to access an ASPSP resource owned by the PSU *Type* : oauth2 *Flow* : accessCode *Token URL* : /authorization *Token URL* : /token |Name|Description| |---|---| |payment|Generic payment scope|