openapi: 3.2.0 info: version: 1.3.0 title: Xe.Api.Payments Recipient API tags: - name: Recipient paths: /recipients: get: tags: - Recipient summary: Gets recipients for a currency. description: "Sample requests:\n \n GET /recipients?currency=GBP\n \n\\\nRequired user rights:\n \n CanAccessRecipients" operationId: Get parameters: - name: currency in: query description: Get recipients for a specific currency. required: false schema: type: string responses: '200': description: Returns the list of recipients. content: text/plain: schema: $ref: '#/components/schemas/RecipientListResponse' application/json: schema: $ref: '#/components/schemas/RecipientListResponse' example: content: - id: 1234567 name: Joe Smith currency: GBP accountNumber: '87654321' accountName: Joe Smith bankName: BankName bankCountry: GB nickname: Nickname paymentReference: Reference purposeOfPaymentCode: PRIV_OTHER purposeOfPaymentFreeText: Free text bankAddressLine1: Bank 1 bankAddressLine2: Bank 2 bankAddressLine3: Bank 3 bankBic: '194857' nationalClearingCode: '1235457' addressLine1: Address1 addressLine2: Address2 addressLine3: Address3 email: Joe.Smith@email.com intermediaryBankAddressLine1: IntBank1 intermediaryBankAddressLine2: IntBank2 intermediaryBankAddressLine3: IntBank3 intermediaryBankBic: '6582342' intermediaryNationalClearingCode: '6534211' intermediaryBankName: IntBankName intermediaryBankAddressCountryCode: GB intermediaryAccountNumber: '564245821' text/json: schema: $ref: '#/components/schemas/RecipientListResponse' '400': description: Request was invalid. content: text/plain: schema: $ref: '#/components/schemas/RecipientListResponse' application/json: schema: $ref: '#/components/schemas/RecipientListResponse' example: message: Invalid currency code. errors: - code: RECIPIENT001 data: - key: currency value: '123' text/json: schema: $ref: '#/components/schemas/RecipientListResponse' '404': description: No recipients were found. '500': description: Error getting recipients. post: tags: - Recipient summary: Creates a recipient with the details provided. description: "Sample request:\n \n POST /recipients\n \n\\\nRequired user rights:\n \n CanAddRecipient" operationId: Create responses: '200': description: Returns the created recipient. content: text/plain: schema: $ref: '#/components/schemas/RecipientResponse' application/json: schema: $ref: '#/components/schemas/RecipientResponse' example: content: id: 1234567 name: Joe Smith currency: GBP accountNumber: '87654321' accountName: Joe Smith bankName: BankName bankCountry: GB nickname: Nickname paymentReference: Reference purposeOfPaymentCode: PRIV_OTHER purposeOfPaymentFreeText: Free text bankAddressLine1: Bank 1 bankAddressLine2: Bank 2 bankAddressLine3: Bank 3 bankBic: '194857' nationalClearingCode: '1235457' addressLine1: Address1 addressLine2: Address2 addressLine3: Address3 email: Joe.Smith@email.com intermediaryBankAddressLine1: IntBank1 intermediaryBankAddressLine2: IntBank2 intermediaryBankAddressLine3: IntBank3 intermediaryBankBic: '6582342' intermediaryNationalClearingCode: '6534211' intermediaryBankName: IntBankName intermediaryBankAddressCountryCode: GB intermediaryAccountNumber: '564245821' warnings: - code: WARN001 information: - code: INFO001 text/json: schema: $ref: '#/components/schemas/RecipientResponse' '400': description: Request was invalid. content: text/plain: schema: $ref: '#/components/schemas/RecipientResponse' application/json: schema: $ref: '#/components/schemas/RecipientResponse' example: message: Request failed validation. errors: - code: CREATE_RECIPIENT_REQUEST_VALIDATION data: - key: BankCountryCode value: Country code must be 2 characters. text/json: schema: $ref: '#/components/schemas/RecipientResponse' '500': description: Error creating recipient. requestBody: content: application/json-patch+json: schema: $ref: '#/components/schemas/RecipientRequest' application/json: schema: $ref: '#/components/schemas/RecipientRequest' text/json: schema: $ref: '#/components/schemas/RecipientRequest' application/*+json: schema: $ref: '#/components/schemas/RecipientRequest' description: "Details needed to create a recipient. The fields that are required, and those that can be included in the request, vary depending on the country and the currency.\n Use GET /recipients/fields/{country}/{currency} to retrieve the valid format for the country/currency combination." /recipients/{recipientId}: delete: tags: - Recipient summary: Delete a recipient. description: "Sample request:\n \n DELETE /recipients/{recipientId}\n \n\\\nRequired user rights:\n \n CanDeleteRecipient" operationId: Delete parameters: - name: recipientId in: path description: Recipient ID of recipient to delete. required: true schema: type: integer format: int32 responses: '204': description: Recipient has been deleted. '404': description: Recipient not found. '500': description: Error occurred while deleting the recipient. /recipients/fields/{country}/{currency}: get: tags: - Recipient summary: Gets all recipient field definitions for a user for a specified currency and a country. description: "Sample request:\n \n GET /recipients/fields/AU/GBP\n \n\\\nRequired user rights:\n \n CanAccessRecipients\n \n\\\n
**Names and descriptions for the fields that can be returned**\n* ibanOrAccountNumber - Used if either an IBAN, or an domestic Account Number can be provided.\n* accountNumber - Account Number (Domestic - with respect to the Bank Address Country Code) for the recipient's bank account.\n* iban - International Bank Account Number for the recipient's bank account.\n* nationalClearingCode - National Clearing Code for the recipient's bank.\n* bankAccountType - The type of bank account. (NOTE: is looking for an integer value that should map to the values stored for each type, e.g. 10 for Savings)\n* bankBic - Bank Identification Code for the recipient's bank.\n* bankName - Name of the bank for the recipient's account.\n* bankAddressLine1 - Line 1 of the address for the recipient's bank.\n* bankAddressLine2 - Line 2 of the address for the recipient's bank.\n* bankAddressLine3 - Line 3 of the address for the recipient's bank.\n* bankAddressCountryCode - Country code for the recipient's bank.\n* accountName - Name of the recipient on their bank account.\n* email - Email for the recipient.\n* addressLine1 - Line 1 of the address for the recipient.\n* addressLine2 - Line 2 of the address for the recipient.\n* addressCountryCode - Country code of the address for the recipient.\n* paymentReference - Client specified reference when making payments to the recipient.\n* intermediaryBankNationalClearingCode - National Clearing Code for an intermediary bank.\n* intermediaryBankBic - Bank Identification Code for an intermediary bank.\n* intermediaryBankName - Name of the intermediary bank.\n* intermediaryBankIbanOrAccountNumber - IBAN or Account Number for an intermediary bank.\n* intermediaryBankAddressLine1 - Line 1 of the address for an intermediary bank.\n* intermediaryBankAddressLine2 - Line 2 of the address for an intermediary bank.\n* intermediaryBankAddressLine3 - Line 3 of the address for an intermediary bank.\n* intermediaryBankAddressCountryCode - Country code for an intermediary bank.\n* purposeOfPaymentCode - Default purpose of payment code for the recipient.\n* purposeOfPaymentFreeText - Default purpose of payment free text for the recipient.\n* nickname - Nickname specified by the client.\n
" operationId: GetRecipientFieldDefinitions parameters: - name: country in: path description: Country code to get recipient field definitions for. required: true schema: type: string - name: currency in: path description: Currency code to get recipient field definitions for. required: true schema: type: string responses: '200': description: Returns all Recipient Field definitions. content: text/plain: schema: $ref: '#/components/schemas/RecipientFieldDefinitionsResponse' application/json: schema: $ref: '#/components/schemas/RecipientFieldDefinitionsResponse' example: content: fieldDefinitions: - fieldName: accountName regEx: ^[a-zA-Z0-9\s\(\)\+\-'/\?\.:,]{1,70}$ required: false fieldType: Text allowedValues: [] - fieldName: addressLine1 regEx: ^$|^[a-zA-Z0-9,\s\(\)\+\-'/\?\.:]{3,35}$ required: false fieldType: Text allowedValues: [] contentReplacements: COUNTRY_CODE: GB ACCOUNT_LENGTH: '8' errors: {} infos: {} text/json: schema: $ref: '#/components/schemas/RecipientFieldDefinitionsResponse' '400': description: Request was invalid. content: text/plain: schema: $ref: '#/components/schemas/RecipientFieldDefinitionsResponse' application/json: schema: $ref: '#/components/schemas/RecipientFieldDefinitionsResponse' example: message: Request failed validation. errors: - code: COUNTRY_VALIDATION data: - key: GBR value: Country code must be 2 characters. text/json: schema: $ref: '#/components/schemas/RecipientFieldDefinitionsResponse' '500': description: Error getting all Recipient Field definitions. components: schemas: RecipientListResponse: description: "Generic response returned for each request.\n \n\"message\" - Result from the request.\n\"content\" - Data returned in the response.\n\"errors\" - Issues while processing the request.\n\"warnings\" - Potential issues while processing the request or with the response data.\n\"information\" - Extra details relating to the response data.\nThe type of the content." type: object properties: content: uniqueItems: false type: array items: $ref: '#/components/schemas/Recipient' message: type: string errors: uniqueItems: false type: array items: $ref: '#/components/schemas/Message' warnings: uniqueItems: false type: array items: $ref: '#/components/schemas/Message' information: uniqueItems: false type: array items: $ref: '#/components/schemas/Message' Recipient: description: "Details for a recipient.\n \n\"id\" - ID of the recipient.\n\"name\" - Display name of the recipient.\n\"currency\" - Currency code for the recipient's account.\n\"accountNumber\" - Bank account number for the recipient.\n\"accountName\" - Name of the recipient on their bank account.\n\"bankName\" - Name of the bank for the recipient's account.\n\"bankCountry\" - Country where the recipient's bank is located.\n\"nickname\" - Nickname specified by the client.\n\"paymentReference\" - Client specified reference when making payments to the recipient.\n\"purposeOfPaymentCode\" - Default purpose of payment code for the recipient.\n\"purposeOfPaymentFreeText\" - Default purpose of payment free text for the recipient.\n\"bankAddressLine1\" - Line 1 of the address for the recipient’s bank.\n\"bankAddressLine2\" - Line 2 of the address for the recipient’s bank.\n\"bankAddressLine3\" - Line 3 of the address for the recipient’s bank.\n\"bankBic\" - Bank Identification Code for the recipient’s bank.\n\"nationalClearingCode\" - National Clearing Code for the recipient’s bank.\n\"addressLine1\" - Line 1 of the address for the recipient.\n\"addressLine2\" - Line 2 of the address for the recipient.\n\"addressLine3\" - Line 3 of the address for the recipient.\n\"email\" - Email address for the recipient.\n\"intermediaryBankAddressLine1\" - Line 1 of the address for an intermediary bank.\n\"intermediaryBankAddressLine2\" - Line 2 of the address for an intermediary bank.\n\"intermediaryBankAddressLine3\" - Line 3 of the address for an intermediary bank.\n\"intermediaryBankBic\" - Bank Identification Code for an intermediary bank.\n\"intermediaryNationalClearingCode\" - National Clearing Code for an intermediary bank.\n\"intermediaryBankName\" - Name for an intermediary bank.\n\"intermediaryBankAddressCountryCode\" - Country code of the address for an intermediary bank.\n\"intermediaryAccountNumber\" - Account Number for an intermediary bank." type: object properties: id: format: int32 type: integer name: type: string currency: type: string accountNumber: type: string accountName: type: string bankName: type: string bankCountry: type: string nickname: type: string paymentReference: type: string purposeOfPaymentCode: type: string purposeOfPaymentFreeText: type: string bankAddressLine1: type: string bankAddressLine2: type: string bankAddressLine3: type: string bankBic: type: string nationalClearingCode: type: string addressLine1: type: string addressLine2: type: string addressLine3: type: string email: type: string intermediaryBankAddressLine1: type: string intermediaryBankAddressLine2: type: string intermediaryBankAddressLine3: type: string intermediaryBankBic: type: string intermediaryNationalClearingCode: type: string intermediaryBankName: type: string intermediaryBankAddressCountryCode: type: string intermediaryAccountNumber: type: string RecipientRequest: description: "Request body for creating a new recipient.\n \n\"bankCountryCode\" - Country code of the bank for the recipient.\n\"currencyCode\" - Currency code that the recipient is for.\n\"fields\" - Dynamic set of fields, which will include all the other required/optional fields to create a recipient for the country/currency combination." type: object properties: bankCountryCode: type: string currencyCode: type: string fields: uniqueItems: false type: array items: $ref: '#/components/schemas/RecipientField' example: bankCountryCode: GB currencyCode: GBP fields: - name: AccountName value: Account Name - name: AccountNumber value: '12548795' - name: NationalClearingCode value: '132546' - name: BankName value: Bank Name - name: BankAccountType value: '10' RecipientFieldDefinition: description: "Details for a recipient field definition.\n \n\"fieldName\" - Name of the recipient field.\n\"regEx\" - Allowed format of the field.\n\"required\" - Boolean value to indicate whether the field is mandatory or not.\n\"fieldType\" - Type of the field.\n\"allowedValues\" - Values allowed for the field. If it is null, can enter any value." type: object properties: fieldName: type: string regEx: type: string required: type: boolean fieldType: type: string allowedValues: uniqueItems: false type: array items: $ref: '#/components/schemas/LocalisableString' RecipientFieldDefinitionsResponse: description: "Generic response returned for each request.\n \n\"message\" - Result from the request.\n\"content\" - Data returned in the response.\n\"errors\" - Issues while processing the request.\n\"warnings\" - Potential issues while processing the request or with the response data.\n\"information\" - Extra details relating to the response data.\nThe type of the content." type: object properties: content: $ref: '#/components/schemas/RecipientFieldDefinitions' message: type: string errors: uniqueItems: false type: array items: $ref: '#/components/schemas/Message' warnings: uniqueItems: false type: array items: $ref: '#/components/schemas/Message' information: uniqueItems: false type: array items: $ref: '#/components/schemas/Message' RecipientResponse: description: "Generic response returned for each request.\n \n\"message\" - Result from the request.\n\"content\" - Data returned in the response.\n\"errors\" - Issues while processing the request.\n\"warnings\" - Potential issues while processing the request or with the response data.\n\"information\" - Extra details relating to the response data.\nThe type of the content." type: object properties: content: $ref: '#/components/schemas/Recipient' message: type: string errors: uniqueItems: false type: array items: $ref: '#/components/schemas/Message' warnings: uniqueItems: false type: array items: $ref: '#/components/schemas/Message' information: uniqueItems: false type: array items: $ref: '#/components/schemas/Message' RecipientField: type: object properties: name: type: string value: type: string RecipientFieldDefinitions: description: "Details for a recipient field definitions\n \n\"fieldDefinitions\" - List of recipient field definition.\n\"contentReplacements\" - A list of replacements values that are applicable to this recipient field definition.\n\"errors\" - A list of errors occured when requesting the field definitions.\n\"infos\" - A list of information for field definitions (if there is any)." type: object properties: fieldDefinitions: uniqueItems: false type: array items: $ref: '#/components/schemas/RecipientFieldDefinition' contentReplacements: type: object additionalProperties: type: string errors: type: object additionalProperties: type: object additionalProperties: type: string infos: type: object additionalProperties: type: object additionalProperties: type: string StringStringKeyValuePair: type: object properties: key: type: string readOnly: true value: type: string readOnly: true Message: description: "Details for an error or warning that occured during the request or general information from it.\n \n\"code\" - Code that can be used to find full details for the message.\n\"data\" - Any relevant data that caused the message, if applicable." type: object properties: code: type: string data: uniqueItems: false type: array items: $ref: '#/components/schemas/StringStringKeyValuePair' LocalisableString: description: "Details for the localisable string.\n \n\"externalCode\" - code to indentify the display name.\n\"text\" - Text to display for the field." type: object properties: externalCode: type: string text: type: string