> ## 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. # Retrieve a Payment > Retrieve a Payment ## OpenAPI ````yaml open-finance-api/yaml/uae-bank-initiation-openapi.yaml get /payments/{PaymentId} 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: /payments/{PaymentId}: get: tags: - Payment Instruction summary: Retrieve a Payment description: | Retrieve a Payment operationId: RetrievePayment 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/PaymentId' responses: '200': $ref: '#/components/responses/200PaymentId' '400': $ref: '#/components/responses/400Error' '401': $ref: '#/components/responses/401Error' '403': $ref: '#/components/responses/403Error' '404': $ref: '#/components/responses/404Error' '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: - TPPOAuth2Security: - 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 PaymentId: name: PaymentId in: path description: >- Unique identification as assigned by the LFI to uniquely identify the payment resource. schema: type: string minLength: 1 maxLength: 40 required: true example: 83b47199-90c2-4c05-9ef1-aeae68b0fc7c responses: 200PaymentId: description: Payment Id headers: x-fapi-interaction-id: $ref: '#/components/headers/x-fapi-interaction-id' content: application/jwt: schema: $ref: '#/components/schemas/AEPaymentIdResponseSigned' 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' 404Error: description: Not found headers: x-fapi-interaction-id: $ref: '#/components/headers/x-fapi-interaction-id' 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 schemas: AEPaymentIdResponseSigned: description: | Payment Response Signed Schema allOf: - $ref: '#/components/schemas/AEJwt' - type: object properties: message: $ref: '#/components/schemas/AEPaymentIdResponse' required: - message AEErrorResponseSigned: description: | Error Signed Schema allOf: - $ref: '#/components/schemas/AEJwt' - type: object properties: message: $ref: '#/components/schemas/AEErrorResponse' 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 AEPaymentIdResponse: description: | Payment Id Response Schema type: object additionalProperties: false required: - Data - Links properties: Data: type: object additionalProperties: false required: - PaymentId - ConsentId - Status - StatusUpdateDateTime - Instruction - CreationDateTime - PaymentPurposeCode - OpenFinanceBilling properties: PaymentId: $ref: '#/components/schemas/AEPaymentId' ConsentId: $ref: '#/components/schemas/AEConsentId' PaymentTransactionId: $ref: '#/components/schemas/AEPaymentTransactionId' Status: $ref: '#/components/schemas/AEPaymentStatus' StatusUpdateDateTime: $ref: '#/components/schemas/AEStatusUpdateDateTime' CreationDateTime: $ref: '#/components/schemas/AECreationDateTime' Charges: $ref: '#/components/schemas/AECharges' ExchangeRate: $ref: '#/components/schemas/AEExchangeRateInformation' CurrencyRequest: $ref: '#/components/schemas/AECurrencyRequest' Instruction: $ref: '#/components/schemas/AEPaymentInstruction' PaymentPurposeCode: $ref: '#/components/schemas/AEPaymentPurposeCode' DebtorReference: $ref: '#/components/schemas/AEStructuredDebtorReference' OpenFinanceBilling: $ref: >- #/components/schemas/AEServiceInitiationOpenFinancePaymentBilling 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 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 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 AEPaymentTransactionId: type: string description: > This is an end to end TransactionId that is generated by the underlying payment rails when it is sent from an Originating LFI to a Receiving LFI. For Aani Core transactions, this is the Aani Core generated TransactionId. This is not the same as the TransactionID in the Account Information Transactions API. The PaymentTransactionId must be populated if the payment is processed by the LFI. minimum: 1 maximum: 40 AEPaymentStatus: description: > Specifies the status of the payment information group * Pending: Payment initiation or individual transaction included in the payment initiation is pending. Further checks and status update will be performed. * Rejected: The payment initiation has been rejected * AcceptedSettlementCompleted: Settlement of the Debtor's account has been completed * AcceptedCreditSettlementCompleted: When the Creditor account has been credited with the funds of the payment initiated via the TPP * AcceptedWithoutPosting: When the Recipient Bank has accepted the payment but has not applied the credit to the Creditor account yet. type: string enum: - Pending - AcceptedSettlementCompleted - AcceptedCreditSettlementCompleted - AcceptedWithoutPosting - Rejected example: Pending 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' AEExchangeRateInformation: type: object additionalProperties: false required: - UnitCurrency - ExchangeRate - RateType description: >- Further detailed information on the exchange rate that has been used in the payment transaction - returned by the LFI. properties: UnitCurrency: description: >- Currency in which the rate of exchange is expressed in a currency exchange. In the example 1GBP = xxxCUR, the unit currency is GBP. type: string pattern: ^[A-Z]{3,3}$ ExchangeRate: description: >- The factor used for conversion of an amount from one currency to another. This reflects the price at which one currency was bought with another currency. type: number RateType: description: Specifies the type used to complete the currency exchange. type: string enum: - Actual - Agreed - Indicative ContractIdentification: description: >- Unique and unambiguous reference to the foreign exchange contract agreed between the initiating party/creditor and the debtor agent. type: string minLength: 1 maxLength: 256 ExpirationDateTime: description: >- Specified date and time the exchange rate agreement will expire. 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: 2017-04-05T10:43:07+00:00 type: string format: date-time AECurrencyRequest: description: > The details of the non-local currency or FX request that has been agreed between the User and the TPP. The LFI may return different ChargeBearer and ExchangeRateInformation in the Consent object. type: object additionalProperties: false required: - ExtendedPurpose - CurrencyOfTransfer properties: InstructionPriority: description: >- Indicator of the urgency or order of importance that the instructing party would like the instructed party to apply to the processing of the instruction. type: string enum: - Normal - Urgent ExtendedPurpose: description: >- Specifies the purpose of an international payment, when there is no corresponding 4 character code available in the ISO20022 list of Purpose Codes. type: string minLength: 1 maxLength: 140 ChargeBearer: $ref: '#/components/schemas/AEChargeBearerType1Code' CurrencyOfTransfer: description: >- Specifies the currency of the to be transferred amount, which is different from the currency of the debtor's account. type: string pattern: ^[A-Z]{3,3}$ DestinationCountryCode: description: >- Country in which Credit Account is domiciled. Code to identify a country, a dependency, or another area of particular geopolitical interest, on the basis of country names obtained from the United Nations (ISO 3166, Alpha-2 code). type: string pattern: '[A-Z]{2,2}' ExchangeRateInformation: type: object additionalProperties: false required: - UnitCurrency - RateType description: Provides details on the currency exchange rate and contract. properties: UnitCurrency: description: >- Currency in which the rate of exchange is expressed in a currency exchange. In the example 1GBP = xxxCUR, the unit currency is GBP. type: string pattern: ^[A-Z]{3,3}$ ExchangeRate: description: >- The factor used for conversion of an amount from one currency to another. This reflects the price at which one currency was bought with another currency. type: number RateType: description: Specifies the type used to complete the currency exchange. type: string enum: - Actual - Agreed - Indicative ContractIdentification: description: >- Unique and unambiguous reference to the foreign exchange contract agreed between the initiating party/creditor and the debtor agent. type: string minLength: 1 maxLength: 256 AEPaymentInstruction: type: object additionalProperties: false required: - Amount description: >- The Initiation payload is sent by the initiating party to the LFI. It is used to request movement of funds from the debtor account to a creditor for a single payment. properties: Amount: $ref: '#/components/schemas/AEActiveCurrencyAmount' 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}($|,.+$) AEServiceInitiationOpenFinancePaymentBilling: type: object required: - Type properties: Type: enum: - Collection - LargeValueCollection - PushP2P - PullP2P - Me2Me description: The type payment for billing type: string MerchantId: description: MerchantId type: string minLength: 8 maxLength: 20 description: Billing parameters specified by the TPP for a payment initiation 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 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: TPPOAuth2Security: type: oauth2 description: >- TPP confidential client authorization with the LFI to stage a consent. **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: clientCredentials: tokenUrl: https://authserver.example/token scopes: openid: Activates OpenID Connect Support payments: Ability for accessing payments. accounts: Ability for accessing account information. ````