{ "components": { "responses": { "APIError": { "content": { "application/json": { "schema": { "properties": { "code": { "description": "Error code", "example": "not_found", "type": "string" }, "details": { "description": "Error details", "type": "object" }, "message": { "description": "Error message", "type": "string" } }, "title": "APIError", "type": "object" } } }, "description": "Error response" } }, "schemas": { "ApiError": { "properties": { "code": { "description": "Machine-readable error code.", "type": "string" }, "details": { "additionalProperties": true, "description": "Additional error context.", "type": "object" }, "message": { "description": "Human-readable error message.", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "UaePaymentAccount": { "properties": { "id": { "type": "string" }, "identification": { "type": "string", "description": "Account identifier, its format is given by the accompanying scheme (e.g. an IBAN)." }, "name": { "type": "string", "description": "Name associated with this object, e.g. the account holder or party name." }, "schemeName": { "type": "string", "description": "Identification scheme for the account (e.g. IBAN)." } }, "required": [ "id", "name", "schemeName", "identification" ], "type": "object" }, "BahrainProviderListItem": { "properties": { "address": { "nullable": true, "type": "string" }, "arabicName": { "nullable": true, "type": "string" }, "country": { "$ref": "#/components/schemas/ProviderCountryResponse", "nullable": true }, "englishName": { "type": "string" }, "id": { "type": "string" }, "isEnable": { "type": "boolean" }, "logo": { "nullable": true, "type": "string" }, "phone": { "nullable": true, "type": "string" }, "status": { "type": "string", "description": "Current status of the resource." } }, "required": [ "englishName", "isEnable" ], "type": "object" }, "BankAccount": { "properties": { "accountHolderName": { "type": "string" }, "accountIdentification": { "type": "string" }, "bankName": { "type": "string" }, "createdAt": { "format": "date-time", "type": "string" }, "id": { "type": "string" }, "isDefault": { "type": "boolean" }, "name": { "nullable": true, "title": "Human-readable name of the account itself (e.g., \"My Savings\").", "type": "string", "description": "Name associated with this object, e.g. the account holder or party name." }, "scheme": { "description": "Identification scheme for the value (e.g. IBAN, national ID).", "nullable": true, "title": "Identification scheme of the account (e.g., \"UK.OBIE.IBAN\"/\"IBAN\").", "type": "string" } }, "required": [ "id", "bankName", "accountIdentification", "accountHolderName", "isDefault", "createdAt" ], "type": "object" }, "KsaProviderListItem": { "properties": { "address": { "nullable": true, "type": "string" }, "arabicName": { "nullable": true, "type": "string" }, "country": { "$ref": "#/components/schemas/ProviderCountryResponse", "nullable": true }, "englishName": { "type": "string" }, "id": { "type": "string" }, "isEnable": { "type": "boolean" }, "logo": { "nullable": true, "type": "string" }, "phone": { "nullable": true, "type": "string" }, "status": { "type": "string", "description": "Current status of the resource." } }, "required": [ "englishName", "isEnable" ], "type": "object" }, "PaymentRequest": { "properties": { "amount": { "type": "string", "description": "Monetary amount. Where paired with a currency, given as a decimal string (e.g. `250.00`)." }, "clientId": { "nullable": true, "title": "The client/merchant UUID used on the payment request.", "type": "string" }, "consentPermissions": { "items": { "type": "string" }, "nullable": true, "type": "array", "description": "Data permissions the consent grants (e.g. read balances, read transactions)." }, "createdAt": { "format": "date-time", "type": "string" }, "creditorAccountId": { "nullable": true, "title": "UAE: SpUaeBankAccount.Id linked to this payment request, used for V21\nCreditorPostalAddress lookup.", "type": "string" }, "creditorIdentification": { "nullable": true, "type": "string" }, "creditorName": { "nullable": true, "type": "string" }, "creditorReference": { "nullable": true, "type": "string", "description": "Your reference for the creditor/payee, echoed back for reconciliation." }, "creditorScheme": { "nullable": true, "type": "string" }, "creditorType": { "nullable": true, "type": "string", "description": "Type of creditor (e.g. `MERCHANT`)." }, "currencyCode": { "nullable": true, "type": "string" }, "debtorReference": { "nullable": true, "type": "string", "description": "Your reference for the debtor/payer." }, "externalReferenceId": { "nullable": true, "type": "string" }, "failureRedirectUrl": { "nullable": true, "type": "string", "description": "URL to redirect the payer to after a failed or cancelled authorization." }, "id": { "type": "string" }, "instructions": { "$ref": "#/components/schemas/PaymentInstructionsUAE", "nullable": true }, "internalReferenceId": { "type": "string" }, "isCopPerformed": { "type": "boolean" }, "paymentExecutionDate": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "string" } ], "nullable": true }, "paymentType": { "type": "string" }, "purpose": { "type": "string", "description": "Payment purpose code, see the [payment purpose codes](/docs/api-reference/payment-purpose-codes) reference." }, "risks": { "$ref": "#/components/schemas/PaymentRisks", "nullable": true, "description": "Risk metadata for the payment (e.g. delivery address, merchant category)." }, "status": { "type": "string", "description": "Current status of the resource." }, "successRedirectUrl": { "nullable": true, "type": "string", "description": "URL to redirect the payer to after a successful authorization." }, "updatedAt": { "format": "date-time", "type": "string" } }, "required": [ "id", "internalReferenceId", "externalReferenceId", "amount", "currencyCode", "status", "paymentType", "purpose", "clientId", "creditorType", "creditorScheme", "creditorIdentification", "creditorName", "creditorAccountId", "debtorReference", "creditorReference", "successRedirectUrl", "failureRedirectUrl", "paymentExecutionDate", "instructions", "risks", "isCopPerformed", "consentPermissions", "createdAt", "updatedAt" ], "type": "object" }, "ProviderCountryResponse": { "properties": { "arabicName": { "nullable": true, "type": "string" }, "createdAt": { "type": "string" }, "currency": { "$ref": "#/components/schemas/CurrencyResponse", "nullable": true, "description": "ISO 4217 currency code (e.g. `AED`, `SAR`)." }, "englishName": { "type": "string" }, "id": { "type": "string" }, "iso3166Code": { "nullable": true, "type": "string" }, "timeZone": { "nullable": true, "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "englishName" ], "type": "object" }, "UaeProviderListItem": { "properties": { "code": { "type": "string" }, "country": { "$ref": "#/components/schemas/ProviderCountryResponse", "nullable": true }, "id": { "type": "string" }, "logo": { "nullable": true, "type": "string" }, "name": { "type": "string", "description": "Name associated with this object, e.g. the account holder or party name." }, "status": { "type": "string", "description": "Current status of the resource." } }, "required": [ "code", "name" ], "type": "object" }, "ProviderListItem": { "anyOf": [ { "$ref": "#/components/schemas/KsaProviderListItem" }, { "$ref": "#/components/schemas/BahrainProviderListItem" }, { "$ref": "#/components/schemas/UaeProviderListItem" } ] }, "PurposeCode": { "properties": { "code": { "title": "Purpose code (e.g., 'EDU', 'SELF', 'FAM')", "type": "string" }, "description": { "title": "Description of the purpose code", "type": "string" }, "id": { "title": "Purpose code ID (GUID)", "type": "string" } }, "required": [ "id", "code", "description" ], "title": "Purpose code model.", "type": "object" }, "SyncConsentDetailsResponse": { "properties": { "consentId": { "type": "string" }, "consentVersion": { "type": "string" }, "expiresAt": { "type": "string" }, "paymentRequestId": { "type": "string" }, "resourceUri": { "type": "string" }, "status": { "$ref": "#/components/schemas/ConsentsStatus", "description": "Current status of the resource." }, "wasUpdated": { "type": "boolean" } }, "required": [ "consentId", "paymentRequestId", "status", "wasUpdated" ], "title": "Sync consent response (UAE only).", "type": "object" }, "CreateLinkPaymentTokenResponseData": { "properties": { "expires_at": { "type": "string", "description": "ISO 8601 timestamp when the link token expires (~1 hour)." }, "link_token": { "type": "string", "description": "Short-lived token passed to Spare Link to open the hosted authorization UI." }, "request": { "allOf": [ { "$ref": "#/components/schemas/InitiatePaymentRequestResponse" } ], "title": "Same shape as `POST /payment-requests` create" } }, "required": [ "link_token", "expires_at" ], "type": "object" }, "LinkExchangeMultipaymentData": { "properties": { "consentId": { "type": "string" }, "intent": { "enum": [ "payment" ], "type": "string" }, "mandateId": { "type": "string", "description": "UUID of the mandate this payment draws against." }, "resource_type": { "enum": [ "multipayment" ], "type": "string", "description": "Type of resource returned after link exchange." } }, "required": [ "intent", "resource_type", "consentId", "mandateId" ], "type": "object" }, "LinkExchangeSipData": { "properties": { "consentId": { "type": "string" }, "intent": { "enum": [ "payment" ], "type": "string" }, "paymentId": { "type": "string" }, "paymentStatus": { "type": "string" }, "resource_type": { "enum": [ "sip" ], "type": "string", "description": "Type of resource returned after link exchange." } }, "required": [ "intent", "resource_type", "paymentId", "paymentStatus", "consentId" ], "type": "object" }, "LinkExchangeResponseData": { "anyOf": [ { "$ref": "#/components/schemas/LinkExchangeSipData" }, { "$ref": "#/components/schemas/LinkExchangeMultipaymentData" } ] }, "MandateTransactionResponse": { "properties": { "approvedAmount": { "title": "Approved amount (0 when not approved)", "type": "number" }, "approvedAt": { "title": "When the transaction was approved (ISO 8601, null if not approved)", "type": "string" }, "executionDate": { "title": "Scheduled execution date (yyyy-MM-dd, optional)", "type": "string", "description": "ISO 8601 date the payment should execute." }, "id": { "title": "Transaction ID (GUID)", "type": "string" }, "isApproved": { "title": "Whether the transaction is approved for execution", "type": "boolean" }, "isVariable": { "title": "Whether the transaction has variable amount (requires approval)", "type": "boolean" }, "mandateId": { "title": "Mandate ID (GUID)", "type": "string", "description": "UUID of the mandate this payment draws against." }, "maxAmount": { "title": "Maximum amount allowed for this transaction", "type": "number" }, "status": { "title": "Current status (e.g. PENDING, COMPLETED)", "type": "string", "description": "Current status of the resource." } }, "required": [ "id", "mandateId", "status", "isApproved", "approvedAmount", "maxAmount", "isVariable" ], "title": "Response for schedule and approve endpoints", "type": "object" }, "ChargeBearerUAE": { "description": "Indicates who is responsible for bearing the charges associated with the payment.\n\n@property {string} BorneByCreditor - Charges are borne by the creditor (recipient) @property {string} BorneByDebtor - Charges are borne by the debtor (sender) @property {string} Shared - Charges are shared between creditor and debtor", "enum": [ "BorneByCreditor", "BorneByDebtor", "Shared" ], "title": "Enum representing the charge bearer options for UAE payment instructions.", "type": "string" }, "Account": { "properties": { "identification": { "type": "string", "description": "Account identifier, its format is given by the accompanying scheme (e.g. an IBAN)." }, "name": { "nullable": true, "type": "string", "description": "Name associated with this object, e.g. the account holder or party name." }, "schemeName": { "$ref": "#/components/schemas/AccountIdentificationScheme", "description": "Identification scheme for the account (e.g. IBAN)." } }, "required": [ "schemeName", "identification" ], "type": "object" }, "AmountDtoUAE": { "description": "\\- \\`amount\\`: decimal string, must match \\`^\\\\d{1,16}\\\\.\\\\d{2}$\\`. - \\`currency\\`: ISO-4217 3-letter uppercase. Both are required.", "properties": { "amount": { "type": "string", "description": "Monetary amount. Where paired with a currency, given as a decimal string (e.g. `250.00`)." }, "currency": { "type": "string", "description": "ISO 4217 currency code (e.g. `AED`, `SAR`)." } }, "required": [ "amount", "currency" ], "title": "Amount contract.", "type": "object" }, "CurrencyRequestUAE": { "properties": { "chargeBearer": { "$ref": "#/components/schemas/ChargeBearerUAE" }, "currencyOfTransfer": { "type": "string", "description": "ISO 4217 currency the funds are transferred in, for international payments." }, "destinationCountryCode": { "type": "string", "description": "ISO country code of the payment destination, for international payments." }, "exchangeRateInformation": { "$ref": "#/components/schemas/ExchangeRateInfoUAE" }, "fxQuoteId": { "type": "string", "description": "UUID of the FX quote to apply to an international payment." }, "priority": { "$ref": "#/components/schemas/InstructionPriorityUAE" }, "purpose": { "type": "string", "description": "Payment purpose code, see the [payment purpose codes](/docs/api-reference/payment-purpose-codes) reference." } }, "title": "Currency-related request information for UAE payment instructions.", "type": "object" }, "ExchangeRateInfoUAE": { "properties": { "contractIdentification": { "type": "string" }, "exchangeRate": { "type": "number" }, "rateType": { "$ref": "#/components/schemas/RateTypeUAE" }, "unitCurrency": { "type": "string" } }, "title": "Represents exchange rate information for UAE payment instructions.", "type": "object" }, "InitiatePaymentRequestResponse": { "properties": { "amount": { "nullable": true, "type": "string", "description": "Monetary amount. Where paired with a currency, given as a decimal string (e.g. `250.00`)." }, "createdAt": { "type": "string" }, "creditorAccount": { "$ref": "#/components/schemas/Account", "nullable": true, "description": "The payee (creditor) account that receives the funds." }, "creditorReference": { "nullable": true, "type": "string", "description": "Your reference for the creditor/payee, echoed back for reconciliation." }, "creditorType": { "nullable": true, "type": "string", "description": "Type of creditor (e.g. `MERCHANT`)." }, "currency": { "nullable": true, "type": "string", "description": "ISO 4217 currency code (e.g. `AED`, `SAR`)." }, "debtorReference": { "nullable": true, "type": "string", "description": "Your reference for the debtor/payer." }, "failureRedirectUrl": { "nullable": true, "type": "string", "description": "URL to redirect the payer to after a failed or cancelled authorization." }, "id": { "nullable": true, "type": "string" }, "instructions": { "$ref": "#/components/schemas/PaymentInstructionsUAE", "nullable": true }, "internalReference": { "nullable": true, "type": "string" }, "isCopVerified": { "type": "boolean" }, "merchantId": { "nullable": true, "type": "string" }, "merchantReference": { "nullable": true, "type": "string", "description": "Your merchant reference for this transaction, echoed back for reconciliation." }, "purpose": { "nullable": true, "type": "string", "description": "Payment purpose code, see the [payment purpose codes](/docs/api-reference/payment-purpose-codes) reference." }, "redirectUrl": { "nullable": true, "type": "string" }, "risks": { "$ref": "#/components/schemas/PaymentRisks", "nullable": true, "description": "Risk metadata for the payment (e.g. delivery address, merchant category)." }, "status": { "$ref": "#/components/schemas/PaymentRequestStatus", "description": "Current status of the resource." }, "successRedirectUrl": { "nullable": true, "type": "string", "description": "URL to redirect the payer to after a successful authorization." }, "type": { "$ref": "#/components/schemas/PaymentType", "description": "Variant selector, determines which other fields are required." }, "updatedAt": { "type": "string" } }, "required": [ "createdAt", "updatedAt", "status", "type", "isCopVerified" ], "title": "Single payment request in list/create response", "type": "object" }, "InstructionPriorityUAE": { "description": "Determines the urgency and processing speed of the payment.\n\n@property {string} Normal - Standard priority payment @property {string} Urgent - High priority payment requiring expedited processing", "enum": [ "Normal", "Urgent" ], "title": "Enum representing the priority level for UAE payment instructions.", "type": "string" }, "BankError": { "properties": { "Code": { "type": "string" }, "Errors": { "items": { "$ref": "#/components/schemas/BankErrorItem" }, "type": "array" }, "Id": { "type": "string" }, "Message": { "type": "string" } }, "title": "Error wrapper from the bank, present when the bank call fails.", "type": "object" }, "BankErrorItem": { "properties": { "ErrorCode": { "type": "string" }, "Message": { "type": "string" }, "Path": { "type": "string" }, "Url": { "type": "string" } }, "title": "Error item within the bank error response.", "type": "object" }, "BankLinks": { "properties": { "Related": { "type": "string" }, "Self": { "type": "string" } }, "title": "Links object returned by the bank.", "type": "object" }, "OpenFinanceBilling": { "properties": { "MerchantId": { "type": "string" }, "Type": { "type": "string" } }, "title": "Open finance billing info.", "type": "object" }, "PaymentCharge": { "properties": { "Amount": { "properties": { "Amount": { "type": "string" }, "Currency": { "type": "string" } }, "type": "object" }, "ChargeBearer": { "type": "string" }, "Type": { "type": "string" } }, "title": "Charge line-item from the bank payment response.", "type": "object" }, "PaymentEnvelope": { "properties": { "error": { "$ref": "#/components/schemas/BankError" }, "message": { "$ref": "#/components/schemas/PaymentMessage" }, "requestData": { "$ref": "#/components/schemas/RequestMetadata" }, "signedMessage": { "type": "string" } }, "type": "object", "description": "Bank payment response. The `message` field carries the provider's raw response payload." }, "PaymentExchangeRate": { "properties": { "ContractIdentification": { "type": "string" }, "ExchangeRate": { "type": "number" }, "ExpirationDateTime": { "type": "string" }, "RateType": { "type": "string" }, "UnitCurrency": { "type": "string" } }, "title": "Exchange rate info within a payment response.", "type": "object" }, "PaymentMessage": { "description": "Signed bank payment message envelope.", "properties": { "Data": { "$ref": "#/components/schemas/PaymentResponseData" }, "Links": { "$ref": "#/components/schemas/BankLinks" }, "Meta": { "properties": { "TotalPages": { "type": "number" } }, "type": "object" } }, "type": "object" }, "PaymentResponseData": { "properties": { "Charges": { "items": { "$ref": "#/components/schemas/PaymentCharge" }, "type": "array" }, "ConsentId": { "type": "string" }, "CreationDateTime": { "type": "string" }, "DebtorReference": { "type": "string" }, "DomesticPaymentId": { "title": "UAE domestic payment identifier (alias for PaymentId in some bank responses).", "type": "string" }, "ExchangeRate": { "$ref": "#/components/schemas/PaymentExchangeRate" }, "Links": { "$ref": "#/components/schemas/BankLinks" }, "OpenFinanceBilling": { "$ref": "#/components/schemas/OpenFinanceBilling" }, "PaymentId": { "type": "string" }, "PaymentPurposeCode": { "type": "string" }, "PaymentTransactionId": { "type": "string" }, "RejectReasonCode": { "items": { "$ref": "#/components/schemas/RejectReason" }, "type": "array" }, "Status": { "type": "string" }, "StatusUpdateDateTime": { "type": "string" } }, "title": "Data section of the bank payment response.", "type": "object" }, "RejectReason": { "properties": { "Code": { "type": "string" }, "Description": { "type": "string" } }, "title": "Reject reason code from the bank.", "type": "object" }, "RequestMetadata": { "properties": { "error": { "type": "string" }, "httpMethod": { "type": "string" }, "idempotencyKey": { "type": "string" }, "interactionId": { "type": "string" }, "requestSeconds": { "type": "number" }, "statusCode": { "type": "number" }, "url": { "type": "string" } }, "title": "Request metadata captured during a bank API call.", "type": "object" }, "PaymentInstructionPaymentScheduleUAE": { "description": "For Fixed the entry supplies \\`amount\\`; for Variable it supplies \\`maxAmount\\`.", "properties": { "amount": { "$ref": "#/components/schemas/AmountDtoUAE", "description": "Monetary amount. Where paired with a currency, given as a decimal string (e.g. `250.00`)." }, "maxAmount": { "$ref": "#/components/schemas/AmountDtoUAE" }, "paymentExecutionDate": { "type": "string" } }, "title": "A scheduled payment entry for Fixed/Variable Defined Schedule payments.", "type": "object" }, "PaymentInstructionPeriodicScheduleUAE": { "properties": { "amount": { "$ref": "#/components/schemas/AmountDtoUAE", "description": "Monetary amount. Where paired with a currency, given as a decimal string (e.g. `250.00`)." }, "controls": { "$ref": "#/components/schemas/PeriodicControlsUAE" }, "endDate": { "type": "string", "description": "ISO 8601 date the schedule ends." }, "frequency": { "$ref": "#/components/schemas/PeriodTypeUAE" }, "maxAmount": { "$ref": "#/components/schemas/AmountDtoUAE" }, "startDate": { "type": "string", "description": "ISO 8601 date the schedule starts." } }, "title": "Represents a periodic payment schedule for UAE payment requests.", "type": "object" }, "PaymentInstructionsUAE": { "properties": { "amount": { "$ref": "#/components/schemas/AmountDtoUAE", "description": "Monetary amount. Where paired with a currency, given as a decimal string (e.g. `250.00`)." }, "currencyRequest": { "$ref": "#/components/schemas/CurrencyRequestUAE" }, "isInternationalPayment": { "type": "boolean", "description": "When true, the payment is processed as an international transfer." }, "maxCumulativeAmount": { "$ref": "#/components/schemas/AmountDtoUAE" }, "maxCumulativeNumberOfPayments": { "type": "number", "description": "Maximum total number of payments allowed under a recurring mandate." }, "paymentSchedule": { "items": { "$ref": "#/components/schemas/PaymentInstructionPaymentScheduleUAE" }, "type": "array", "description": "Schedule defining when recurring payments execute." }, "periodicSchedule": { "$ref": "#/components/schemas/PaymentInstructionPeriodicScheduleUAE" }, "permissions": { "$ref": "#/components/schemas/PaymentPermissionsUAE" } }, "title": "Full instructions contract for UAE payment requests.", "type": "object" }, "PaymentPermissionsUAE": { "properties": { "confirmPayee": { "type": "boolean", "description": "When true, run payee name confirmation before initiating the payment." }, "readAccountsBasic": { "type": "boolean", "description": "Consent permission, read basic account identifiers." }, "readAccountsDetail": { "type": "boolean", "description": "Consent permission, read detailed account information." }, "readBalances": { "type": "boolean", "description": "Consent permission, read account balances." }, "readRefundAccount": { "type": "boolean", "description": "Consent permission, read the account's refund details." } }, "title": "Consent-scope permissions attached to a UAE payment instruction.", "type": "object" }, "PaymentRiskDeliveryAddress": { "properties": { "AddressLine": { "items": { "type": "string" }, "type": "array", "description": "Free-form address line." }, "BuildingNumber": { "type": "string", "description": "Building number of the address." }, "Country": { "type": "string", "description": "ISO country code of the address." }, "CountrySubDivision": { "items": { "type": "string" }, "type": "array", "description": "State, province, or region of the address." }, "PostCode": { "type": "string", "description": "Postal or ZIP code of the address." }, "StreetName": { "type": "string", "description": "Street name of the address." }, "TownName": { "type": "string", "description": "City or town of the address." } }, "title": "Delivery address within the risk section.", "type": "object" }, "PaymentRisks": { "properties": { "BeneficiaryAccountType": { "type": "string", "description": "Type of beneficiary account." }, "DeliveryAddress": { "$ref": "#/components/schemas/PaymentRiskDeliveryAddress" }, "MerchantCategoryCode": { "type": "string", "description": "ISO 18245 merchant category code (MCC)." }, "MerchantCustomerIdentification": { "type": "string", "description": "Your identifier for the customer at the merchant." }, "PaymentContextCode": { "type": "string", "description": "Context of the payment (e.g. e-commerce goods, bill payment)." } }, "title": "Risk section sent by the initiating party to the ASPSP.", "type": "object" }, "PeriodicControlsUAE": { "description": "Defines limits and constraints for payments within a specific period.", "properties": { "maxCumulativeAmountPerPeriod": { "$ref": "#/components/schemas/AmountDtoUAE" }, "maxCumulativeNumberOfPaymentsPerPeriod": { "type": "number" } }, "title": "Represents periodic controls for UAE payment schedules.", "type": "object" }, "PeriodTypeUAE": { "description": "Defines the frequency unit for periodic payment schedules.\n\n@property {string} Day - Daily period @property {string} Week - Weekly period @property {string} Month - Monthly period @property {string} Year - Yearly period", "enum": [ "Day", "Week", "Month", "Year" ], "title": "Enum representing the period type for UAE payment schedules.", "type": "string" }, "RateTypeUAE": { "description": "Indicates the nature of the exchange rate used for currency conversion.\n\n@property {string} Actual - Actual exchange rate used for the transaction @property {string} Agreed - Agreed exchange rate between parties @property {string} Indicative - Indicative exchange rate for reference purposes", "enum": [ "Actual", "Agreed", "Indicative" ], "title": "Enum representing the exchange rate type for UAE payment instructions.", "type": "string" }, "PaymentRequestStatus": { "enum": [ "New", "Consumed", "ConsentRaised", "Processed", "Rejected", "Errored", "Scheduled" ], "title": "PaymentRequestStatus from swagger", "type": "string" }, "PaymentType": { "enum": [ "SingleInstantPayment", "FixedDefinedSchedule", "VariableDefinedSchedule", "FixedPeriodicSchedule", "VariablePeriodicSchedule", "FixedOnDemand", "VariableOnDemand", "InternationalPayment" ], "title": "Payment type enum used by payment request flows.", "type": "string", "description": "The type of payment to initiate. Determines which instruction fields are required." }, "CreatePaymentRequestInput": { "properties": { "consentPermissions": { "items": { "type": "string" }, "title": "Consent permissions", "type": "array", "description": "Data permissions the consent grants (e.g. read balances, read transactions)." }, "creditorAccount": { "allOf": [ { "$ref": "#/components/schemas/Account" } ], "title": "Creditor account (required)", "description": "The payee (creditor) account that receives the funds." }, "creditorReference": { "title": "Creditor reference (required).", "type": "string", "description": "Your reference for the creditor/payee, echoed back for reconciliation." }, "creditorType": { "allOf": [ { "$ref": "#/components/schemas/CreditorType" } ], "title": "Creditor type (required)", "description": "Type of creditor (e.g. `MERCHANT`)." }, "debtorAccount": { "allOf": [ { "$ref": "#/components/schemas/Account" } ], "title": "Debtor account (optional)", "description": "The payer (debtor) account the funds are collected from." }, "debtorReference": { "title": "Debtor reference", "type": "string", "description": "Your reference for the debtor/payer." }, "failureRedirectUrl": { "title": "Failure redirect URL", "type": "string", "description": "URL to redirect the payer to after a failed or cancelled authorization." }, "instructions": { "allOf": [ { "$ref": "#/components/schemas/PaymentInstructionsUAE" } ], "description": "sub-fields (\\`amount\\` / \\`paymentSchedule\\` / \\`periodicSchedule\\` / …) are required for each \\`type\\`." }, "merchantReference": { "type": "string", "description": "Your merchant reference for this transaction, echoed back for reconciliation." }, "purpose": { "title": "Purpose code, valid PaymentPurpose enum value (required)", "type": "string", "description": "Payment purpose code, see the [payment purpose codes](/docs/api-reference/payment-purpose-codes) reference." }, "risks": { "allOf": [ { "$ref": "#/components/schemas/PaymentRisks" } ], "title": "Risk identifiers", "description": "Risk metadata for the payment (e.g. delivery address, merchant category)." }, "successRedirectUrl": { "title": "Success redirect URL", "type": "string", "description": "URL to redirect the payer to after a successful authorization." }, "type": { "allOf": [ { "$ref": "#/components/schemas/PaymentType" } ], "title": "Payment type (required)", "description": "Variant selector, determines which other fields are required." } }, "required": [ "type", "creditorType", "creditorReference", "creditorAccount", "purpose", "merchantReference", "instructions" ], "title": "Create payment request input - body for POST /payment/request/create (all\ntenants).", "type": "object" }, "CreditorType": { "enum": [ "MERCHANT", "USER", "CREDITOR" ], "title": "Creditor type enum", "type": "string" }, "CurrencyResponse": { "properties": { "arabicName": { "type": "string" }, "englishName": { "type": "string" }, "id": { "type": "string" }, "iso4117Code": { "type": "string" }, "iso4117Number": { "type": "string" } }, "required": [ "englishName", "iso4117Code" ], "title": "Shared currency response model used in account and payment.", "type": "object" }, "DomesticPaymentConsentResponse": { "properties": { "amount": { "$ref": "#/components/schemas/PaymentAmountResponse", "nullable": true, "description": "Monetary amount. Where paired with a currency, given as a decimal string (e.g. `250.00`)." }, "authorizationLink": { "nullable": true, "type": "string" }, "connection": { "$ref": "#/components/schemas/PaymentInitiationConnectionResponse", "nullable": true }, "consentId": { "nullable": true, "type": "string" }, "consentVersion": { "nullable": true, "title": "version-aware reference building during payment execution.", "type": "string" }, "createdAt": { "type": "string" }, "creditorAccount": { "$ref": "#/components/schemas/PaymentAccount", "nullable": true, "description": "The payee (creditor) account that receives the funds." }, "debtorAccount": { "$ref": "#/components/schemas/PaymentAccount", "nullable": true, "description": "The payer (debtor) account the funds are collected from." }, "encryptedRefreshToken": { "nullable": true, "title": "mandate payments.", "type": "string" }, "executionDateTime": { "nullable": true, "type": "string" }, "expiresAt": { "nullable": true, "title": "ISO-8601 timestamp (UTC) when the PAR authorization request expires.", "type": "string" }, "externalReference": { "nullable": true, "type": "string" }, "note": { "nullable": true, "type": "string" }, "paymentConsentType": { "$ref": "#/components/schemas/ConsentPaymentType", "nullable": true }, "paymentId": { "nullable": true, "type": "string" }, "providerId": { "nullable": true, "type": "string" }, "purpose": { "nullable": true, "type": "string", "description": "Payment purpose code, see the [payment purpose codes](/docs/api-reference/payment-purpose-codes) reference." }, "resourceUri": { "nullable": true, "title": "Opaque provider PAR `request_uri` (UAE). Required to construct the", "type": "string" }, "scope": { "$ref": "#/components/schemas/ConsentScope", "nullable": true }, "status": { "$ref": "#/components/schemas/ConsentsStatus", "nullable": true, "description": "Current status of the resource." } }, "required": [ "createdAt" ], "type": "object" }, "Pages": { "properties": { "currentPageNumber": { "type": "number" }, "pageSize": { "type": "number" }, "totalNumberOfPages": { "type": "number" } }, "required": [ "currentPageNumber", "pageSize", "totalNumberOfPages" ], "title": "Pagination meta (PagesModel)", "type": "object" }, "PaymentAccount": { "properties": { "id": { "nullable": true, "type": "string" }, "identification": { "type": "string", "description": "Account identifier, its format is given by the accompanying scheme (e.g. an IBAN)." }, "name": { "nullable": true, "type": "string", "description": "Name associated with this object, e.g. the account holder or party name." }, "schemeName": { "$ref": "#/components/schemas/AccountIdentificationScheme", "description": "Identification scheme for the account (e.g. IBAN)." } }, "required": [ "identification", "schemeName" ], "type": "object" }, "PaymentAmountResponse": { "properties": { "currency": { "$ref": "#/components/schemas/CurrencyResponse", "nullable": true, "description": "ISO 4217 currency code (e.g. `AED`, `SAR`)." }, "value": { "nullable": true, "type": "number" } }, "type": "object" }, "PaymentInitiationConnectionResponse": { "properties": { "createdAt": { "type": "string" }, "id": { "type": "string" }, "provider": { "$ref": "#/components/schemas/PaymentInitiationProvider", "nullable": true }, "status": { "$ref": "#/components/schemas/ConnectionStatus", "nullable": true, "description": "Current status of the resource." }, "updatedAt": { "type": "string" } }, "type": "object" }, "PaymentInitiationProvider": { "properties": { "address": { "nullable": true, "type": "string" }, "arabicName": { "nullable": true, "type": "string" }, "country": { "nullable": true, "type": "string" }, "englishName": { "type": "string" }, "id": { "type": "string" }, "isEnable": { "type": "boolean" }, "logo": { "nullable": true, "type": "string" }, "phone": { "nullable": true, "type": "string" }, "status": { "type": "string", "description": "Current status of the resource." } }, "required": [ "englishName" ], "type": "object" }, "AccountIdentificationScheme": { "enum": [ "IBAN", "AccountNumber" ], "title": "Shared account identification scheme used in payment.", "type": "string" }, "ConnectionStatus": { "enum": [ "ACTIVE", "INACTIVE" ], "type": "string" }, "ConsentPaymentType": { "enum": [ "SingleInstantPayment", "FixedDefinedSchedule", "VariableDefinedSchedule", "FixedPeriodicSchedule", "VariablePeriodicSchedule", "FixedOnDemand", "VariableOnDemand", "InternationalPayment" ], "title": "UAE `PaymentType` enum.", "type": "string" }, "ConsentScope": { "enum": [ "Accounts", "Payments" ], "type": "string" }, "ConsentsStatus": { "enum": [ "AwaitingAuthorization", "Authorized", "Consumed", "Finished", "Rejected", "Expired", "Revoked", "Suspended" ], "type": "string" }, "JsonWebKey": { "properties": { "alg": { "type": "string" }, "crv": { "type": "string" }, "e": { "type": "string" }, "kid": { "type": "string" }, "kty": { "type": "string" }, "n": { "type": "string" }, "use": { "enum": [ "sig", "enc" ], "type": "string" }, "x": { "type": "string" }, "y": { "type": "string" } }, "required": [ "kty" ], "type": "object" }, "BeneficiaryVerificationResponse": { "description": "Beneficiary verification result, the resolved account holder name, bank, account status, and the match outcome.", "properties": { "accountIdentifier": { "type": "string" }, "accountStatus": { "type": "string" }, "bank": { "$ref": "#/components/schemas/Bank" }, "beneficiaryName": { "type": "string" }, "errorDescription": { "type": "string" }, "executionDate": { "type": "string", "description": "ISO 8601 date the payment should execute." }, "inputBeneficiaryName": { "type": "string" }, "requestId": { "type": "string" }, "result": { "$ref": "#/components/schemas/VerificationResult", "nullable": true } }, "title": "Beneficiary-verification response payload.", "type": "object" }, "Bank": { "properties": { "arabicName": { "type": "string" }, "bankCode": { "type": "string" }, "englishName": { "type": "string" }, "swiftCode": { "type": "string" } }, "required": [ "englishName", "bankCode" ], "title": "Bank metadata returned alongside a verification result.", "type": "object" }, "VerificationResult": { "enum": [ "MATCH", "NO_MATCH", "ERROR" ], "title": "Beneficiary-verification outcome as surfaced on the JSON API (upper-snake).", "type": "string" } }, "securitySchemes": { "BearerAuth": { "bearerFormat": "JWT", "description": "Spare API token or OAuth access token.", "scheme": "bearer", "type": "http" } } }, "info": { "title": "Spare API", "version": "1" }, "openapi": "3.0.0", "paths": { "/auth/.well-known/jwks.json": { "get": { "description": "Includes the RSA PS512 key used to sign API-key JWTs (\\`kid\\` matches \\`deriveApiTokenJwtKidFromX509CertificatePem\\`, SHA-256 hex of UTF-8 JWK \\`n\\`+\\`e\\`, same as token headers) and the ECC ES256 key for data payloads (\\`kid\\` matches \\`deriveEccPlatformJwksKidFromX509CertificatePem\\`, SHA-256 hex of UTF-8 JWK \\`x\\`+\\`y\\`). Relying parties should cache this response for up to 5 minutes (\\`Cache-Control: public, max-age=300, stale-while-revalidate=60\\`) and re-fetch only when signature verification fails.\n\nResponse is a bare RFC 7517 JWKS: \\`{ \"keys\": \\[...] }\\`.\n\nGET /auth/.well-known/jwks.json", "operationId": "auth_getPlatformJwks", "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "keys": { "items": { "$ref": "#/components/schemas/JsonWebKey" }, "type": "array" } }, "required": [ "keys" ], "type": "object" } } }, "description": "Success response", "headers": { "cache-control": { "allowEmptyValue": true, "description": "HTTP cache directive for relying parties.", "explode": true, "required": true, "schema": { "type": "string" }, "style": "simple" } } }, "400": { "description": "Bad request. The request was invalid or failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Unauthorized, the access token is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "The token doesn't have access to this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Too many requests. Retry after a short wait.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Something went wrong on our side. Try again shortly.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "The bank or provider is temporarily unavailable. Retry later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "$ref": "#/components/responses/APIError" } }, "summary": "Returns the platform's public JSON Web Key Set (JWKS).", "tags": [ "auth" ], "x-fern-sdk-group-name": "auth", "x-fern-sdk-method-name": "getPlatformJwks", "parameters": [] } }, "/auth/.well-known/jwks/{provider}": { "get": { "description": "The tenant header (\\`X-Tenant\\`) determines which certificate store is queried. Returns 404 if the provider is unknown or has no certificates.\n\n\\`Cache-Control: private, max-age=300\\`, private because the response varies by \\`X-Tenant\\` and must not be served from a shared cache to a different tenant. The \\`Vary: X-Tenant\\` header is also set for RFC-compliant intermediaries that honour it.\n\nResponse is a bare RFC 7517 JWKS: \\`{ \"keys\": \\[...] }\\`.\n\nGET /auth/.well-known/jwks/:provider", "operationId": "auth_getProviderJwks", "parameters": [ { "allowEmptyValue": true, "explode": false, "in": "path", "name": "provider", "required": true, "schema": { "type": "string" }, "style": "simple", "description": "Bank provider code or ID, from the providers list." }, { "allowEmptyValue": true, "description": "Regulatory jurisdiction the request routes to (e.g. `UAE`, `KSA`, `MAIN`). Match it to the market you're integrating.", "examples": { "KSA": { "value": "KSA" }, "UAE": { "value": "UAE" } }, "explode": true, "in": "header", "name": "x-tenant", "required": true, "schema": { "type": "string" }, "style": "simple" } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "keys": { "items": { "$ref": "#/components/schemas/JsonWebKey" }, "type": "array" } }, "required": [ "keys" ], "type": "object" } } }, "description": "Success response", "headers": { "cache-control": { "allowEmptyValue": true, "description": "HTTP cache directive for relying parties.", "explode": true, "required": true, "schema": { "type": "string" }, "style": "simple" }, "vary": { "allowEmptyValue": true, "description": "Vary header, instructs shared caches to key on X-Tenant. Prevents cross-tenant cache poisoning when public caching is used.", "explode": true, "required": true, "schema": { "type": "string" }, "style": "simple" } } }, "400": { "description": "Bad request. The request was invalid or failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Unauthorized, the access token is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "The token doesn't have access to this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Not found, the requested resource does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Too many requests. Retry after a short wait.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Something went wrong on our side. Try again shortly.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "The bank or provider is temporarily unavailable. Retry later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "$ref": "#/components/responses/APIError" } }, "summary": "Returns the signing public keys for a specific Open Banking provider.", "tags": [ "auth" ], "x-fern-sdk-group-name": "auth", "x-fern-sdk-method-name": "getProviderJwks" } }, "/auth/api-keys/sessions": { "post": { "description": "Validates the application identifier and API key, enforces IP whitelist policy, verifies application and client status, and issues a signed JWT with role-derived audience scopes.\n\nPOST /auth/api-keys/sessions", "operationId": "auth_authenticate", "parameters": [ { "allowEmptyValue": true, "description": "Regulatory jurisdiction the request routes to (e.g. `UAE`, `KSA`, `MAIN`). Match it to the market you're integrating.", "examples": { "KSA": { "value": "KSA" }, "UAE": { "value": "UAE" } }, "explode": true, "in": "header", "name": "x-tenant", "required": true, "schema": { "type": "string" }, "style": "simple" }, { "allowEmptyValue": true, "description": "Your application's App ID, from the developer dashboard.", "explode": true, "in": "header", "name": "app-id", "required": true, "schema": { "type": "string" }, "style": "simple" }, { "allowEmptyValue": true, "description": "Your application's API key, from the developer dashboard.", "explode": true, "in": "header", "name": "x-api-key", "required": true, "schema": { "type": "string" }, "style": "simple" } ], "responses": { "200": { "content": { "application/json": { "examples": { "authenticated": { "summary": "API key authenticated; token ready for subsequent requests.", "value": { "data": { "accessToken": "", "expiresIn": 3600, "tokenType": "Bearer" } } } }, "schema": { "properties": { "access_token": { "type": "string", "description": "Bearer access token for subsequent API requests." }, "expires_in": { "type": "number", "description": "Access token lifetime in seconds." }, "refresh_expires_in": { "type": "number", "description": "Refresh token lifetime in seconds." }, "refresh_token": { "type": "string", "description": "Refresh token for renewing the session." }, "type": { "enum": [ "Bearer" ], "title": "OAuth token type; always `Bearer` for this flow.", "type": "string", "description": "Variant selector, determines which other fields are required." } }, "required": [ "access_token", "type", "refresh_token", "expires_in", "refresh_expires_in" ], "type": "object" } } }, "description": "Success response" }, "400": { "description": "Bad request. The request was invalid or failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Unauthorized, the access token is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "The token doesn't have access to this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Conflict, the request conflicts with the current state of the resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Too many requests. Retry after a short wait.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Something went wrong on our side. Try again shortly.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "The bank or provider is temporarily unavailable. Retry later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "$ref": "#/components/responses/APIError" } }, "summary": "Authenticate an application using its API key credentials.", "tags": [ "auth" ], "x-fern-sdk-group-name": "auth", "x-fern-sdk-method-name": "authenticate" } }, "/auth/api-keys/sessions/refresh": { "post": { "description": "Verifies the refresh JWT, re-checks IP whitelist and application status, then mints a new access JWT and a new refresh JWT (refresh-token rotation on every successful call).\n\nPOST /auth/api-keys/sessions/refresh", "operationId": "auth_refreshSession", "parameters": [ { "allowEmptyValue": true, "description": "Regulatory jurisdiction the request routes to (e.g. `UAE`, `KSA`, `MAIN`). Match it to the market you're integrating.", "examples": { "KSA": { "value": "KSA" }, "UAE": { "value": "UAE" } }, "explode": true, "in": "header", "name": "x-tenant", "required": true, "schema": { "type": "string" }, "style": "simple" }, { "allowEmptyValue": true, "description": "The refresh token issued with your access token, used to renew the session.", "explode": true, "in": "header", "name": "refresh-token", "schema": { "type": "string" }, "style": "simple" } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "access_token": { "type": "string", "description": "Bearer access token for subsequent API requests." }, "expires_in": { "type": "number", "description": "Access token lifetime in seconds." }, "refresh_expires_in": { "type": "number", "description": "Refresh token lifetime in seconds." }, "refresh_token": { "type": "string", "description": "Refresh token for renewing the session." }, "type": { "enum": [ "Bearer" ], "title": "OAuth token type; always `Bearer` for this flow.", "type": "string", "description": "Variant selector, determines which other fields are required." } }, "required": [ "access_token", "type", "refresh_token", "expires_in", "refresh_expires_in" ], "type": "object" } } }, "description": "Success response" }, "400": { "description": "Bad request. The request was invalid or failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Unauthorized, the access token is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "The token doesn't have access to this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Conflict, the request conflicts with the current state of the resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Too many requests. Retry after a short wait.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Something went wrong on our side. Try again shortly.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "The bank or provider is temporarily unavailable. Retry later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "$ref": "#/components/responses/APIError" } }, "summary": "Refresh an existing API key session using the Spare-issued PS512 refresh JWT.", "tags": [ "auth" ], "x-fern-sdk-group-name": "auth", "x-fern-sdk-method-name": "refreshSession" } }, "/consent/payment/{consentId}": { "get": { "operationId": "paymentConsents_get", "parameters": [ { "allowEmptyValue": true, "explode": false, "in": "path", "name": "consentId", "required": true, "schema": { "type": "string" }, "style": "simple", "description": "UUID of the consent (returned when the consent was created)." }, { "allowEmptyValue": true, "examples": { "KSA": { "value": "KSA" }, "UAE": { "value": "UAE" } }, "explode": true, "in": "header", "name": "x-tenant", "required": true, "schema": { "type": "string" }, "style": "simple", "description": "Regulatory jurisdiction the request routes to (e.g. `UAE`, `KSA`, `MAIN`). Match it to the market you're integrating." } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/DomesticPaymentConsentResponse" }, "error": { "nullable": true, "type": "string" }, "errorDescription": { "additionalProperties": { "items": { "type": "string" }, "type": "array" }, "nullable": true, "type": "object" } }, "type": "object" } } }, "description": "Success response" }, "400": { "description": "Bad request. The request was invalid or failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Unauthorized, the access token is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "The token doesn't have access to this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Not found, the requested resource does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Too many requests. Retry after a short wait.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Something went wrong on our side. Try again shortly.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "The bank or provider is temporarily unavailable. Retry later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "$ref": "#/components/responses/APIError" } }, "summary": "Payment Consents Get", "tags": [ "paymentConsents" ], "x-fern-sdk-group-name": "paymentConsents", "x-fern-sdk-method-name": "get", "security": [ { "BearerAuth": [] } ] } }, "/consent/payment/list": { "get": { "operationId": "paymentConsents_list", "parameters": [ { "allowEmptyValue": true, "examples": { "KSA": { "value": "KSA" }, "UAE": { "value": "UAE" } }, "explode": true, "in": "header", "name": "x-tenant", "required": true, "schema": { "type": "string" }, "style": "simple", "description": "Regulatory jurisdiction the request routes to (e.g. `UAE`, `KSA`, `MAIN`). Match it to the market you're integrating." }, { "allowEmptyValue": true, "explode": true, "in": "query", "name": "page", "schema": { "type": "number" }, "style": "form", "description": "1-based page number for paginated results. Defaults to the first page." }, { "allowEmptyValue": true, "explode": true, "in": "query", "name": "perPage", "schema": { "type": "number" }, "style": "form", "description": "Number of items to return per page. Defaults to the API's page size." }, { "allowEmptyValue": true, "explode": true, "in": "query", "name": "providerId", "schema": { "type": "string" }, "style": "form", "description": "Spare provider UUID to filter results by." }, { "allowEmptyValue": true, "explode": true, "in": "query", "name": "connectionId", "schema": { "type": "string" }, "style": "form", "description": "UUID of the account/consent connection to filter by." }, { "allowEmptyValue": true, "explode": true, "in": "query", "name": "externalReference", "schema": { "type": "string" }, "style": "form", "description": "Filter results by your own reference set when the resource was created." } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "items": { "$ref": "#/components/schemas/DomesticPaymentConsentResponse" }, "type": "array" }, "error": { "nullable": true, "type": "string" }, "errorDescription": { "additionalProperties": { "items": { "type": "string" }, "type": "array" }, "nullable": true, "type": "object" }, "meta": { "$ref": "#/components/schemas/Pages" } }, "type": "object" } } }, "description": "Success response" }, "400": { "description": "Bad request. The request was invalid or failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Unauthorized, the access token is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "The token doesn't have access to this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Too many requests. Retry after a short wait.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Something went wrong on our side. Try again shortly.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "The bank or provider is temporarily unavailable. Retry later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "$ref": "#/components/responses/APIError" } }, "summary": "Payment Consents List", "tags": [ "paymentConsents" ], "x-fern-sdk-group-name": "paymentConsents", "x-fern-sdk-method-name": "list", "security": [ { "BearerAuth": [] } ] } }, "/consent/payment/sync": { "get": { "operationId": "paymentConsents_sync", "parameters": [ { "allowEmptyValue": true, "examples": { "KSA": { "value": "KSA" }, "UAE": { "value": "UAE" } }, "explode": true, "in": "header", "name": "x-tenant", "required": true, "schema": { "type": "string" }, "style": "simple", "description": "Regulatory jurisdiction the request routes to (e.g. `UAE`, `KSA`, `MAIN`). Match it to the market you're integrating." }, { "allowEmptyValue": true, "explode": true, "in": "query", "name": "paymentRequestId", "schema": { "type": "string" }, "style": "form", "description": "UUID of the payment request." } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/SyncConsentDetailsResponse" }, "error": { "nullable": true, "type": "string" }, "errorDescription": { "additionalProperties": { "items": { "type": "string" }, "type": "array" }, "nullable": true, "type": "object" } }, "type": "object" } } }, "description": "Success response" }, "400": { "description": "Bad request. The request was invalid or failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Unauthorized, the access token is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "The token doesn't have access to this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Too many requests. Retry after a short wait.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Something went wrong on our side. Try again shortly.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "The bank or provider is temporarily unavailable. Retry later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "$ref": "#/components/responses/APIError" } }, "summary": "Payment Consents Sync", "tags": [ "paymentConsents" ], "x-fern-sdk-group-name": "paymentConsents", "x-fern-sdk-method-name": "sync", "security": [ { "BearerAuth": [] } ] } }, "/consent/payment/update/{consentId}": { "patch": { "operationId": "paymentConsents_update", "parameters": [ { "allowEmptyValue": true, "explode": false, "in": "path", "name": "consentId", "required": true, "schema": { "type": "string" }, "style": "simple", "description": "UUID of the consent (returned when the consent was created)." }, { "allowEmptyValue": true, "examples": { "KSA": { "value": "KSA" }, "UAE": { "value": "UAE" } }, "explode": true, "in": "header", "name": "x-tenant", "required": true, "schema": { "type": "string" }, "style": "simple", "description": "Regulatory jurisdiction the request routes to (e.g. `UAE`, `KSA`, `MAIN`). Match it to the market you're integrating." } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "status": { "type": "string", "description": "Current status of the resource." } }, "required": [ "status" ], "type": "object" } } } }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/DomesticPaymentConsentResponse" }, "error": { "nullable": true, "type": "string" }, "errorDescription": { "additionalProperties": { "items": { "type": "string" }, "type": "array" }, "nullable": true, "type": "object" } }, "type": "object" } } }, "description": "Success response" }, "400": { "description": "Bad request. The request was invalid or failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Unauthorized, the access token is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "The token doesn't have access to this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Not found, the requested resource does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Conflict, the request conflicts with the current state of the resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Too many requests. Retry after a short wait.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Something went wrong on our side. Try again shortly.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "The bank or provider is temporarily unavailable. Retry later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "$ref": "#/components/responses/APIError" } }, "summary": "Payment Consents Update", "tags": [ "paymentConsents" ], "x-fern-sdk-group-name": "paymentConsents", "x-fern-sdk-method-name": "update", "security": [ { "BearerAuth": [] } ] } }, "/link/exchange": { "post": { "description": "POST /link/exchange\n\n\n\n\nErrors: invalid/expired code → 400/401; already consumed → 403; session not completed → 400; app\\_id mismatch → 403; AIS/KSA/BH → 501.", "operationId": "link_exchange", "parameters": [ { "allowEmptyValue": true, "examples": { "KSA": { "value": "KSA" }, "UAE": { "value": "UAE" } }, "explode": true, "in": "header", "name": "x-tenant", "required": true, "schema": { "type": "string" }, "style": "simple", "description": "Regulatory jurisdiction the request routes to (e.g. `UAE`, `KSA`, `MAIN`). Match it to the market you're integrating." } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "exchange_code": { "type": "string", "description": "One-time public token from Spare Link. Exchange server-side within ~5 minutes." } }, "required": [ "exchange_code" ], "type": "object" } } } }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/LinkExchangeResponseData" }, "error": { "nullable": true, "type": "string" }, "errorDescription": { "additionalProperties": { "items": { "type": "string" }, "type": "array" }, "nullable": true, "type": "object" } }, "type": "object" } } }, "description": "Success response" }, "400": { "description": "Bad request. The request was invalid or failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Unauthorized, the access token is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "The token doesn't have access to this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Conflict, the request conflicts with the current state of the resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Too many requests. Retry after a short wait.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Something went wrong on our side. Try again shortly.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "The bank or provider is temporarily unavailable. Retry later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "$ref": "#/components/responses/APIError" } }, "summary": "Exchange a one-time `exchange_code` for durable PIS identifiers.", "tags": [ "link" ], "x-fern-sdk-group-name": "link", "x-fern-sdk-method-name": "exchange" } }, "/link/token/payment": { "post": { "description": "POST /link/token/payment", "operationId": "link_createPaymentToken", "parameters": [ { "allowEmptyValue": true, "examples": { "KSA": { "value": "KSA" }, "UAE": { "value": "UAE" } }, "explode": true, "in": "header", "name": "x-tenant", "required": true, "schema": { "type": "string" }, "style": "simple", "description": "Regulatory jurisdiction the request routes to (e.g. `UAE`, `KSA`, `MAIN`). Match it to the market you're integrating." }, { "allowEmptyValue": true, "explode": true, "in": "header", "name": "x-signature", "required": true, "schema": { "type": "string" }, "style": "simple", "description": "HMAC signature of the request payload, required on endpoints that mandate request signing." } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "provider_code": { "type": "string", "description": "Bank provider code from the providers list. Optional, pre-selects the payer bank in Spare Link." }, "provider_id": { "type": "string", "description": "Spare provider UUID. Optional, use with provider_code to skip bank selection." }, "request": { "$ref": "#/components/schemas/CreatePaymentRequestInput" }, "user_ref": { "type": "string", "description": "Your opaque reference for the payer or session (for correlation in logs and support)." } }, "required": [ "request" ], "type": "object" } } } }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/CreateLinkPaymentTokenResponseData" }, "error": { "nullable": true, "type": "string" }, "errorDescription": { "additionalProperties": { "items": { "type": "string" }, "type": "array" }, "nullable": true, "type": "object" } }, "type": "object" } } }, "description": "Success response" }, "400": { "description": "Bad request. The request was invalid or failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Unauthorized, the access token is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "The token doesn't have access to this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Conflict, the request conflicts with the current state of the resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Too many requests. Retry after a short wait.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Something went wrong on our side. Try again shortly.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "The bank or provider is temporarily unavailable. Retry later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "$ref": "#/components/responses/APIError" } }, "tags": [ "link" ], "x-fern-sdk-group-name": "link", "x-fern-sdk-method-name": "createPaymentToken" } }, "/mandate/{mandateId}/transactions": { "get": { "operationId": "mandates_listTransactions", "parameters": [ { "allowEmptyValue": true, "explode": false, "in": "path", "name": "mandateId", "required": true, "schema": { "pattern": "^(?!approve$|schedule$).+", "type": "string" }, "style": "simple", "description": "UUID of the mandate." }, { "allowEmptyValue": true, "examples": { "KSA": { "value": "KSA" }, "UAE": { "value": "UAE" } }, "explode": true, "in": "header", "name": "x-tenant", "required": true, "schema": { "type": "string" }, "style": "simple", "description": "Regulatory jurisdiction the request routes to (e.g. `UAE`, `KSA`, `MAIN`). Match it to the market you're integrating." } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "items": { "$ref": "#/components/schemas/MandateTransactionResponse" }, "type": "array" }, "error": { "nullable": true, "type": "string" }, "errorDescription": { "additionalProperties": { "items": { "type": "string" }, "type": "array" }, "nullable": true, "type": "object" } }, "type": "object" } } }, "description": "Success response" }, "400": { "description": "Bad request. The request was invalid or failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Unauthorized, the access token is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "The token doesn't have access to this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Not found, the requested resource does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Too many requests. Retry after a short wait.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Something went wrong on our side. Try again shortly.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "The bank or provider is temporarily unavailable. Retry later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "$ref": "#/components/responses/APIError" } }, "summary": "Mandates List Transactions", "tags": [ "mandates" ], "x-fern-sdk-group-name": "mandates", "x-fern-sdk-method-name": "listTransactions", "security": [ { "BearerAuth": [] } ] } }, "/mandate/approve": { "patch": { "operationId": "mandates_approve", "parameters": [ { "allowEmptyValue": true, "explode": true, "in": "header", "name": "x-signature", "required": true, "schema": { "type": "string" }, "style": "simple", "description": "HMAC signature of the request payload, required on endpoints that mandate request signing." }, { "allowEmptyValue": true, "examples": { "KSA": { "value": "KSA" }, "UAE": { "value": "UAE" } }, "explode": true, "in": "header", "name": "x-tenant", "required": true, "schema": { "type": "string" }, "style": "simple", "description": "Regulatory jurisdiction the request routes to (e.g. `UAE`, `KSA`, `MAIN`). Match it to the market you're integrating." } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "amount": { "type": "number", "description": "Monetary amount. Where paired with a currency, given as a decimal string (e.g. `250.00`)." }, "executionDate": { "type": "string", "description": "ISO 8601 date the payment should execute." }, "mandateId": { "type": "string", "description": "UUID of the mandate this payment draws against." }, "transactionId": { "type": "string", "description": "Identifier of the transaction." } }, "required": [ "mandateId", "transactionId" ], "type": "object" } } } }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/MandateTransactionResponse" }, "error": { "nullable": true, "type": "string" }, "errorDescription": { "additionalProperties": { "items": { "type": "string" }, "type": "array" }, "nullable": true, "type": "object" } }, "type": "object" } } }, "description": "Success response" }, "400": { "description": "Bad request. The request was invalid or failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Unauthorized, the access token is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "The token doesn't have access to this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Conflict, the request conflicts with the current state of the resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Too many requests. Retry after a short wait.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Something went wrong on our side. Try again shortly.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "The bank or provider is temporarily unavailable. Retry later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "$ref": "#/components/responses/APIError" } }, "summary": "Mandates Approve", "tags": [ "mandates" ], "x-fern-sdk-group-name": "mandates", "x-fern-sdk-method-name": "approve", "security": [ { "BearerAuth": [] } ] } }, "/mandate/schedule": { "post": { "operationId": "mandates_schedule", "parameters": [ { "allowEmptyValue": true, "explode": true, "in": "header", "name": "x-signature", "required": true, "schema": { "type": "string" }, "style": "simple", "description": "HMAC signature of the request payload, required on endpoints that mandate request signing." }, { "allowEmptyValue": true, "examples": { "KSA": { "value": "KSA" }, "UAE": { "value": "UAE" } }, "explode": true, "in": "header", "name": "x-tenant", "required": true, "schema": { "type": "string" }, "style": "simple", "description": "Regulatory jurisdiction the request routes to (e.g. `UAE`, `KSA`, `MAIN`). Match it to the market you're integrating." } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "amount": { "type": "number", "description": "Monetary amount. Where paired with a currency, given as a decimal string (e.g. `250.00`)." }, "executionDate": { "type": "string", "description": "ISO 8601 date the payment should execute." }, "mandateId": { "type": "string", "description": "UUID of the mandate this payment draws against." } }, "required": [ "mandateId", "executionDate" ], "type": "object" } } } }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/MandateTransactionResponse" }, "error": { "nullable": true, "type": "string" }, "errorDescription": { "additionalProperties": { "items": { "type": "string" }, "type": "array" }, "nullable": true, "type": "object" } }, "type": "object" } } }, "description": "Success response" }, "400": { "description": "Bad request. The request was invalid or failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Unauthorized, the access token is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "The token doesn't have access to this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Conflict, the request conflicts with the current state of the resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Too many requests. Retry after a short wait.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Something went wrong on our side. Try again shortly.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "The bank or provider is temporarily unavailable. Retry later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "$ref": "#/components/responses/APIError" } }, "summary": "Mandates Schedule", "tags": [ "mandates" ], "x-fern-sdk-group-name": "mandates", "x-fern-sdk-method-name": "schedule", "security": [ { "BearerAuth": [] } ] } }, "/payment-purpose-codes": { "get": { "operationId": "paymentPurposeCodes_list", "parameters": [ { "allowEmptyValue": true, "examples": { "KSA": { "value": "KSA" }, "UAE": { "value": "UAE" } }, "explode": true, "in": "header", "name": "x-tenant", "required": true, "schema": { "type": "string" }, "style": "simple", "description": "Regulatory jurisdiction the request routes to (e.g. `UAE`, `KSA`, `MAIN`). Match it to the market you're integrating." }, { "allowEmptyValue": true, "explode": true, "in": "query", "name": "isDomestic", "schema": { "type": "boolean" }, "style": "form", "description": "When true, filter to domestic payments only." }, { "allowEmptyValue": true, "explode": true, "in": "query", "name": "isInternational", "schema": { "type": "boolean" }, "style": "form", "description": "When true, filter to international payments only." } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "items": { "$ref": "#/components/schemas/PurposeCode" }, "type": "array" }, "error": { "nullable": true, "type": "string" }, "errorDescription": { "additionalProperties": { "items": { "type": "string" }, "type": "array" }, "nullable": true, "type": "object" } }, "type": "object" } } }, "description": "Success response" }, "400": { "description": "Bad request. The request was invalid or failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Unauthorized, the access token is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "The token doesn't have access to this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Too many requests. Retry after a short wait.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Something went wrong on our side. Try again shortly.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "The bank or provider is temporarily unavailable. Retry later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "$ref": "#/components/responses/APIError" } }, "summary": "Payment Purpose Codes List", "tags": [ "paymentPurposeCodes" ], "x-fern-sdk-group-name": "paymentPurposeCodes", "x-fern-sdk-method-name": "list", "security": [ { "BearerAuth": [] } ] } }, "/payment-requests": { "get": { "operationId": "paymentRequests_list", "parameters": [ { "allowEmptyValue": true, "examples": { "KSA": { "value": "KSA" }, "UAE": { "value": "UAE" } }, "explode": true, "in": "header", "name": "x-tenant", "required": true, "schema": { "type": "string" }, "style": "simple", "description": "Regulatory jurisdiction the request routes to (e.g. `UAE`, `KSA`, `MAIN`). Match it to the market you're integrating." }, { "allowEmptyValue": true, "explode": true, "in": "query", "name": "page", "schema": { "type": "number" }, "style": "form", "description": "1-based page number for paginated results. Defaults to the first page." }, { "allowEmptyValue": true, "explode": true, "in": "query", "name": "perPage", "schema": { "type": "number" }, "style": "form", "description": "Number of items to return per page. Defaults to the API's page size." }, { "allowEmptyValue": true, "description": "Filter results by the merchant reference you set when the resource was created.", "explode": true, "in": "query", "name": "merchantReference", "schema": { "type": "string" }, "style": "form" } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "items": { "$ref": "#/components/schemas/InitiatePaymentRequestResponse" }, "type": "array" }, "error": { "nullable": true, "type": "string" }, "errorDescription": { "additionalProperties": { "items": { "type": "string" }, "type": "array" }, "nullable": true, "type": "object" }, "meta": { "$ref": "#/components/schemas/Pages" } }, "type": "object" } } }, "description": "Success response" }, "400": { "description": "Bad request. The request was invalid or failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Unauthorized, the access token is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "The token doesn't have access to this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Too many requests. Retry after a short wait.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Something went wrong on our side. Try again shortly.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "The bank or provider is temporarily unavailable. Retry later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "$ref": "#/components/responses/APIError" } }, "summary": "Payment Requests List", "tags": [ "paymentRequests" ], "x-fern-sdk-group-name": "paymentRequests", "x-fern-sdk-method-name": "list", "security": [ { "BearerAuth": [] } ] }, "post": { "operationId": "paymentRequests_create", "parameters": [ { "allowEmptyValue": true, "explode": true, "in": "header", "name": "x-signature", "required": true, "schema": { "type": "string" }, "style": "simple", "description": "HMAC signature of the request payload, required on endpoints that mandate request signing." }, { "allowEmptyValue": true, "examples": { "KSA": { "value": "KSA" }, "UAE": { "value": "UAE" } }, "explode": true, "in": "header", "name": "x-tenant", "required": true, "schema": { "type": "string" }, "style": "simple", "description": "Regulatory jurisdiction the request routes to (e.g. `UAE`, `KSA`, `MAIN`). Match it to the market you're integrating." } ], "requestBody": { "content": { "application/json": { "example": { "amount": "125.50", "beneficiaryIban": "AE070331234567890123456", "beneficiaryName": "Acme Supplier LLC", "currency": "AED", "reference": "INV-10042" }, "schema": { "properties": { "consentPermissions": { "items": { "type": "string" }, "type": "array", "description": "Data permissions the consent grants (e.g. read balances, read transactions)." }, "creditorAccount": { "properties": { "identification": { "type": "string", "description": "Account identifier, its format is given by the accompanying scheme (e.g. an IBAN)." }, "name": { "type": "string", "description": "Name associated with this object, e.g. the account holder or party name." }, "schemeName": { "type": "string", "description": "Identification scheme for the account (e.g. IBAN)." } }, "required": [ "schemeName", "identification" ], "type": "object", "description": "The payee (creditor) account that receives the funds." }, "creditorReference": { "type": "string", "description": "Your reference for the creditor/payee, echoed back for reconciliation." }, "creditorType": { "type": "string", "description": "Type of creditor (e.g. `MERCHANT`)." }, "debtorAccount": { "properties": { "identification": { "type": "string", "description": "Account identifier, its format is given by the accompanying scheme (e.g. an IBAN)." }, "name": { "type": "string", "description": "Name associated with this object, e.g. the account holder or party name." }, "schemeName": { "type": "string", "description": "Identification scheme for the account (e.g. IBAN)." } }, "required": [ "schemeName", "identification" ], "type": "object", "description": "The payer (debtor) account the funds are collected from." }, "debtorReference": { "type": "string", "description": "Your reference for the debtor/payer." }, "failureRedirectUrl": { "type": "string", "description": "URL to redirect the payer to after a failed or cancelled authorization." }, "instructions": { "$ref": "#/components/schemas/PaymentInstructionsUAE" }, "merchantReference": { "type": "string", "description": "Your merchant reference for this transaction, echoed back for reconciliation." }, "purpose": { "type": "string", "description": "Payment purpose code, see the [payment purpose codes](/docs/api-reference/payment-purpose-codes) reference." }, "risks": { "$ref": "#/components/schemas/PaymentRisks", "description": "Risk metadata for the payment (e.g. delivery address, merchant category)." }, "successRedirectUrl": { "type": "string", "description": "URL to redirect the payer to after a successful authorization." }, "type": { "type": "string", "description": "Variant selector, determines which other fields are required." } }, "required": [ "type", "creditorType", "purpose", "merchantReference", "creditorAccount", "instructions" ], "type": "object" } } } }, "responses": { "200": { "content": { "application/json": { "examples": { "created": { "summary": "Payment request created successfully.", "value": { "data": { "amount": "125.50", "currency": "AED", "internalReferenceId": "req_01hqnx2w", "status": "New" } } } }, "schema": { "properties": { "data": { "$ref": "#/components/schemas/InitiatePaymentRequestResponse" }, "error": { "nullable": true, "type": "string" }, "errorDescription": { "additionalProperties": { "items": { "type": "string" }, "type": "array" }, "nullable": true, "type": "object" } }, "type": "object" } } }, "description": "Success response" }, "400": { "description": "Bad request. The request was invalid or failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Unauthorized, the access token is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "The token doesn't have access to this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Conflict, the request conflicts with the current state of the resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Too many requests. Retry after a short wait.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Something went wrong on our side. Try again shortly.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "The bank or provider is temporarily unavailable. Retry later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "$ref": "#/components/responses/APIError" } }, "summary": "Payment Requests Create", "tags": [ "paymentRequests" ], "x-fern-sdk-group-name": "paymentRequests", "x-fern-sdk-method-name": "create", "security": [ { "BearerAuth": [] } ] } }, "/payment-requests/{paymentRequestId}": { "delete": { "operationId": "paymentRequests_delete", "parameters": [ { "allowEmptyValue": true, "explode": false, "in": "path", "name": "paymentRequestId", "required": true, "schema": { "type": "string" }, "style": "simple", "description": "UUID of the payment request." }, { "allowEmptyValue": true, "examples": { "KSA": { "value": "KSA" }, "UAE": { "value": "UAE" } }, "explode": true, "in": "header", "name": "x-tenant", "required": true, "schema": { "type": "string" }, "style": "simple", "description": "Regulatory jurisdiction the request routes to (e.g. `UAE`, `KSA`, `MAIN`). Match it to the market you're integrating." } ], "responses": { "200": { "description": "Success response" }, "400": { "description": "Bad request. The request was invalid or failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Unauthorized, the access token is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "The token doesn't have access to this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Not found, the requested resource does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Conflict, the request conflicts with the current state of the resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Too many requests. Retry after a short wait.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Something went wrong on our side. Try again shortly.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "The bank or provider is temporarily unavailable. Retry later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "$ref": "#/components/responses/APIError" } }, "summary": "Payment Requests Delete", "tags": [ "paymentRequests" ], "x-fern-sdk-group-name": "paymentRequests", "x-fern-sdk-method-name": "delete", "security": [ { "BearerAuth": [] } ] }, "get": { "operationId": "paymentRequests_get", "parameters": [ { "allowEmptyValue": true, "explode": false, "in": "path", "name": "paymentRequestId", "required": true, "schema": { "type": "string" }, "style": "simple", "description": "UUID of the payment request." }, { "allowEmptyValue": true, "examples": { "KSA": { "value": "KSA" }, "UAE": { "value": "UAE" } }, "explode": true, "in": "header", "name": "x-tenant", "required": true, "schema": { "type": "string" }, "style": "simple", "description": "Regulatory jurisdiction the request routes to (e.g. `UAE`, `KSA`, `MAIN`). Match it to the market you're integrating." } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/InitiatePaymentRequestResponse" }, "error": { "nullable": true, "type": "string" }, "errorDescription": { "additionalProperties": { "items": { "type": "string" }, "type": "array" }, "nullable": true, "type": "object" } }, "type": "object" } } }, "description": "Success response" }, "400": { "description": "Bad request. The request was invalid or failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Unauthorized, the access token is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "The token doesn't have access to this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Not found, the requested resource does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Too many requests. Retry after a short wait.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Something went wrong on our side. Try again shortly.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "The bank or provider is temporarily unavailable. Retry later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "$ref": "#/components/responses/APIError" } }, "summary": "Payment Requests Get", "tags": [ "paymentRequests" ], "x-fern-sdk-group-name": "paymentRequests", "x-fern-sdk-method-name": "get", "security": [ { "BearerAuth": [] } ] } }, "/payment/bank-account": { "get": { "operationId": "bankAccounts_list", "parameters": [ { "allowEmptyValue": true, "examples": { "KSA": { "value": "KSA" }, "UAE": { "value": "UAE" } }, "explode": true, "in": "header", "name": "x-tenant", "required": true, "schema": { "type": "string" }, "style": "simple", "description": "Regulatory jurisdiction the request routes to (e.g. `UAE`, `KSA`, `MAIN`). Match it to the market you're integrating." }, { "allowEmptyValue": true, "explode": true, "in": "query", "name": "page", "schema": { "type": "number" }, "style": "form", "description": "1-based page number for paginated results. Defaults to the first page." }, { "allowEmptyValue": true, "explode": true, "in": "query", "name": "perPage", "schema": { "type": "number" }, "style": "form", "description": "Number of items to return per page. Defaults to the API's page size." } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "items": { "$ref": "#/components/schemas/BankAccount" }, "type": "array" }, "error": { "nullable": true, "type": "string" }, "errorDescription": { "additionalProperties": { "items": { "type": "string" }, "type": "array" }, "nullable": true, "type": "object" }, "meta": { "$ref": "#/components/schemas/Pages" } }, "type": "object" } } }, "description": "Success response" }, "400": { "description": "Bad request. The request was invalid or failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Unauthorized, the access token is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "The token doesn't have access to this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Too many requests. Retry after a short wait.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Something went wrong on our side. Try again shortly.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "The bank or provider is temporarily unavailable. Retry later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "$ref": "#/components/responses/APIError" } }, "summary": "Bank Accounts List", "tags": [ "bankAccounts" ], "x-fern-sdk-group-name": "bankAccounts", "x-fern-sdk-method-name": "list", "security": [ { "BearerAuth": [] } ] }, "post": { "operationId": "bankAccounts_create", "parameters": [ { "allowEmptyValue": true, "examples": { "KSA": { "value": "KSA" }, "UAE": { "value": "UAE" } }, "explode": true, "in": "header", "name": "x-tenant", "required": true, "schema": { "type": "string" }, "style": "simple", "description": "Regulatory jurisdiction the request routes to (e.g. `UAE`, `KSA`, `MAIN`). Match it to the market you're integrating." } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "accountDetails": { "properties": { "identificationNumber": { "type": "string", "description": "Identification number, formatted per the accompanying scheme." }, "scheme": { "type": "string", "description": "Identification scheme for the value (e.g. IBAN, national ID)." }, "subType": { "type": "string", "description": "Sub-type refining the parent type." }, "type": { "type": "string", "description": "Variant selector, determines which other fields are required." } }, "required": [ "identificationNumber" ], "type": "object", "description": "Details of the account." }, "accountHolderDetails": { "properties": { "name": { "type": "string", "description": "Name associated with this object, e.g. the account holder or party name." }, "tradingName": { "type": "string", "description": "Trading (business) name." } }, "required": [ "name" ], "type": "object", "description": "Details about the account holder." }, "bankDetails": { "properties": { "identificationNumber": { "type": "string", "description": "Identification number, formatted per the accompanying scheme." }, "name": { "type": "string", "description": "Name associated with this object, e.g. the account holder or party name." }, "scheme": { "type": "string", "description": "Identification scheme for the value (e.g. IBAN, national ID)." } }, "required": [ "name" ], "type": "object", "description": "Details of the bank." }, "name": { "type": "string", "description": "Name associated with this object, e.g. the account holder or party name." }, "type": { "type": "string", "description": "Variant selector, determines which other fields are required." } }, "required": [ "accountDetails", "accountHolderDetails" ], "type": "object" } } } }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/BankAccount" }, "error": { "nullable": true, "type": "string" }, "errorDescription": { "additionalProperties": { "items": { "type": "string" }, "type": "array" }, "nullable": true, "type": "object" } }, "type": "object" } } }, "description": "Success response" }, "400": { "description": "Bad request. The request was invalid or failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Unauthorized, the access token is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "The token doesn't have access to this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Conflict, the request conflicts with the current state of the resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Too many requests. Retry after a short wait.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Something went wrong on our side. Try again shortly.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "The bank or provider is temporarily unavailable. Retry later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "$ref": "#/components/responses/APIError" } }, "summary": "Bank Accounts Create", "tags": [ "bankAccounts" ], "x-fern-sdk-group-name": "bankAccounts", "x-fern-sdk-method-name": "create", "security": [ { "BearerAuth": [] } ] } }, "/payment/bank-account/{bankAccountId}": { "delete": { "operationId": "bankAccounts_delete", "parameters": [ { "allowEmptyValue": true, "explode": false, "in": "path", "name": "bankAccountId", "required": true, "schema": { "type": "string" }, "style": "simple", "description": "UUID of the bank account (from the bank accounts list)." }, { "allowEmptyValue": true, "examples": { "KSA": { "value": "KSA" }, "UAE": { "value": "UAE" } }, "explode": true, "in": "header", "name": "x-tenant", "required": true, "schema": { "type": "string" }, "style": "simple", "description": "Regulatory jurisdiction the request routes to (e.g. `UAE`, `KSA`, `MAIN`). Match it to the market you're integrating." } ], "responses": { "200": { "description": "Success response" }, "400": { "description": "Bad request. The request was invalid or failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Unauthorized, the access token is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "The token doesn't have access to this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Not found, the requested resource does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Conflict, the request conflicts with the current state of the resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Too many requests. Retry after a short wait.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Something went wrong on our side. Try again shortly.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "The bank or provider is temporarily unavailable. Retry later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "$ref": "#/components/responses/APIError" } }, "summary": "Bank Accounts Delete", "tags": [ "bankAccounts" ], "x-fern-sdk-group-name": "bankAccounts", "x-fern-sdk-method-name": "delete", "security": [ { "BearerAuth": [] } ] }, "get": { "operationId": "bankAccounts_get", "parameters": [ { "allowEmptyValue": true, "explode": false, "in": "path", "name": "bankAccountId", "required": true, "schema": { "type": "string" }, "style": "simple", "description": "UUID of the bank account (from the bank accounts list)." }, { "allowEmptyValue": true, "examples": { "KSA": { "value": "KSA" }, "UAE": { "value": "UAE" } }, "explode": true, "in": "header", "name": "x-tenant", "required": true, "schema": { "type": "string" }, "style": "simple", "description": "Regulatory jurisdiction the request routes to (e.g. `UAE`, `KSA`, `MAIN`). Match it to the market you're integrating." } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/BankAccount" }, "error": { "nullable": true, "type": "string" }, "errorDescription": { "additionalProperties": { "items": { "type": "string" }, "type": "array" }, "nullable": true, "type": "object" } }, "type": "object" } } }, "description": "Success response" }, "400": { "description": "Bad request. The request was invalid or failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Unauthorized, the access token is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "The token doesn't have access to this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Not found, the requested resource does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Too many requests. Retry after a short wait.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Something went wrong on our side. Try again shortly.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "The bank or provider is temporarily unavailable. Retry later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "$ref": "#/components/responses/APIError" } }, "summary": "Bank Accounts Get", "tags": [ "bankAccounts" ], "x-fern-sdk-group-name": "bankAccounts", "x-fern-sdk-method-name": "get", "security": [ { "BearerAuth": [] } ] } }, "/payment/bank-account/default": { "get": { "operationId": "bankAccounts_getDefault", "parameters": [ { "allowEmptyValue": true, "examples": { "KSA": { "value": "KSA" }, "UAE": { "value": "UAE" } }, "explode": true, "in": "header", "name": "x-tenant", "required": true, "schema": { "type": "string" }, "style": "simple", "description": "Regulatory jurisdiction the request routes to (e.g. `UAE`, `KSA`, `MAIN`). Match it to the market you're integrating." } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/BankAccount" }, "error": { "nullable": true, "type": "string" }, "errorDescription": { "additionalProperties": { "items": { "type": "string" }, "type": "array" }, "nullable": true, "type": "object" } }, "type": "object" } } }, "description": "Success response" }, "400": { "description": "Bad request. The request was invalid or failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Unauthorized, the access token is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "The token doesn't have access to this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Too many requests. Retry after a short wait.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Something went wrong on our side. Try again shortly.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "The bank or provider is temporarily unavailable. Retry later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "$ref": "#/components/responses/APIError" } }, "summary": "Bank Accounts Get Default", "tags": [ "bankAccounts" ], "x-fern-sdk-group-name": "bankAccounts", "x-fern-sdk-method-name": "getDefault", "security": [ { "BearerAuth": [] } ] }, "put": { "operationId": "bankAccounts_setDefault", "parameters": [ { "allowEmptyValue": true, "examples": { "KSA": { "value": "KSA" }, "UAE": { "value": "UAE" } }, "explode": true, "in": "header", "name": "x-tenant", "required": true, "schema": { "type": "string" }, "style": "simple", "description": "Regulatory jurisdiction the request routes to (e.g. `UAE`, `KSA`, `MAIN`). Match it to the market you're integrating." }, { "allowEmptyValue": true, "explode": true, "in": "query", "name": "id", "schema": { "type": "string" }, "style": "form", "description": "Resource identifier to filter by." }, { "allowEmptyValue": true, "explode": true, "in": "query", "name": "isDefault", "schema": { "type": "boolean" }, "style": "form", "description": "When true, return only the default bank account." } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/UaePaymentAccount" }, "error": { "nullable": true, "type": "string" }, "errorDescription": { "additionalProperties": { "items": { "type": "string" }, "type": "array" }, "nullable": true, "type": "object" } }, "type": "object" } } }, "description": "Success response" }, "400": { "description": "Bad request. The request was invalid or failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Unauthorized, the access token is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "The token doesn't have access to this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Conflict, the request conflicts with the current state of the resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Too many requests. Retry after a short wait.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Something went wrong on our side. Try again shortly.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "The bank or provider is temporarily unavailable. Retry later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "$ref": "#/components/responses/APIError" } }, "summary": "Bank Accounts Set Default", "tags": [ "bankAccounts" ], "x-fern-sdk-group-name": "bankAccounts", "x-fern-sdk-method-name": "setDefault", "security": [ { "BearerAuth": [] } ] } }, "/payments": { "get": { "operationId": "payments_list", "parameters": [ { "allowEmptyValue": true, "examples": { "KSA": { "value": "KSA" }, "UAE": { "value": "UAE" } }, "explode": true, "in": "header", "name": "x-tenant", "required": true, "schema": { "type": "string" }, "style": "simple", "description": "Regulatory jurisdiction the request routes to (e.g. `UAE`, `KSA`, `MAIN`). Match it to the market you're integrating." }, { "allowEmptyValue": true, "explode": true, "in": "query", "name": "page", "schema": { "type": "number" }, "style": "form", "description": "1-based page number for paginated results. Defaults to the first page." }, { "allowEmptyValue": true, "explode": true, "in": "query", "name": "perPage", "schema": { "type": "number" }, "style": "form", "description": "Number of items to return per page. Defaults to the API's page size." }, { "allowEmptyValue": true, "explode": true, "in": "query", "name": "externalReference", "schema": { "type": "string" }, "style": "form", "description": "Filter results by your own reference set when the resource was created." } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "items": { "$ref": "#/components/schemas/PaymentRequest" }, "type": "array" }, "error": { "nullable": true, "type": "string" }, "errorDescription": { "additionalProperties": { "items": { "type": "string" }, "type": "array" }, "nullable": true, "type": "object" }, "meta": { "$ref": "#/components/schemas/Pages" } }, "type": "object" } } }, "description": "Success response" }, "400": { "description": "Bad request. The request was invalid or failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Unauthorized, the access token is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "The token doesn't have access to this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Too many requests. Retry after a short wait.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Something went wrong on our side. Try again shortly.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "The bank or provider is temporarily unavailable. Retry later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "$ref": "#/components/responses/APIError" } }, "summary": "Payments List", "tags": [ "payments" ], "x-fern-sdk-group-name": "payments", "x-fern-sdk-method-name": "list", "security": [ { "BearerAuth": [] } ] } }, "/payments/{paymentId}": { "get": { "operationId": "payments_get", "parameters": [ { "allowEmptyValue": true, "explode": false, "in": "path", "name": "paymentId", "required": true, "schema": { "type": "string" }, "style": "simple", "description": "UUID of the payment." }, { "allowEmptyValue": true, "examples": { "KSA": { "value": "KSA" }, "UAE": { "value": "UAE" } }, "explode": true, "in": "header", "name": "x-tenant", "required": true, "schema": { "type": "string" }, "style": "simple", "description": "Regulatory jurisdiction the request routes to (e.g. `UAE`, `KSA`, `MAIN`). Match it to the market you're integrating." } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/PaymentEnvelope" }, "error": { "nullable": true, "type": "string" }, "errorDescription": { "additionalProperties": { "items": { "type": "string" }, "type": "array" }, "nullable": true, "type": "object" } }, "type": "object" } } }, "description": "Success response" }, "400": { "description": "Bad request. The request was invalid or failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Unauthorized, the access token is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "The token doesn't have access to this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Not found, the requested resource does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Too many requests. Retry after a short wait.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Something went wrong on our side. Try again shortly.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "The bank or provider is temporarily unavailable. Retry later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "$ref": "#/components/responses/APIError" } }, "summary": "Payments Get", "tags": [ "payments" ], "x-fern-sdk-group-name": "payments", "x-fern-sdk-method-name": "get", "security": [ { "BearerAuth": [] } ] } }, "/providers": { "get": { "description": "GET /providers?countryCode=AE", "operationId": "providers_list", "parameters": [ { "allowEmptyValue": true, "examples": { "KSA": { "value": "KSA" }, "UAE": { "value": "UAE" } }, "explode": true, "in": "header", "name": "x-tenant", "required": true, "schema": { "type": "string" }, "style": "simple", "description": "Regulatory jurisdiction the request routes to (e.g. `UAE`, `KSA`, `MAIN`). Match it to the market you're integrating." }, { "allowEmptyValue": true, "explode": true, "in": "query", "name": "countryCode", "schema": { "type": "string" }, "style": "form", "description": "ISO country code to filter results (e.g. `AE`, `SA`, `BH`)." } ], "responses": { "200": { "content": { "application/json": { "examples": { "sandboxProviders": { "summary": "Available open-banking providers for UAE tenant.", "value": { "data": [ { "country": "UAE", "id": "adcb", "name": "ADCB" }, { "country": "UAE", "id": "fab", "name": "FAB" } ] } } }, "schema": { "properties": { "data": { "items": { "$ref": "#/components/schemas/ProviderListItem" }, "type": "array" }, "error": { "nullable": true, "type": "string" }, "errorDescription": { "additionalProperties": { "items": { "type": "string" }, "type": "array" }, "nullable": true, "type": "object" } }, "type": "object" } } }, "description": "Success response" }, "400": { "description": "Bad request. The request was invalid or failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Unauthorized, the access token is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "The token doesn't have access to this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Too many requests. Retry after a short wait.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Something went wrong on our side. Try again shortly.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "The bank or provider is temporarily unavailable. Retry later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "$ref": "#/components/responses/APIError" } }, "summary": "List PIS providers for a given country code.", "tags": [ "providers" ], "x-fern-sdk-group-name": "providers", "x-fern-sdk-method-name": "list", "security": [ { "BearerAuth": [] } ] } }, "/verifications/beneficiary": { "post": { "operationId": "verifications_verifyBeneficiary", "parameters": [ { "allowEmptyValue": true, "examples": { "KSA": { "value": "KSA" }, "UAE": { "value": "UAE" } }, "explode": true, "in": "header", "name": "x-tenant", "required": true, "schema": { "type": "string" }, "style": "simple", "description": "Regulatory jurisdiction the request routes to (e.g. `UAE`, `KSA`, `MAIN`). Match it to the market you're integrating." } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "beneficiaryName": { "type": "string" }, "iban": { "type": "string" }, "swiftCode": { "title": "Beneficiary BIC/SWIFT code. Reserved for international beneficiaries.", "type": "string" } }, "required": [ "iban" ], "type": "object" } } } }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/BeneficiaryVerificationResponse" }, "error": { "nullable": true, "type": "string" }, "errorDescription": { "additionalProperties": { "items": { "type": "string" }, "type": "array" }, "nullable": true, "type": "object" } }, "type": "object" } } }, "description": "Success response" }, "400": { "description": "Bad request. The request was invalid or failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Unauthorized, the access token is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "The token doesn't have access to this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Conflict, the request conflicts with the current state of the resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Too many requests. Retry after a short wait.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Something went wrong on our side. Try again shortly.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "The bank or provider is temporarily unavailable. Retry later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "default": { "$ref": "#/components/responses/APIError" } }, "summary": "Verifications Verify Beneficiary", "tags": [ "verifications" ], "x-fern-sdk-group-name": "verifications", "x-fern-sdk-method-name": "verifyBeneficiary", "security": [ { "BearerAuth": [] } ] } } }, "servers": [ { "description": "Sandbox", "url": "https://api.sandbox.tryspare.ae" }, { "description": "Production", "url": "https://api.tryspare.ae" } ] }