# Initiate Single Immediate Domestic VRP Payment source: https://developer.mastercard.com/open-banking-connect/documentation/pisfeatures/initiate-single-immediate-domestic-vrp-payment-request/index.md ## Request overview {#request-overview} The goal of this request is to create initiate a VRP payment. ### Endpoint details {#endpoint-details} | **Endpoints/Resources** | **Method** | **API Profiles** | **Description** | |-------------------------|------------|-------------------------------------------------|----------------------------------------------------------------------------------------------------------------------| | /payments/domestic-vrps | `POST` | CMA9 (restricted to specific ASPSPs and TPPs\*) | Initiate a Domestic Variable Recurring payment using a long-lived consent that was previously authorized by the PSU. | \*UK only. Available on subscription. The following sequence diagram shows the flows for an Initiate Single Immediate Domestic VRP Payment request. Diagram vrp_single_immediate_payment ## Request scenario {#request-scenario} API Reference: `POST /payments/domestic-vrps` #### Request header {#request-header} | **Name** | **Purpose** | **Required by** | **How it can be used** | **Condition** | **Multiplicity** | **Type** | **Description** | |------------------------|---------------------------------------|-----------------|----------------------------------------------------------------------|---------------|------------------|----------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `X-Mc-Idempotency-Key` | Is used to enable request idempotency | ASPSP | Should be used to ensure that requests are not rejected as duplicate | O | 0..1 | String | Required to enable idempotency for the request. If not provided, unique value will be generated and sent to the bank. Example: c0ba8bf3-ef1a-419f-87a3-28a1b2e6da96 | #### Request body {#request-body} | **Name** | **Purpose** | **Required by** | **How it can be used** | **Condition** | **Multiplicity** | **Type** | **Description** | **Limitations/Parameters** | |----------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------------|------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------| | `requestInfo` | Includes information about request being processed | MC | This element encapsulates all request information sent to the API Service | M | 1..1 | Object | Set of elements used to define the request details | - | | `xRequestId` | ID of the request, unique to the call, as determined by the TPP | TPP | A memorable ID could be used to support in a dispute | M | 1..1 | UUID | Free field that allows for the addition of information that can be referenced for future use | 36 | | `aspspId` | ID of a financial institution servicing the Accounts of the PSU | ASPSP | Identification of ASPSP. | M | 1..1 | String | This element is used to specify the identification code of a financial institution which holds PSU accounts | 36 | | `isLivePsuRequest` | Indicates if PSU actively initiated request | ASPSP | Type of PSU request | O | 0..1 | Boolean | PSU request type | Boolean:true, false | | `psuIPAddress` | The forwarded IP address field consists of the corresponding HTTP request IP address field between PSU and TPP. | ASPSP | It shall be contained only if the PSU actively initiated this request | C | 0..1 | String | IP address of PSU's terminal device Required when isLivePsuRequest=true. | 1-256 Required when isLivePsuRequest=true | | `psuAgent` | Indicates the user-agent for the PSU. If the PSU is using the TPP's mobile app, make sure the mobile app user-agent string is different than browser-based user-agent strings. | ASPSP | If user-agent is supplied to ASPSP, then this information can be used by ASPSP's security mechanisms. To avoid rejections, it is recommended to include this field when providing isLivePsuRequest and psuIPAddress. | O | 0..1 | String | PSU's browser agent details | 1-256 | | `merchant` | Collect merchant data for reporting purposes | MC | Merchant data used for reporting or reconciliation purposes | O | 0..1 | Object | Set of elements used to define the merchant details | N/A | | `id` | Merchant identification code to identify the merchant | MC | Unique Merchant identifier per TPP, which could be used for reporting/reconciliation purposes | M | 1..1 | String | Unique Merchant identifier per TPP | 1-256 | | `name` | Merchant name to identify the merchant | MC | Name of merchant | M | 1..1 | String | Merchant name | 1-256 | | `consentId` | A unique reference to the account information consent stored by the ASPSP. | ASPSP | Pass this value as part of the variable recurrent payment initiation request | M | 1..1 | String | The authorization query / data received after PSU has authorized the consent | 1-256 | | `payment` | The object contains the list of fields used to send a payment instruction to financial institution | MC | This element encapsulates all payment details | M | 1..1 | Object | Set of elements used to define VRP payment details | N/A | | `creditorAccount` | Unambiguous identification of the account of the creditor to which a credit entry will be posted as a result of the payment transaction. | ASPSP | Specify account in a financial institution servicing the creditor | M | 1..1 | Object | Set of elements used to define the creditor account details | N/A | | `schemeName` | Name of the identification scheme, in a coded form as published in an external list. | ASPSP | This field is used to identify the type of Identification used to identify an account. | M | 1..1 | String Enum: \['UK.AccountNumber'\] | Account scheme name | 1-50 | | `identification` | Identification assigned by an institution to identify an account. This identification is known by the account owner. | ASPSP | This element is used to specify the account identification number | M | 1..1 | String | Account identification which can be used on payload-level to address specific accounts | 1-256 | | `creditorName` | Name by which a party is known, and which is usually used to identify that party | ASPSP | This element is used to specify creditor name | O | 0..1 | String | Name of the Beneficiary/Creditor | 1-70 | | `creditorAgent` | Unambiguous identification of the financial institution of the creditor to which a credit entry will be posted as a result of the payment transaction | ASPSP | Specify financial institution servicing an account for the creditor | M | 1..1 | Object | Set of elements used to define the creditor agent details | N/A | | `clearingSystemIdentification` | Name of the identification scheme, in a coded form as published in an external list | ASPSP | This field is used to identify the type of identification used to identify an agent | M | 1..1 | Enum: \['UK.SortCode'\] | Clearing system identification scheme | 1-50 | | `memberIdentification` | Code allocated to a financial institution by the ISO 9362 Registration Authority to identify the financial institution | ASPSP | This element is used to specify the financial institution identification code | M | 0..1 | String | Identification code to identify the financial institution | 1-256 | | `debtorAccount` | Unambiguous identification of the account of the debtor to which a debit entry will be made as a result of the transaction | ASPSP | Specify account in a financial institution servicing the debtor | O | 0..1 | Object | Set of elements used to define the debtor account details | N/A | | `identification` | Identification assigned by an institution to identify an account. This identification is known by the account owner | ASPSP | This element is used to specify the account identification number | M | 1..1 | String | Account identification which can be used on payload-level to address specific accounts | 1-256 | | `schemeName` | Name of the scheme, used to specify the account identification type. | MC | This field is used to specify the account identification type | M | 1..1 | String | Account scheme name | 1-50 | | `debtorName` | Name by which a party is known, and which is usually used to identify that party | ASPSP | This element is used to specify debtor name | O | 0..1 | String | Name by which a party is known, and which is usually used to identify that party | 1-256 | | `debtorAgent` | Unambiguous identification of the financial institution of the debtor to which a debit entry will be made as a result of the transaction | ASPSP | Specify financial institution servicing an account for the debtor | O | 0..1 | Object | Set of elements used to define the debtor agent details | N/A | | `clearingSystemIdentification` | Code allocated to a financial institution by the ISO 9362 Registration Authority to identify the financial institution | ASPSP | This element is used to specify the financial institution identification code | M | 1..1 | Enum: `['UK.SortCode']` | Clearing system identification scheme | 1-256 | | `memberIdentification` | Code allocated to a financial institution by the ISO 9362 Registration Authority to identify the financial institution | ASPSP | This element is used to specify the financial institution identification code | M | | String | Identification code to identify the financial institution | 1-256 | | `instructedAmount` | Amount of money to be moved between the debtor and creditor, before deduction of charges, expressed in the currency as ordered by the TPP | ASPSP | This amount has to be transported unchanged through the transaction chain | M | 1..1 | Object | Structure aiming to embed amount and currency of current VRP payment | N/A | | `currency` | 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" | ASPSP | The currency of the amount used in transaction | M | 1..1 | String Enum \["GBP"\] | Specifies the currency of the included amount | | | `amount` | A number of monetary units specified in an active currency where the unit of currency is explicit and compliant with ISO 4217. | ASPSP | This element is used to specify the amount of money to be processed | M | 1..1 | Decimal | Amount of money that needs to be moved between the debtor and creditor accounts | Min:0 | | `instructionIdentification` | Unique identification as assigned by an instructing party for an instructed party to unambiguously identify the instruction. | ASPSP | 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. | M | 1..1 | String | Unique identification shared between the TPP and the ASPSP | 1-256 | | `localInstrument` | User community specific instrument | ASPSP | This element is used to specify a local instrument, local clearing option and/or further qualify the service or service level. | O | 0..1 | String Enum:`['UK.FasterPayments']` | User community specific instrument specifies which clearing system should be used to process the payment instruction | 1-50 | | `endToEndIdentification` | Unique identification assigned by the TPP to unambiguously identify the transaction. This identification is passed on, unchanged, throughout the entire end-to-end chain. | ASPSP | 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. | M | 1..1 | String | Field is available for TPPs to enable end-to-end identification of the transaction | 1-18 | | `remittanceInformationReference` | Reference information provided by the creditor to allow the identification of the underlying documents | ASPSP | If available, the TPP should provide this reference in the structured remittance information, to enable reconciliation by the creditor upon receipt of the amount of money. | O | 0..1 | String | Unique reference, as assigned by the creditor, to unambiguously refer to the payment transaction. | 1-256 | | `risk` | The object contains the list of fields used to send risk information to financial institution. | ASPSP | It is used to specify additional details for risk scoring for Payments. | O | 0..1 | Object | The Risk object is sent by the initiating party to the ASPSP. It is used to specify additional details for risk scoring for Payments. | | | `paymentContextCode` | Information that specify payment context for a payment. | ASPSP | Specifies the payment context. | O | 0..1 | Enum: BILL_PAYMENT, ECOMMERCE_GOODS, ECOMMERCE_SERVICES, OTHER, PERSON_TO_PERSON, BILLING_GOODS_AND_SERVICES_IN_ADVANCE, BILLING_GOODS_AND_SERVICES_IN_ARREARS, PISP_PAYEE, ECOMMERCE_MERCHANT_INITIATED_PAYMENT, FACE_TO_FACE_POINT_OF_SALE, TRANSFER_TO_SELF, TRANSFER_TO_THIRD_PARTY | Specifies the payment context, BillPayment, EcommerceGoods, EcommerceServices, Other, PersonToPerson | 1-50 | | `merchantCategoryCode` | Category code conform to ISO 18245, related to the type of services or goods the merchant provides for the transaction. | ASPSP | Unique merchant category code. | O | 0..1 | String | Category code conform to ISO 18245, related to the type of services or goods the merchant provides for the transaction. | 1-256 | | `merchantCustomerIdentification` | Field is to enable capturing of a merchant's PSU unique identifier. | ASPSP | Used to specify the merchant's PSU identifier. | O | 0..1 | String | The unique customer identifier of the PSU with the merchant. | | | `deliveryAddress` | Information that locates and identifies delivery address. | ASPSP | This element is usually used to identify the delivery address. | O | 0..1 | Object | Information that locates and identifies a specific address, as defined by postal services or in free format text. | | | `addressLine` | Information that locates and identifies a specific address, as defined by postal services that is presented in free format text. | ASPSP | This element is used to specify the specific postal address. | O | 0..2 | String | Information that locates and identifies a specific address, as defined by postal services, that is presented in free format text. | | | `street` | Name of a street or thoroughfare. | ASPSP | This element is used to specify the street name. | O | 0..1 | String | Name of a street or thoroughfare. | 1-70 | | `buildingNumber` | Number that identifies the position of a building on a street. | ASPSP | This element is used to specify the building number. | O | 0..1 | String | Number that identifies the position of a building on a street. | 1-16 | | ` postalCode` | This element is used to specify the post code. | ASPSP | This element is used to specify the post code. | O | 0..1 | String | Identifier consisting of a group of letters and/or numbers that is added to a postal address to assist the sorting of mail. | 1-16 | | `city` | Name of a built-up area, with defined boundaries, and a local government. | ASPSP | This element is used to specify the city name. | M | 1..1 | String | Name of a built-up area, with defined boundaries, and a local government. | 1-35 | | `countrySubDivision` | Identifies a subdivision of a country such as state, region, county. | ASPSP | This element is used to specify the county code. | O | 0..1 | String | Identifies a subdivision of a country, for instance state, region, county. | 1-35 | | `country` | Country in which a person resides. | ASPSP | This element is used to specify the country code. | M | 1..1 | String | Nation with its own government, occupying a particular territory. | pattern: `^[A-Z]{2}$` | Tip: For an explanation of notations used, refer to **Open Banking General FAQ** in our [Frequently Asked Questions](https://developer.mastercard.com/open-banking-connect/documentation/frequently-asked-questions/index.md) section. ### Response -- Success {#response--success} HTTP Response Code = 200, OK Tip: For a list of general response codes and error code structure see [Response and Error Codes](https://developer.mastercard.com/open-banking-connect/documentation/response-and-error-codes/index.md). #### Response header {#response-header} N/A #### Response body {#response-body} | **Name** | **Purpose** | **Required by** | **How it can be used** | **Condition** | **Multiplicity** | **Type** | **Description** | **Limitations/Parameters** | |--------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------|-------------------------------------------------------------------------------------------------|---------------|------------------|----------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `originalRequestInfo` | Returns original request information to the TPP | MC | This object contains original request information | M | 1..1 | Object | Original request information received from the TPP | N/A | | `xRequestId` | A memorable ID which could be used to support in a dispute | TPP | This element could be used for request-response tracking | M | 1..1 | UUID | Reply back with xRequestId from the original TPP request | pattern: `^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$` | | `transfer` | Specifies transfer information in returned data | TPP | This element encapsulates all transfer information | M | 1..1 | Object | Set of elements used to reference a payment instruction | N/A | | `vrpId` | Unique identification to specify the payment resource | TPP | This value should be used to make subsequent payment specific requests | O | 0..1 | String | VRP id as returned | 1-256 | | `transactionStatus` | Specifies the status of the payment information group | TPP | Transaction Status of the VRP payment resource | O | 0..1 | String | Payment status as returned from the ASPSP and translated: ACCP, ACSC, ACSP, ACTC, ACWC, ACWP, PDNG, RCVD, RJCT, CANC | 1-256 | | `originalPaymentStatus` | VRP Payment status returned by the ASPSP | TPP | Can be used for tracking VRP status as originally returned by the ASPSP | O | 0..1 | String | Examples: AwaitingAuthorisation, Authorised, Pending, InitiationPending, InitiationFailed, Rejected, AcceptedSettlementInProgress, AcceptedSettlementCompleted, AcceptedWithoutPosting, AcceptedCreditSettlementCompleted, InitiationCompleted, Cancelled | 1-256 | | `originalvrpId` | VRP id returned by the ASPSP | TPP | Can be used for tracking the VRP to the ASPSP | O | 0..1 | String | VRP id as returned by the ASPSP | 1-256 | | `refundAccount` | refundAccount object is available in the response only when PSU has provided consent to share account details with the TPP. It includes PSU's account details. | TPP | This element encapsulates refund account details | O | 0..1 | Object | refundAccount object is available in the response only when PSU has provided consent to share account details with the TPP. It includes PSU's account details. | N/A | | `schemeName` | Name of the scheme, used to specify the account identification type. | TPP | This field is used to specify the account identification type | O | 0..1 | String | Name of the scheme, used to specify the account identification type. Example values: 'UK.AccountNumber' | 1-256 | | `identification` | Account identification number. It can be used on payload-level to mention specific account. | TPP | Details received in this field can be used for creditor account details in the reversed payment | O | 0..1 | String | Account identification number. It can be used on payload-level to mention specific account. | 1-256 | | `name` | This field is used to send the name of debtor account owner. | TPP | The data from this field should be used in the creditorName field for refund payments. | O | 0..1 | String | The account name is the name or names of the account owner(s) represented at an account level as it was assigned by the ASPSP. | 1-256 | | `refundAgent` | refundAgent object is available in the response only when PSU has provided consent to share account details with the TPP. It includes details of the financial institution servicing the refund account. | TPP | This element encapsulates refund agent details | O | 0..1 | Object | Object encapsulating refund agent details | refundAgent object is available in the response only when PSU has provided consent to share account details with the TPP. It includes details of the financial institution servicing the refund account. | | `clearingSystemIdentification` | Denomination of the system, used to specify agent identification type. | TPP | This field is used to specify the type of agent identification. | O | 0..1 | String | Denomination of the system, used to specify agent identification type. Example: 'UK.SortCode' | 1-256 | | `memberIdentification` | Identification code of the financial institution as assigned by the ISO 9362 Registration Authority. | TPP | This element is used to specify the financial institution identification code. | O | 0..1 | String | Identification code to identify the financial institution. | 1-256 | | `consentId` | A unique reference to the account information consent stored by the ASPSP. | TPP | This is used to enable VRP initiation requests related to the consent | O | 0..1 | String | Consent identification | 1-256 | ## Feature specific error codes {#feature-specific-error-codes} Tip: For a list of general response codes and error code structure see [Response and Error Codes](https://developer.mastercard.com/open-banking-connect/documentation/response-and-error-codes/index.md). | **Message** | **Reason Code** | **Description** | **Developer Details** | **Typical Occurrences** | **Next Steps** | |-----------------------------------------------------------------------------------------------------|-----------------|----------------------------------------------------------------------------------------------|-----------------------------------------------------------|--------------------------------------------------|--------------------------------------------------------------------------------------| | "\[Path 'path\[i\]'\] Numeric instance is lower than the required minimum (minimum: 0, found: %s)"" | `FORMAT_ERROR` | The value provided for the amount field in instructedAmount object is less or equal to zero. | Return as path to the element that failed the validation. | Typically occurs due to submitting user's error. | Ensure that a value greater than 0 is populated as Amount and re-submit the message. | **Error example code** ```json { "Errors": { "Error": [ { "Source": "OBC", "ReasonCode": "FORMAT_ERROR", "Description": "[Path '/consent/maximalIndividualAmount/amount'] Numeric instance is lower than the required minimum (minimum: 0, found: -2)", "Details": "path[0]=/instructedAmount/amount" } ] } } ``` | **Message** | **Reason Code** | **Description** | **Developer Details** | **Typical Occurrences** | **Next Steps** | |--------------------------------------------------|-----------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------------|----------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | "Method not supported by Provider's API profile" | `NOT_FOUND` | Method not supported by ASPSP. Depending on the API Standard /Profile implemented at the side of the ASPSP, some of the endpoints may not be available for that ASPSP. The information about API Profile support is provided in the specification for each endpoint. | N/A | Typically happens with new customers who send data not part of the API Standard. | Verify the specification and ensure that the endpoint is supported by the API Profile returned for the ASPSP (e.g. in /payments/aspsps or /accounts/aspsps). If you think you should be able to access the specified endpoint, contact the Open Banking Connect API support team. | **Error example code** ```json { "Errors": { "Error": [ { "Source": "OBC", "ReasonCode": "NOT_FOUND", "Description": "Method not supported by Provider's API profile" } ] } } ``` | **Message** | **Reason Code** | **Description** | **Developer Details** | **Typical Occurrences** | **Next Steps** | |---------------------------------------------------------------------------|-----------------|-----------------------------------------------------------------------|-----------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------| | "Conditional field psuIPAddress is expected when isLivePsuRequest='true'" | `FORMAT_ERROR` | "IP address" field is mandatory if parameter "isLivePsuRequest"=true. | "path\[i\]=;" where i = 0, 1, 2, etc. for each element that failed the validation | Typically occurs because the TPP has provided in request "isLivePsuRequest"=true and didn't provide the IP address value. | Provide IP address of PSU in the request when providing "isLivePsuRequest"=true. | **Error example code** ```json { "Errors": { "Error": [ { "Source": "OBC", "ReasonCode": "FORMAT_ERROR", "Description": "Conditional field psuIPAddress is expected when isLivePsuRequest='true", "Details": "path[0]=/requestInfo/psuIPAddress" } ] } } ``` | **Message** | **Reason Code** | **Description** | **Developer Details** | **Typical Occurrences** | **Next Steps** | |---------------------------------------------------------------------------------|-----------------|-----------------------------------------------------------------------------------------------------|-----------------------|---------------------------------------------------------------------------------------------------------------------------------------|--------------------------------------------| | "Both debtorAccount and deborAgent are required when at least one is specified" | `FORMAT_ERROR` | If one of the objects (debtorAccount or debtorAgent) was specified, the other one becomes required. | N/A | Typically occurs because the TPP has provided in request one of debtorAccount or debtorAgent objects, but haven't included the other. | Please include all debtor details or none. | **Error example code** ```json {"Errors": { "Error": [ {"Source": "OBC", "ReasonCode": "FORMAT_ERROR", "Description": "Both debtorAccount and deborAgent are required when at least one is specified", "Details": "path[0]=/payment/debtorAccount" } ] } } or {"Errors": { "Error": [ {"Source": "OBC", "ReasonCode": "FORMAT_ERROR", "Description": "Both debtorAccount and deborAgent are required when at least one is specified", "Details": "path[0]=/payment/debtorAgent" } ] } } ```