> ## Documentation Index > Fetch the complete documentation index at: https://docs.openfinance-hackathon.com/llms.txt > Use this file to discover all available pages before exploring further. # Create a File Payment > Create a File Payment ## OpenAPI ````yaml open-finance-api/yaml/uae-bank-initiation-openapi.yaml post /file-payments openapi: 3.0.0 info: title: UAE Payment API description: '## UAE Open Finance Payment API Specification' version: v1.2 servers: - url: /open-finance/payment/v1.2 security: [] tags: - name: Payment Initiation description: Initiate a Payment Consent - name: Payment Instruction description: Instruct the Payment - name: Payment Instruction File description: Instruct the File Payment - name: Payment Instruction File Report description: Retrieve the Payment Instruction File Report paths: /file-payments: post: tags: - Payment Instruction File summary: Create a File Payment description: | Create a File Payment operationId: CreateFilePayment parameters: - $ref: '#/components/parameters/authorization' - $ref: '#/components/parameters/x-fapi-auth-date' - $ref: '#/components/parameters/x-fapi-customer-ip-address' - $ref: '#/components/parameters/x-fapi-interaction-id-request' - $ref: '#/components/parameters/x-customer-user-agent' - $ref: '#/components/parameters/x-idempotency-key' requestBody: description: | Request Body content: application/jwt: schema: $ref: '#/components/schemas/AEFilePaymentRequestSigned' responses: '201': $ref: '#/components/responses/201FilePaymentId' '400': $ref: '#/components/responses/400Error' '401': $ref: '#/components/responses/401Error' '403': $ref: '#/components/responses/403Error' '405': $ref: '#/components/responses/405Error' '406': $ref: '#/components/responses/406Error' '415': $ref: '#/components/responses/415Error' '429': $ref: '#/components/responses/429Error' '500': $ref: '#/components/responses/500Error' security: - UserOAuth2Security: - openid - payments components: parameters: authorization: in: header name: authorization required: true description: An authorization Token as per https://tools.ietf.org/html/rfc6750 schema: type: string example: Bearer 12773da5-81c5-45e7-893c-381ca3cecc30 x-fapi-auth-date: in: header name: x-fapi-auth-date required: false description: >- The time when the User last logged in with the TPP. All dates in the HTTP headers are represented as RFC 7231 Full Dates. An example is below: Sun, 10 Sep 2023 19:43:31 UTC schema: type: string pattern: >- ^(Mon|Tue|Wed|Thu|Fri|Sat|Sun), \d{2} (Jan|Feb|Mar|Apr|May|Jun|Jul|Aug|Sep|Oct|Nov|Dec) \d{4} \d{2}:\d{2}:\d{2} (GMT|UTC)$ example: Thu, 26 Jan 2023 16:31:32 UTC x-fapi-customer-ip-address: in: header name: x-fapi-customer-ip-address required: false description: The User's IP address if the User is currently logged in with the TPP. schema: type: string example: 51.235.115.203 x-fapi-interaction-id-request: in: header name: x-fapi-interaction-id required: false description: An RFC4122 UID used as a correlation id. schema: type: string example: 49df2c2c-6b80-40ee-96a1-71910a248048 x-customer-user-agent: in: header name: x-customer-user-agent description: Indicates the user-agent that the User is using. required: false schema: type: string example: >- Mozilla/5.0 (iPhone; CPU iPhone OS 10_3_1 like Mac OS X) AppleWebKit/603.1.30 (KHTML, like Gecko) Version/10.0 Mobile/14E304 Safari/602.1 x-idempotency-key: name: x-idempotency-key in: header description: > Ensures the LFI processes the resource successfully only once per x-idempotency-key The TPP must not change the request body while using the same x-idempotency-key, changes to the request body will not result any action on the end resource. The OFP will treat a request as idempotent if it had received the first request with the same x-idempotency-key from the same TPP in the preceding 24 hours. required: true schema: type: string maxLength: 40 pattern: ^(\S*)$ example: 78dae4513b8847f98e2d4173b4ed0eb6 schemas: AEFilePaymentRequestSigned: description: | Payment Request Signed Schema allOf: - $ref: '#/components/schemas/AEJwt' - type: object properties: message: $ref: '#/components/schemas/AEFilePaymentRequest' required: - message AEJwt: description: > [https://www.rfc-editor.org/rfc/rfc7519](https://www.rfc-editor.org/rfc/rfc7519) type: object properties: iss: description: > [https://www.rfc-editor.org/rfc/rfc7519#section-4.1.1](https://www.rfc-editor.org/rfc/rfc7519#section-4.1.1) type: string exp: description: > [https://www.rfc-editor.org/rfc/rfc7519#section-4.1.4](https://www.rfc-editor.org/rfc/rfc7519#section-4.1.4) type: number nbf: description: > [https://www.rfc-editor.org/rfc/rfc7519#section-4.1.5](https://www.rfc-editor.org/rfc/rfc7519#section-4.1.5) type: number aud: description: > [https://www.rfc-editor.org/rfc/rfc7519#section-4.1.3](https://www.rfc-editor.org/rfc/rfc7519#section-4.1.3) type: array items: type: string iat: description: > [https://www.rfc-editor.org/rfc/rfc7519#section-4.1.6](https://www.rfc-editor.org/rfc/rfc7519#section-4.1.6) type: number required: - iss - exp - nbf AEFilePaymentRequest: description: | File Payment Request Schema type: object additionalProperties: false required: - Data properties: Data: type: object additionalProperties: false required: - ConsentId - PaymentPurposeCode properties: ConsentId: $ref: '#/components/schemas/AEConsentId' Instruction: $ref: '#/components/schemas/AEFilePaymentConsent' PaymentPurposeCode: $ref: '#/components/schemas/AEPaymentPurposeCode' DebtorReference: $ref: '#/components/schemas/AEStructuredDebtorReference' AEFilePaymentIdResponseSigned: description: | Payment Response Signed Schema allOf: - $ref: '#/components/schemas/AEJwt' - type: object properties: message: $ref: '#/components/schemas/AEFilePaymentIdResponse' required: - message AEErrorResponseSigned: description: | Error Signed Schema allOf: - $ref: '#/components/schemas/AEJwt' - type: object properties: message: $ref: '#/components/schemas/AEErrorResponse' required: - message AEConsentId: description: > Unique identification assigned by the TPP to identify the consent resource. type: string minLength: 1 maxLength: 128 example: aac-69255d98-ab0e-4758-92a7-cacbf3073efa AEFilePaymentConsent: type: object description: | A file based payment consent. required: - FileType - FileHash - NumberOfTransactions - ControlSum properties: FileType: $ref: '#/components/schemas/AEFileType' FileHash: $ref: '#/components/schemas/AEFileHash' FileReference: $ref: '#/components/schemas/AEReference' NumberOfTransactions: $ref: '#/components/schemas/AEFileNumberOfTransactions' ControlSum: $ref: '#/components/schemas/AEControlSum' RequestedExecutionDate: $ref: '#/components/schemas/AERequestedExecutionDate' additionalProperties: false AEPaymentPurposeCode: description: >- A category code that relates to the type of services or goods that corresponds to the underlying purpose of the payment. The code must conform to the published Aani payment purpose code list. type: string minLength: 1 maxLength: 3 pattern: ^[A-Z]{3}$ AEStructuredDebtorReference: description: > A reason or reference in relation to a payment, set to facilitate a structured Debtor reference consisting of: * For payments to Merchants: TPP ID, Merchant ID, BIC for the Creditor Account, followed by freeform text to a maximum of 120 characters. * For other payments: TPP ID and BIC for the Creditor Account, followed by freeform text to a maximum of 120 characters. The TPP ID value will match the organization ID value from the Trust Framework, and therefore will be a v4 UUID. The Merchant ID wil be as per the existing Aani Core rules for the Merchant identification, and will incorporate the Trade License number for the Merchant. A BIC is specific according to the standard format for ISO 20022, and can therefore be either 8 or 11 characters in length. If the value of the concatenated string exceeds 120 characters, the TPP must omit or truncate the freeform element of the reference. type: string minLength: 1 maxLength: 120 pattern: >- ^TPP=[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12},(Merchant=[A-Z0-9]{3}-[A-Z]{4}-TL.+-[0-9]{4},|)BIC=[A-Z0-9]{4}[A-Z0-9]{2}[A-Z0-9]{2}([A-Z0-9]{3}){0,1}($|,.+$) AEFilePaymentIdResponse: description: | Payment Id Response Schema type: object additionalProperties: false required: - Data - Links properties: Data: type: object additionalProperties: false required: - PaymentId - ConsentId - Status - StatusUpdateDateTime - CreationDateTime - Instruction - PaymentPurposeCode properties: PaymentId: $ref: '#/components/schemas/AEPaymentId' ConsentId: $ref: '#/components/schemas/AEConsentId' Status: $ref: '#/components/schemas/AEFilePaymentStatus' StatusUpdateDateTime: $ref: '#/components/schemas/AEStatusUpdateDateTime' CreationDateTime: $ref: '#/components/schemas/AECreationDateTime' Charges: $ref: '#/components/schemas/AECharges' Instruction: $ref: '#/components/schemas/AEFilePaymentConsent' PaymentPurposeCode: $ref: '#/components/schemas/AEPaymentPurposeCode' OpenFinanceBilling: $ref: >- #/components/schemas/AEServiceInitiationOpenFinanceFilePaymentBilling Links: $ref: '#/components/schemas/AELinksRelatedConsent' Meta: $ref: '#/components/schemas/AEMeta' AEErrorResponse: description: >- An array of detail error codes, and messages, and URLs to documentation to help remediation. type: object properties: Errors: items: $ref: '#/components/schemas/AEError' type: array minItems: 1 required: - Errors additionalProperties: false AEFileType: type: string description: Specifies the payment file type minLength: 1 maxLength: 40 AEFileHash: type: string description: A base64 encoding of a SHA256 hash of the file to be uploaded. minLength: 1 maxLength: 44 AEReference: description: | A reason or reference in relation to a payment. type: string minLength: 1 maxLength: 120 AEFileNumberOfTransactions: type: integer description: "Number of individual transactions contained in the payment information group.\t\n" AEControlSum: description: > Total of all individual amounts included in the group, irrespective of currencies. type: string pattern: ^\d{1,16}\.\d{2}$ example: '100.00' AERequestedExecutionDate: description: > The date when the TPP expects the LFI to execute the payment. The date must be in the future and cannot be on the same day or a day in the past. The maximum date in the future that can be specified is 1 year from the day of the consent of the User to the TPP. All dates in the JSON payloads are represented in ISO 8601 date format. type: string format: date AEPaymentId: description: >- An API specific unique identification as assigned by the LFI to identify the domestic Payment resource. type: string minLength: 1 maxLength: 40 example: 83b47199-90c2-4c05-9ef1-aeae68b0fc7c AEFilePaymentStatus: description: | Specifies the status of the payment information group * Received: The file payment has been received. * Rejected: The file payment has been rejected. type: string enum: - Received - Rejected example: Received AEStatusUpdateDateTime: description: >- Date and time at which the resource status was updated.All dates in the JSON payloads are represented in ISO 8601 date-time format. All date-time fields in responses must include the timezone. An example is below: 2023-04-05T10:43:07+00:00 type: string format: date-time AECreationDateTime: description: >- Date and time at which the message was created. All dates in the JSON payloads are represented in ISO 8601 date-time format. All date-time fields in responses must include the timezone. An example is below: 2023-04-05T10:43:07+00:00 type: string format: date-time AECharges: type: array items: type: object additionalProperties: false description: > Set of elements used to provide details of a charge for the payment initiation. * For Payments, these Charges are on the Debtor. required: - ChargeBearer - Type - Amount properties: ChargeBearer: $ref: '#/components/schemas/AEChargeBearerType1Code' Type: $ref: '#/components/schemas/AEExternalPaymentChargeTypeCode' Amount: $ref: '#/components/schemas/AEActiveCurrencyAmount' AEServiceInitiationOpenFinanceFilePaymentBilling: type: object properties: NumberOfSuccessfulTransactions: type: integer description: "Number of individual transactions successfully executed by the LFI.\t\nThis is returned by the LFI after the file is fully processed.\n" description: Billing parameters specified by the LFI additionalProperties: false AELinksRelatedConsent: type: object description: Links relevant to the resource required: - Self - Related properties: Self: $ref: '#/components/schemas/AERelatedSinglePayment' Related: $ref: '#/components/schemas/AESelfConsent' additionalProperties: false AEMeta: type: object description: Meta Data relevant to the resource additionalProperties: false AEError: description: Error type: object required: - Code - Message additionalProperties: false minProperties: 1 properties: Code: description: Low level textual error code type: string enum: - AccessToken.Unauthorized - AccessToken.InvalidScope - Consent.TransientAccountAccessFailure - Consent.AccountTemporarilyBlocked - Consent.PermanentAccountAccessFailure - Consent.Invalid - Consent.BusinessRuleViolation - Consent.FailsControlParameters - Consent.InvalidUserIdentifier - JWS.InvalidSignature - JWS.Malformed - JWS.InvalidClaim - JWS.InvalidHeader - JWE.DecryptionError - JWE.InvalidHeader - GenericRecoverableError - GenericError - Event.UnexpectedEvent - Body.InvalidFormat - Resource.InvalidResourceId - Resource.InvalidFormat Message: $ref: '#/components/schemas/AEMessage' Path: description: >- Recommended but optional reference to the JSON Path of the field with error, e.g., Data.Initiation.InstructedAmount.Currency type: string minLength: 1 maxLength: 500 Url: description: >- URL to help remediate the problem, or provide more information, or to API Reference, or help etc type: string AEChargeBearerType1Code: description: >- Specifies which party/parties will bear the charges associated with the processing of the payment transaction. type: string enum: - BorneByCreditor - BorneByDebtor - Shared AEExternalPaymentChargeTypeCode: description: Charge type, in a coded form. type: string enum: - VAT - Fees AEActiveCurrencyAmount: description: | The Currency and Amount relating to the Payment type: object required: - Amount - Currency properties: Amount: $ref: '#/components/schemas/AEActiveOrHistoricAmount' Currency: $ref: '#/components/schemas/AEActiveOrHistoricCurrencyCode' AERelatedSinglePayment: type: string format: uri description: A link to the current payment resource example: >- https://api.lfi.sa/open-banking/payment/2023.11.01-final/payments/83b47199-90c2-4c05-9ef1-aeae68b0fc7c AESelfConsent: description: A link to the related payment consents resource type: string format: uri example: >- https://api.lfi.sa/open-banking/payment/2023.11.01-final/payment-consents/aac-69255d98-ab0e-4758-92a7-cacbf3073efa AEMessage: description: >- A description of the error that occurred. e.g., 'A mandatory field isn't supplied' or 'RequestedExecutionDate must be in future' UAEOF doesn't standardise this field type: object required: - en properties: en: type: string description: English value of the string minLength: 1 maxLength: 500 ar: type: string description: Arabic value of the string minLength: 1 maxLength: 500 additionalProperties: false AEActiveOrHistoricAmount: description: >- A number of monetary units specified in an active currency where the unit of currency is explicit and compliant with ISO 4217. type: string pattern: ^\d{1,16}\.\d{2}$ example: '100.00' AEActiveOrHistoricCurrencyCode: description: >- A 3 character alphabetic code allocated to a currency under an international currency identification scheme, as described in the latest edition of the international standard ISO 4217 'Codes for the representation of currencies and funds'. type: string pattern: ^[A-Z]{3,3}$ example: AED responses: 201FilePaymentId: description: File Payment Id headers: x-fapi-interaction-id: $ref: '#/components/headers/x-fapi-interaction-id' x-idempotency-key: $ref: '#/components/headers/x-idempotency-key-consent' Location: $ref: '#/components/headers/Location' content: application/jwt: schema: $ref: '#/components/schemas/AEFilePaymentIdResponseSigned' 400Error: description: Bad request headers: x-fapi-interaction-id: $ref: '#/components/headers/x-fapi-interaction-id' content: application/jwt: schema: $ref: '#/components/schemas/AEErrorResponseSigned' examples: Bad Request: $ref: '#/components/examples/Error400BadRequestSigned' 401Error: description: Unauthorized headers: x-fapi-interaction-id: $ref: '#/components/headers/x-fapi-interaction-id' 403Error: description: Forbidden headers: x-fapi-interaction-id: $ref: '#/components/headers/x-fapi-interaction-id' content: application/jwt: schema: $ref: '#/components/schemas/AEErrorResponseSigned' examples: Forbidden: $ref: '#/components/examples/Error403ForbiddenSigned' 405Error: description: Method Not Allowed headers: x-fapi-interaction-id: $ref: '#/components/headers/x-fapi-interaction-id' 406Error: description: Not Acceptable headers: x-fapi-interaction-id: $ref: '#/components/headers/x-fapi-interaction-id' 415Error: description: Unsupported Media Type headers: x-fapi-interaction-id: $ref: '#/components/headers/x-fapi-interaction-id' 429Error: description: Too Many Requests headers: Retry-After: description: Number in seconds to wait schema: type: integer x-fapi-interaction-id: $ref: '#/components/headers/x-fapi-interaction-id' 500Error: description: Internal Server Error headers: x-fapi-interaction-id: $ref: '#/components/headers/x-fapi-interaction-id' content: application/jwt: schema: $ref: '#/components/schemas/AEErrorResponseSigned' examples: Internal Server Error: $ref: '#/components/examples/Error500InternalServerErrorSigned' headers: x-fapi-interaction-id: required: true description: An RFC4122 UID used as a correlation id. schema: type: string example: 49df2c2c-6b80-40ee-96a1-71910a248048 x-idempotency-key-consent: description: >- Ensures the LFI processes the resource successfully only once per x-idempotency-key schema: type: string maxLength: 40 pattern: ^(\S*)$ example: 78dae4513b8847f98e2d4173b4ed0eb6 Location: description: URI location to the created resource required: true schema: type: string maxLength: 40 examples: Error400BadRequestSigned: summary: 400 Bad Request description: 400 Bad Request value: iss: c50f0152-49bb-4dc4-b866-b625271c4e78 exp: 3349494246 nbf: 1675765189 aud: - e63df191-5fff-4e9c-bba2-b273c94e87f0 iat: 1675765189 message: Errors: - Code: GenericError Message: en: A mandatory field is missing. Error403ForbiddenSigned: summary: 403 Forbidden description: 403 Forbidden value: iss: c50f0152-49bb-4dc4-b866-b625271c4e78 exp: 3349494246 nbf: 1675765189 aud: - e63df191-5fff-4e9c-bba2-b273c94e87f0 iat: 1675765189 message: Errors: - Code: AccessToken.InvalidScope Message: en: >- The access token did not have an appropriate scope attached to it. Error500InternalServerErrorSigned: summary: 500 Internal Server Error description: 500 Internal Server Error value: iss: c50f0152-49bb-4dc4-b866-b625271c4e78 exp: 3349494246 nbf: 1675765189 aud: - e63df191-5fff-4e9c-bba2-b273c94e87f0 iat: 1675765189 message: Errors: - Code: GenericError Message: en: >- An Internal Server error has occurred. Please retry in 60 seconds. securitySchemes: UserOAuth2Security: type: oauth2 description: >- [OAuth2 PAR flow](https://datatracker.ietf.org/doc/html/rfc9126), it is required when the User needs to perform SCA with the LFI when a TPP wants to access an LFI resource owned by the User. **Please refer to [OpenID FAPI Security Profile 1.0 -Part 2 Advanced](https://openid.net/specs/openid-financial-api-part-2-1_0.html#authorization-server) - 5.2.2 point 14 - shall authenticate the confidential client using one of the following methods private_key_jwt and [OpenID Connect Core 1.0](https://openid.net/specs/openid-connect-core-1_0.html#ClientAuthentication) 9. Client Authentication private_key_jwt** flows: authorizationCode: authorizationUrl: https://authserver.example/authorization tokenUrl: https://authserver.example/token scopes: openid: Activates OpenID Connect Support payments: >- Ability for initiating payments. This is a parameterized scope with the ConsentId accounts: Ability for accessing account information. ````