openapi: 3.0.3 info: title: BelMoney Incoming — Generated version: 1.0.0 description: Generated OpenAPI spec for the BelMoney Incoming remittance API, built incrementally from tested payloads during cube_0 batch discovery. servers: - url: https://apps.belmoneylabs.org/WebAPI-UAT/RemittanceTransfers description: UAT / Sandbox (Finastra Fusion Phoenix) security: - APIAuth: [] components: securitySchemes: APIAuth: type: apiKey in: header name: Authorization description: 'Format: `APIAuth ` where token = Base64(APIKey:Timestamp:Base64(HMAC-SHA512(Timestamp, APISecret)))' schemas: ApiError: type: object description: Single error inside the soft-error envelope. Returned with HTTP 200 alongside HasErrors=true. properties: Message: type: string description: Human-readable error message; wording is not stable, pin behavior on ErrorCode. ErrorCode: type: string description: Stable business error code (TRPRxxx, TRFRxxx, SNDRxxx). Full reference in bestAndUse.error_codes_reference. MethodNotAllowed: type: object properties: Message: type: string example: The requested resource does not support http method 'GET'. description: Server message indicating the HTTP verb is not supported. description: 405 envelope returned when a non-POST verb is used on an Incoming endpoint. IncomingBalanceResponse: type: object required: - Balance - HasErrors properties: Balance: type: number format: double description: Current available settlement balance, in the agency's settlement currency. Errors: type: array nullable: true items: $ref: '#/components/schemas/ApiError' description: Populated when HasErrors=true. HasErrors: type: boolean description: Soft-error flag — failures return HTTP 200, always check this. description: Response of GetAvailableBalance — current settlement balance for the authenticated agency. IncomingPayersResponse: type: object required: - HasErrors properties: Results: type: array items: $ref: '#/components/schemas/IncomingPayerItem' description: Array of payers; null when HasErrors=true or none configured. Errors: type: array nullable: true items: $ref: '#/components/schemas/ApiError' description: Populated when HasErrors=true. HasErrors: type: boolean description: Soft-error flag — failures return HTTP 200, always check this. description: Response of PayersList — payers visible to the authenticated agency. IncomingPayerItem: type: object properties: PayerID: type: integer format: int32 description: Unique payer identifier; passed to PayerNetworkList and as PayerID in RateRFQ. PayerName: type: string description: Payer institution full name. Address1: type: string nullable: true description: Payer headquarters primary address. Address2: type: string nullable: true description: Payer headquarters secondary address. CityName: type: string nullable: true description: Payer headquarters city. StateCode: type: string nullable: true description: Payer headquarters state/region code. CountryCode: type: string nullable: true description: ISO 3166-1 alpha-2 country code where the payer is headquartered. PhoneNumber: type: string nullable: true description: Payer contact phone. OperatingCountries: type: array items: $ref: '#/components/schemas/IncomingOperatingCountryItem' description: Countries this payer can deliver into. description: One payer institution available to the calling agency. IncomingOperatingCountryItem: type: object properties: CountryCode: type: string description: ISO 3166-1 alpha-2 destination country code. CurrencyCodes: type: array items: type: string description: Currencies the payer can settle in for this country. description: Country a payer is configured to deliver into. IncomingBanksListRequest: type: object properties: CountryCode: type: string description: ISO 3166-1 alpha-2 destination country to list banks for. description: BanksList request body — pin destination country before listing banks. IncomingBanksResponse: type: object required: - HasErrors properties: Results: type: array items: $ref: '#/components/schemas/IncomingBankItem' description: Array of banks; empty when CountryCode is missing/unknown (returns 200 with empty array). Errors: type: array nullable: true items: $ref: '#/components/schemas/ApiError' description: Populated when HasErrors=true. HasErrors: type: boolean description: Soft-error flag — failures return HTTP 200, always check this. description: Response of BanksList for the requested destination country. IncomingBankItem: type: object properties: BankCode: type: string description: Bank identifier in the destination country's directory; used as Payment.BankAccount.Code. BankName: type: string description: Bank display name. PartnerCode: type: string nullable: true description: Optional partner-side bank code echoed for reconciliation. BankBranches: type: array items: $ref: '#/components/schemas/IncomingBankBranchItem' description: Bank branches under this bank. description: Bank entry returned by BanksList for a given destination country. IncomingBankBranchItem: type: object properties: BranchCode: type: string description: Branch identifier within the bank (sort code, agency number). BranchName: type: string description: Branch display name. description: Branch under a bank in BanksList results. IncomingPayerNetworkRequest: type: object required: - PayerID properties: PayerID: type: integer format: int32 description: Unique payer identifier from PayersList. description: PayerNetworkList request — pin a payer to retrieve its branch network. IncomingPayerNetworkResponse: type: object required: - HasErrors properties: Results: type: array nullable: true items: $ref: '#/components/schemas/IncomingPayerBranchItem' description: Array of branches; null when HasErrors=true. Errors: type: array nullable: true items: $ref: '#/components/schemas/ApiError' description: Populated when HasErrors=true. HasErrors: type: boolean description: Soft-error flag — failures return HTTP 200, always check this. description: Response of PayerNetworkList — branch network for the requested payer. IncomingPayerBranchItem: type: object properties: PayerBranchID: type: integer format: int32 description: Branch identifier; passed as Payment.PayerBranchReference on PreRegister. PayerBranchCode: type: string nullable: true description: Caller-side branch code; informational, routing uses PayerBranchID. PayerBranchName: type: string description: Branch display name. Address1: type: string nullable: true description: Branch primary address line. Address2: type: string nullable: true description: Branch secondary address line. CityName: type: string nullable: true description: Branch city. StateCode: type: string nullable: true description: Branch state/region code. CountryCode: type: string description: ISO 3166-1 alpha-2 country code where the branch operates. PhoneNumber: type: string nullable: true description: Branch contact phone. PayAllCities: type: boolean description: True when the branch can pay across the whole destination country. HasLocations: type: boolean description: True when the branch publishes specific LocationPoints. ValidateBank: type: boolean description: True when ValidateAccount is required before PreRegister. ValidateBankBranch: type: boolean description: True when bank-branch routing must be pre-validated. ReadOnlyBankName: type: boolean description: True when caller-supplied bank name is ignored (server uses directory). ReadOnlyBranchName: type: boolean description: True when caller-supplied branch name is ignored. PaymentTypes: type: array items: type: integer description: Payout methods this branch supports (PaymentTypeID values). Currencies: type: array items: type: string description: Currencies the branch settles in (drives PaymentCurrencyCode). Banks: type: array items: $ref: '#/components/schemas/IncomingPayerBranchBankRef' description: Bank routing references the branch can deposit to. LocationPoints: type: array items: $ref: '#/components/schemas/IncomingPayerBranchLocationPoint' description: Specific payout locations for cash-pickup-style flows. description: Payer branch — a routing endpoint inside a payer's network. IncomingPayerBranchBankRef: type: object properties: BankCode: type: string description: Bank identifier; matches Payment.BankAccount.Code on deposit flows. PartnerCode: type: string nullable: true description: Optional partner-side bank code echoed for reconciliation. description: Bank-routing reference attached to a payer branch. IncomingPayerBranchLocationPoint: type: object properties: LocationPointID: type: integer format: int32 description: Unique location identifier; passed as Payment.LocationCode. Description: type: string nullable: true description: Location display name. Details: type: string nullable: true description: Free-text directions or notes about the location. LocationPointCode: type: string nullable: true description: Caller-side code for the location, when published. Region: type: string nullable: true description: Region/area the location serves. Days: type: string nullable: true description: Operating days, free-text. Hours: type: string nullable: true description: Operating hours, free-text. TransferMinAmount: type: number nullable: true description: Minimum transfer amount accepted at this location. TransferMaxAmount: type: number nullable: true description: Maximum transfer amount accepted at this location. DailyMaxAmount: type: number nullable: true description: Daily cap on transfers per beneficiary at this location. description: Specific payout location available under a branch (used for cash-pickup-style flows). IncomingRatesAndFeesResponse: type: object required: - HasErrors properties: Results: type: array items: $ref: '#/components/schemas/IncomingAgencyRateAndFeeItem' description: Array of pricing rows; null when HasErrors=true. Errors: type: array nullable: true items: $ref: '#/components/schemas/ApiError' description: Populated when HasErrors=true. HasErrors: type: boolean description: Soft-error flag — failures return HTTP 200, always check this. description: Response of RatesAndFeesList — full pricing matrix for the agency. IncomingAgencyRateAndFeeItem: type: object description: Single pricing row from RatesAndFeesList — corridor + amount-band + fee components. properties: CountryCode: type: string description: ISO 3166-1 alpha-2 destination country code for this pricing row. CountryName: type: string description: Destination country display name. PayerID: type: integer format: int32 description: Payer this pricing row belongs to. PayerName: type: string description: Payer institution display name. PayerBranchID: type: integer format: int32 description: Branch this pricing row applies to. PayerBranchName: type: string description: Branch display name. CurrencyCode: type: string description: Currency code this row applies to (alias context for FromCurrencyCode/ToCurrencyCode). CurrencyTypeName: type: string description: Currency-type label (e.g. settlement vs payout). PaymentTypeID: type: integer format: int32 description: Payout method this row prices. PaymentTypeName: type: string description: Payout-method display name (matches PaymentTypeID). FromAmount: type: number format: double description: Lower bound of the amount band (inclusive). ToAmount: type: number format: double description: Upper bound of the amount band (inclusive). PercentageFee: type: number format: double description: Percent fee for the band. FlatFee: type: number format: double description: Flat fee component for this band. RateTypeID: type: integer format: int32 description: Rate-program identifier. 1=Standard, 2=Express Service, 3=Rate 3, 4=Rate 4, 5=Rate 5, 6=Rate 6, 7=Rate 7, 8=Rate 8, 9=Rate 9, 10=Rate 10. RateTypeDescription: type: string description: Display label for the rate type. Rate: type: number format: double description: Customer-facing exchange rate for this band. FromCurrencyCode: type: string description: Sender currency this row applies to. IncomingStatusesRequest: type: array description: JSON array of Reference strings to look up. Empty arrays return HTTP 406. Unknown references are silently dropped (Results=null). items: type: string IncomingStatusesResponse: type: object required: - HasErrors properties: Results: type: array nullable: true items: $ref: '#/components/schemas/TransferStatusItem' description: Array of (Reference, StatusID, HoldReasonIDs, ...) entries; null when none returned. Errors: type: array nullable: true items: $ref: '#/components/schemas/ApiError' description: Populated when HasErrors=true. HasErrors: type: boolean description: Soft-error flag — failures return HTTP 200, always check this. description: Response of Statuses — current StatusID per Reference. Unknown References silently dropped. IncomingPreRegisterTransferRequest: type: object description: PreRegister creates a transfer in StatusID=1 (Created); Confirm advances it. Idempotent on Reference. required: - Reference - Sender - Beneficiary - AmountAndFees - Payment properties: Reference: type: string description: Caller-supplied unique transfer identifier; resubmits return TRPR006. TransferID: type: string description: MUST be empty on create — server generates the real value. TransferPIN: type: string description: MUST be empty on create — server returns the PIN with the response. TransConfirmation: type: string description: Optional caller-supplied confirmation token; echoed back. TransferReasonID: type: integer format: int32 description: Reason for the remittance. 1=Remit to Business, 2=Remit to Family, 3=Other, 5=Savings, 7=Bills, 9=Buy Property, 11=Church Donation, 15=Pay Vacations, 17=School Payment, 23=Pay Wedding, 25=Remit to Friend, 27=Pay Credit Card, 29=Pay Debt, 35=Gift. Sender: $ref: '#/components/schemas/SenderModel' Beneficiary: $ref: '#/components/schemas/BeneficiaryModel' AmountAndFees: $ref: '#/components/schemas/AmountAndFeesModel' Payment: $ref: '#/components/schemas/PaymentModel' TransferPayment: $ref: '#/components/schemas/TransferPaymentModel' description: Optional. Normally supplied later via Confirm. Notes: type: array description: Free-text notes attached at creation; visible later via Notes endpoint. items: type: string CreationDate: type: string format: date-time description: Optional caller-supplied creation timestamp. IncomingCreateTransferRequest: allOf: - $ref: '#/components/schemas/IncomingPreRegisterTransferRequest' description: Same shape as PreRegister — alternative single-call create path. IncomingCreateOrPreRegisterResponse: type: object description: Response of PreRegister/Create. Always inspect HasErrors — soft errors return HTTP 200 with null TransferID. required: - HasErrors properties: Reference: type: string nullable: true description: Echo of caller-supplied Reference. TransferID: type: string nullable: true description: Server-generated unique transfer identifier; use for all subsequent lifecycle calls. TransferPIN: type: string nullable: true description: Server-generated verification code paired with TransferID; required on Confirm. StatusID: type: integer format: int32 description: Lifecycle state of the new transfer; 1 (Created) on success, 0 if call failed pre-create. 1=Created, 2=Hold, 3=Done (To Pay), 4=Transmitted To Payee, 5=Updated, 6=Void, 7=Paid, 8=Cancel, 9=Repair, 11=Processing Payment, 20=Refunded. Errors: type: array nullable: true description: Populated when HasErrors=true. items: $ref: '#/components/schemas/ApiError' HasErrors: type: boolean description: Soft-error flag — failures return HTTP 200, always check this. SenderModel: type: object description: Sender (originator) KYC data. Field-level validation rules and error codes in bestAndUse.error_codes_reference. required: - FirstName - LastName - Address1 - CountryCode - StateName - CityName - IDs properties: AgencyReference: type: string description: Caller's internal sender ID; echoed back, not used for matching. FirstName: type: string description: Given name. MiddleName: type: string description: Middle name. LastName: type: string description: Family name. SecondLastName: type: string description: Maternal / second family name (markets that record two surnames). Address1: type: string description: Primary residential street address. CountryCode: type: string description: ISO 3166-1 alpha-2 country code of residence. StateName: type: string description: State / province / region of residence. StateCode: type: string description: State/province code. Conflicts with StateName at validation (SNDR058) — send StateName only on PreRegister/Create. CityName: type: string description: City of residence. PhoneNumber: type: string description: Sender contact phone. PhoneNumberCountryCode: type: string description: International dial prefix (no leading '+'). PrimaryPhoneNumber: type: string description: Preferred contact number; chosen over PhoneNumber/CellPhoneNumber when present. BirthCountryCode: type: string description: ISO 3166-1 alpha-2 country code of birth. Sex: type: string enum: - M - F description: Biological sex marker as recorded on government ID. CitizenshipCountryCode: type: string description: Citizenship country (ISO 3166-1 alpha-3). ProfessionID: type: integer format: int32 description: Profession enum. 61=Agriculture/Agri-food, 62=Architect/Engineer, 63=Arms/Defence, 64=Artist/craftspeople, 65=Arts & Antiques Trader, 66=Assistant nurse/Childcare, 67=Bank/Insurance, 68=Business administration, 69=Cars dealers/garage, 70=Civil servants/Public service, 71=Cleaning sector, 72=Commercial Admin Officer, 73=Construction industry, 74=Diplomatic/consular staff, 75=Factory worker, 76=Freight transport, 77=Gambling establishment, 78=Gym/fitness, 79=Healthcare professional, 80=Hotel/restaurant/cafe sectors, 81=ICT, 82=International civil servants, 83=Jewelry/Diamond/Precious metals, 84=Judges/prosecutor, 85=Legal professions, 86=Merchant/Retail, 87=Military, 88=Mining/extractive, 89=Pensioner/retiree, 90=Pharmaceutical/Chemical, 91=Political parties, 92=Private security, 93=Sportsman, 94=Real estate, 95=Religious occupations, 96=Taxi Driver, 97=Teacher/instructor, 98=Tobacco and alcohol industry. SenderTypeID: type: integer format: int32 description: 0=Corporate, 1=Individual, 2=Company. PEPTypeID: type: integer format: int32 description: 1=PEP, 2=No PEP. IDs: type: array description: Sender identification documents; at least one required. items: $ref: '#/components/schemas/SenderIDModel' CellPhoneNumber: type: string description: Mobile phone number. CityCode: type: string description: Optional internal city code in addition to CityName. ZipCode: type: string description: Postal / ZIP code. Email: type: string description: Sender email address. BirthCityName: type: string description: City of birth. DOB: type: string format: date-time description: Date of birth. Documents: type: array description: Inline KYC documents; usually attached post-create via AddSenderDocuments. items: $ref: '#/components/schemas/SenderDocumentModel' BeneficiaryModel: type: object description: Beneficiary (recipient) data. Conditional fields per PaymentTypeID in bestAndUse.flows. required: - FirstName - LastName - CountryCode properties: FirstName: type: string description: Given name as it appears on the beneficiary's bank account / ID. MiddleName: type: string description: Middle name. LastName: type: string description: Family name. SecondLastName: type: string description: Maternal / second family name. Address1: type: string description: Primary residential street address. CityName: type: string description: City of residence. CountryCode: type: string description: ISO 3166-1 alpha-2 country code; must be served by the chosen branch. PhoneNumber: type: string description: Beneficiary contact phone (required for some payout methods). RelationshipToSenderID: type: integer format: int32 description: Relationship to sender. 1=Father, 2=Mother, 3=Siblings, 4=Son/Daughter, 5=Husband/Wife, 6=Cousin, 7=Uncle/Aunt, 8=Grandparent, 9=Friend, 10=Other, 11=Brother/Sister-in-law, 12=Father/Mother-in-law, 13=Nephew/Niece, 14=Own, 15=Ex-Husband/Wife, 16=Grandchild, 17=Son/Daughter-in-law, 18=Business Partner. AgencyReference: type: string description: Caller's internal beneficiary ID; echoed back, not used for matching. CityCode: type: string description: Optional internal city code in addition to CityName. StateCode: type: string description: Optional internal state code in addition to StateName. ZipCode: type: string description: Postal / ZIP code. CellPhoneNumber: type: string description: Mobile phone number. PrimaryPhoneNumber: type: string description: Preferred contact number; picked over PhoneNumber/CellPhoneNumber when present. Email: type: string description: Beneficiary email address. IDs: type: array description: Beneficiary identification documents (optional on most corridors). items: $ref: '#/components/schemas/BeneficiaryIDModel' AmountAndFeesModel: type: object description: Money block — amounts, currencies, rate, fee components. Pricing-row keying rules in bestAndUse.rates_and_fees. required: - PaymentAmount - OriginalAmount - Rate - RateID - PayerCurrencyCode - PaymentCurrencyCode properties: PaymentAmount: type: number format: double description: Amount the beneficiary receives, in PaymentCurrencyCode (= OriginalAmount × Rate). OriginalAmount: type: number format: double description: Amount the sender pays, in PayerCurrencyCode. Rate: type: number format: double description: Exchange rate applied; should match the rate from RateRFQ. RateID: type: integer format: int32 description: Rate-program identifier; usually 1 (Standard) unless multi-program agency. 1=Standard, 2=Express Service, 3=Rate 3, 4=Rate 4, 5=Rate 5, 6=Rate 6, 7=Rate 7, 8=Rate 8, 9=Rate 9, 10=Rate 10. PayerCurrencyCode: type: string description: Currency the sender pays in. PaymentCurrencyCode: type: string description: Currency the beneficiary receives. TokenId: type: string description: From a prior RateRFQ — locks the quoted rate. PercentFee: type: string description: Percent-of-amount fee component (decimal string, e.g. '1.5' = 1.5%). FlatFee: type: string description: Fixed fee component charged regardless of amount. OtherFee: type: string description: Additional ad-hoc fee component. Tax: type: string description: Tax on the principal, in PayerCurrencyCode. FeesTax: type: string description: Tax on the fees (separate from Tax on principal). Discount: type: string description: Promotional / loyalty discount applied to fees. PayerFlatFee: type: string description: Flat fee charged by the payer (destination side). PayerPercentFee: type: string description: Percent fee charged by the payer (destination side). PayerRate: type: string description: Payer-side internal exchange rate for settlement. BankRate: type: string description: Reference / mid-market rate; informational, not used for customer calc. PaymentModel: type: object description: Payout method + routing branch. Conditional sub-objects per PaymentTypeID in bestAndUse.flows. required: - PayerBranchReference - PaymentTypeID properties: PayerBranchReference: type: integer format: int32 description: PayerBranchID from PayerNetworkList; determines corridor + pricing row. PaymentTypeID: type: integer format: int32 description: Payout method (HOW the beneficiary is paid). 1=Account Deposit, 2=Office Pick-Up, 3=Bank Pick-Up, 4=Home Delivery, 5=Card Top Up, 6=Wallet Top Up, 7=Pix, 8=ATM Withdraw. BankAccount: $ref: '#/components/schemas/PaymentBankAccount' LocationCode: type: string description: Optional. Specific payout location ID for branches with multiple LocationPoints. PayerBranchCode: type: string description: Optional partner-side branch code; informational only. PaymentBankAccount: type: object description: Beneficiary bank account on Payment. Required for Account Deposit and Pix; conditional for Bank Pick-Up. properties: AccountNo: type: string description: Account number / IBAN. For Pix this is the Pix key. AccountType: type: integer format: int32 description: AccountTypeID enum. 0=Select Bank Account Type, 1=Checking, 2=Savings, 3=Business Checking, 4=Business Savings, 5=Other. BranchName: type: string description: Bank branch name; informational, routing uses Code + AccountNo. Code: type: string description: Bank identifier from PayerNetworkList → Banks[].BankCode for the chosen branch. Name: type: string description: Bank name; routing uses Code, not Name. BranchCode: type: string description: Bank-branch identifier within the bank; required by some corridors. IncomingAddSenderDocumentsRequest: type: object required: - TransferID - Documents properties: TransferID: type: string description: TransferID returned by PreRegister; missing/invalid triggers HTTP 500 leak. Documents: type: array items: $ref: '#/components/schemas/SenderDocumentModel' description: Array of documents to attach. Reference: type: string description: Optional caller Reference for cross-check. description: Attach KYC documents to an existing transfer (typically post-PreRegister, pre-Confirm). SenderDocumentModel: type: object properties: TypeID: type: integer format: int32 description: DocumentTypeID enum. 1=General, 2=Identification, 3=Proof of Address, 4=Compliance, 5=KYC Form, 6=Receipt, 7=Customer Signature, 8=Proof Of Funds, 9=Proof Of Profession, 10=Selfie, 11=KYC Form – Enhanced. DocumentData: type: string format: byte description: Base64-encoded document content (PDF / image). Description: type: string description: Free-text description of the document. IDNo: type: string description: ID number associated with the document, when applicable. IssuedDate: type: string format: date-time description: Date the document was issued. ExpirationDate: type: string format: date-time description: Document expiration date. IssuedCountryCode: type: string description: ISO 3166-1 alpha-2 country code of the issuing authority. description: Single KYC document attachment. IncomingAddSenderDocumentsResponse: type: object required: - HasErrors properties: TransferID: type: string nullable: true description: Echo of the TransferID; null on errors. Errors: type: array nullable: true items: $ref: '#/components/schemas/ApiError' description: Populated when HasErrors=true. HasErrors: type: boolean description: Soft-error flag — failures return HTTP 200, always check this. description: Response of AddSenderDocuments. SenderVideoSelfieModel: type: object required: - TransferID - VideoData properties: TransferID: type: string description: TransferID returned by PreRegister. VideoData: type: string format: byte description: Base64-encoded video bytes. Reference: type: string description: Optional caller Reference for cross-check. description: Selfie video attachment for sender KYC. IncomingAddSenderSelfieVideoResponse: type: object required: - HasErrors properties: TransferID: type: string nullable: true description: Echo of the TransferID; null on errors. Errors: type: array nullable: true items: $ref: '#/components/schemas/ApiError' description: Populated when HasErrors=true. HasErrors: type: boolean description: Soft-error flag — failures return HTTP 200, always check this. description: Response of AddSenderSelfieVideo. IncomingConfirmTransferRequest: type: object required: - Reference - TransferPayment properties: Reference: type: string description: Caller-supplied Reference of the transfer to confirm. TransferPayment: $ref: '#/components/schemas/TransferPaymentModel' description: Confirm advances a Created (StatusID=1) transfer to Hold (2) and into the lifecycle. Requires PSP authorization. TransferPaymentModel: type: object properties: PaymentTypeID: type: integer format: int32 description: TransferPaymentTypeID enum (HOW the sender paid the PSP). 0=Cash, 1=Check, 2=Money Order, 3=Credit Card, 4=Bank Deposit, 5=Direct Debit, 8=Bancontact, 9=Pay later, 10=Boleto AL, 11=Boleto PP-AL, 12=Cash AN, 13=Prepaid Card BT. PaymentConfirmationCode: type: string description: Auth code from the PSP (NOT the WL partner Reference). PaymentProcessorCode: type: string description: Identifier for the PSP (e.g. 'STRIPE'). PaymentProcessorFullResponse: type: string description: Raw JSON response from the PSP for audit. description: How the SENDER paid the PSP — distinct from Payment.PaymentTypeID (how beneficiary is paid). IncomingConfirmTransferResponse: type: object required: - HasErrors properties: Reference: type: string nullable: true description: Echo of caller-supplied Reference. TransferID: type: string nullable: true description: TransferID of the confirmed transfer. TransferPIN: type: string nullable: true description: Verification code for the transfer. StatusID: type: integer format: int32 description: New lifecycle state; typically 2 (Hold) on success. 1=Created, 2=Hold, 3=Done (To Pay), 4=Transmitted To Payee, 5=Updated, 6=Void, 7=Paid, 8=Cancel, 9=Repair, 11=Processing Payment, 20=Refunded. Errors: type: array nullable: true items: $ref: '#/components/schemas/ApiError' description: Populated when HasErrors=true. HasErrors: type: boolean description: Soft-error flag — failures return HTTP 200, always check this. description: Response of Confirm; HasErrors=false means the transfer advanced into the lifecycle. IncomingRepairTransferRequest: type: object required: - Reference - Beneficiary properties: Reference: type: string description: Reference of the transfer to repair. Beneficiary: $ref: '#/components/schemas/RepairBeneficiaryInfo' Note: type: string description: Optional free-text note explaining the repair. description: Repair updates the beneficiary on a transfer in StatusID=9 (Repair). Beneficiary subobject required to avoid HTTP 500. RepairBeneficiaryInfo: type: object description: Beneficiary fields that can be updated during Repair. properties: FirstName: type: string description: Updated given name. MiddleName: type: string description: Updated middle name. LastName: type: string description: Updated family name. SecondLastName: type: string description: Updated maternal / second family name. Address: type: string description: Updated address (alias of Address1). PhoneNumber: type: string description: Updated phone number. PhoneCountryCode: type: string description: Updated international dial prefix. AccountNo: type: string description: Updated account number / IBAN. IncomingRepairTransferResponse: type: object required: - HasErrors properties: Reference: type: string nullable: true description: Echo of caller-supplied Reference. Errors: type: array nullable: true items: $ref: '#/components/schemas/ApiError' description: Populated when HasErrors=true. HasErrors: type: boolean description: Soft-error flag — failures return HTTP 200, always check this. description: Response of Repair. ServerError: type: object properties: Message: type: string example: An error has occurred. description: ASP.NET exception message string. ExceptionMessage: type: string description: Detailed exception text (e.g. NullReferenceException trace). ExceptionType: type: string description: Fully-qualified .NET exception type name. StackTrace: type: string description: Server stack trace; informational only. description: ASP.NET HTTP 500 envelope leaked when a required subobject is missing on Repair / AddSenderDocuments / AddSenderSelfieVideo. IncomingRequestCancelTransferRequest: type: object required: - Reference properties: Reference: type: string description: Caller-supplied Reference of the transfer to cancel. ReasonID: type: integer format: int32 description: Cancel reason. 1=Wrong Account No, 2=Wrong Agency, 3=Wrong Bank, 4=Incorrect Beneficiary Name, 5=Wrong Address, 6=Wrong Telephone No, 7=Missing ID, 8=Canceled or Suspended ID, 9=Invalid ID, 10=Others. Note: type: string description: Optional free-text note explaining the cancellation. description: Request cancellation of an existing transfer by Reference. IncomingRequestCancelTransferResponse: type: object required: - HasErrors properties: Reference: type: string nullable: true description: Echo of caller-supplied Reference. Errors: type: array nullable: true items: $ref: '#/components/schemas/ApiError' description: Populated when HasErrors=true. HasErrors: type: boolean description: Soft-error flag — failures return HTTP 200, always check this. description: Response of RequestCancel. RateRFQ: type: object required: - Amount - RateID properties: Amount: type: number format: double description: Quote amount in the currency selected by AmountType. AmountType: type: integer format: int32 enum: - 1 - 2 - 3 description: 1=Amount in sender currency; 2=Amount in beneficiary currency. SenderCurrencyCode: type: string description: Sender currency for the quote. BeneficiaryCurrencyCode: type: string description: Beneficiary currency for the quote. BeneficiaryCountryCode: type: string description: ISO 3166-1 alpha-2 destination country. PayerID: type: integer format: int32 description: Payer institution to quote against. PayerBranchID: type: integer format: int32 description: Branch to quote against. PaymentTypeID: type: integer format: int32 description: Payout method. 1=Account Deposit, 2=Office Pick-Up, 3=Bank Pick-Up, 4=Home Delivery, 5=Card Top Up, 6=Wallet Top Up, 7=Pix, 8=ATM Withdraw. RateID: type: integer format: int32 description: Rate program identifier; usually 1 unless multi-program agency. description: RateRFQ request — quote a rate + fee for one corridor and amount. IncomingRateRFQResponse: type: object required: - HasErrors properties: Rate: type: number format: double description: Quoted exchange rate (PaymentCurrency per PayerCurrency). Fee: type: number format: double description: Quoted total fee in sender currency. TokenId: type: string nullable: true description: Quote-lock token; pass as AmountAndFees.TokenId on PreRegister to honor this quote. Expiration: type: string format: date-time nullable: true description: When the quote expires; resubmit RateRFQ after this. WarningMessages: type: string nullable: true description: Non-blocking warnings the quote engine surfaced. Errors: type: array nullable: true items: $ref: '#/components/schemas/ApiError' description: Populated when HasErrors=true. HasErrors: type: boolean description: Soft-error flag — failures return HTTP 200, always check this. description: Response of RateRFQ — locked rate + fee + TokenId for use in PreRegister. IncomingValidateAccountRequest: type: object properties: PayerID: type: integer format: int32 description: Optional. Payer to validate against; defaults to the agency's primary payer. BeneficiaryBankAccount: $ref: '#/components/schemas/BeneficiaryBankAccount' description: ValidateAccount request — verify a beneficiary bank account before PreRegister. BeneficiaryBankAccount: type: object description: Standalone beneficiary bank account for ValidateAccount (pre-PreRegister validation). properties: CountryCode: type: string description: ISO 3166-1 alpha-2 country where the account is held; drives the directory used. BankCode: type: string description: Bank identifier in the destination country's directory. BankName: type: string description: Bank display name. BranchCode: type: string description: Bank-branch identifier within the bank. BranchName: type: string description: Bank branch name. AccountType: type: integer format: int32 description: AccountTypeID enum. 0=Select Bank Account Type, 1=Checking, 2=Savings, 3=Business Checking, 4=Business Savings, 5=Other. AccountNumber: type: string description: Account identifier / IBAN. For Pix this is the Pix key. IncomingValidateAccountResponse: type: object required: - HasErrors properties: Errors: type: array nullable: true items: $ref: '#/components/schemas/ApiError' description: Populated when validation fails (account not found, bank unsupported, etc.). HasErrors: type: boolean description: Soft-error flag — failures return HTTP 200, always check this. description: Response of ValidateAccount; HasErrors=false means the account is acceptable for the corridor. IncomingRatesResponse: type: object required: - HasErrors properties: Results: type: array items: $ref: '#/components/schemas/TransferRateItem' description: Array of rate snapshots; null when none. Errors: type: array nullable: true items: $ref: '#/components/schemas/ApiError' description: Populated when HasErrors=true. HasErrors: type: boolean description: Soft-error flag — failures return HTTP 200, always check this. description: Response of Rates — rate snapshot per Reference at creation time. TransferRateItem: type: object properties: Reference: type: string description: Caller-supplied Reference of the transfer. Rate: type: number format: double description: Exchange rate applied at creation. description: Rate snapshot for one transfer. IncomingNotesResponse: type: object required: - HasErrors properties: Results: type: array items: $ref: '#/components/schemas/TransferNoteItem' description: Array of notes per TransferID; null when none. Errors: type: array nullable: true items: $ref: '#/components/schemas/ApiError' description: Populated when HasErrors=true. HasErrors: type: boolean description: Soft-error flag — failures return HTTP 200, always check this. description: Response of Notes — caller / agency notes per TransferID. TransferNoteItem: type: object properties: Reference: type: string description: Caller-supplied Reference of the transfer. Notes: type: array items: type: string description: Array of free-text note strings. description: Single note attached to a transfer. IncomingReceiptsResponse: type: object required: - HasErrors properties: Results: type: array items: $ref: '#/components/schemas/TransferReceiptItem' description: Array of receipts; null when none. Errors: type: array nullable: true items: $ref: '#/components/schemas/ApiError' description: Populated when HasErrors=true. HasErrors: type: boolean description: Soft-error flag — failures return HTTP 200, always check this. description: Response of Receipts — receipt records per Reference. TransferReceiptItem: type: object properties: Reference: type: string description: Caller-supplied Reference of the transfer. Identifier: type: string description: Receipt unique identifier. Note: type: string nullable: true description: Free-text note attached to the receipt. DocumentData: type: string format: byte description: Base64-encoded receipt PDF / image content. DocumentDataMimeType: type: string description: MIME type of the receipt content (e.g. application/pdf). DocumentDataFilename: type: string description: Suggested filename for the receipt download. description: Receipt record for one transfer. TransferStatusItem: type: object properties: Reference: type: string description: Caller-supplied Reference of the transfer. StatusID: type: integer format: int32 description: Current lifecycle state. 1=Created, 2=Hold, 3=Done (To Pay), 4=Transmitted To Payee, 5=Updated, 6=Void, 7=Paid, 8=Cancel, 9=Repair, 11=Processing Payment, 20=Refunded. HoldReasonIDs: type: array items: type: string description: 'Hold reason codes when StatusID=2. Letter-coded: S=High Risk – need every documentation, C=Invalid ID, P=KYC Form, R=Transaction is not confirmed, I=Need Proof of address or Proof.' RepairReasonID: type: integer format: int32 description: Reason code when StatusID=9 (Repair). RepairMessage: type: string nullable: true description: Free-text repair reason text. description: Status snapshot for one transfer. SenderIDModel: type: object description: Extended sender identification record used inside Sender.IDs[]. properties: IDType: type: integer format: int32 description: Document type enum. 0=None, 1=Driver's License, 2=SSN, 3=Alien Registration Card, 4=ID State Issued Card, 5=Passport, 6=Foreign Passport, 7=Other, 8=CPF, 9=Federal ID Number, 10=CNPJ, 11=Insurance Number, 12=ID Issued Card, 13=Utility Bill, 14=National Identity Card, 15=National Residence Card, 16=Foreign Identity Card, 17=European Identity Card, 18=European Residence Card, 19=Certificate of Registration, 20=Firearms License, 24=RUC, 25=Cedula. IDNo: type: string description: ID number / document identifier. IDIssuedDate: type: string format: date-time description: Date the document was issued. IDExpirationDate: type: string format: date-time description: Document expiration date. IssuedCountryCode: type: string description: ISO 3166-1 alpha-2 country code of the issuing authority. Authority: type: string description: Free-text name of the issuing authority. IDCopy: type: boolean description: True when a copy of the document is on file. BeneficiaryIDModel: type: object description: Single beneficiary identification document. properties: IDType: type: integer format: int32 description: Document type enum. 0=None, 1=Driver's License, 2=SSN, 3=Alien Registration Card, 4=ID State Issued Card, 5=Passport, 6=Foreign Passport, 7=Other, 8=CPF, 9=Federal ID Number, 10=CNPJ, 11=Insurance Number, 12=ID Issued Card, 13=Utility Bill, 14=National Identity Card, 15=National Residence Card, 16=Foreign Identity Card, 17=European Identity Card, 18=European Residence Card, 19=Certificate of Registration, 20=Firearms License, 24=RUC, 25=Cedula. IDNo: type: string description: ID number / document identifier. IDCopy: type: boolean description: True when a copy of the document is on file. paths: /api/Incoming/GetAvailableBalance: post: tags: - Incoming - Reference Data operationId: Incoming_GetAvailableBalance summary: Get available settlement balance for the authenticated payer. description: Endpoint ignores the request body. requestBody: required: false content: application/json: schema: type: object additionalProperties: true examples: minimum: value: {} full: value: {} responses: '200': description: Balance retrieved. content: application/json: schema: $ref: '#/components/schemas/IncomingBalanceResponse' example: Balance: 1000193461403.8 Errors: null HasErrors: false '405': description: Method Not Allowed. content: application/json: schema: $ref: '#/components/schemas/MethodNotAllowed' /api/Incoming/PayersList: post: tags: - Incoming - Reference Data operationId: Incoming_PayersList summary: List payers available to the authenticated caller. description: Request body is ignored. requestBody: required: false content: application/json: schema: type: object additionalProperties: true examples: minimum: value: {} full: value: {} responses: '200': description: Payer list retrieved. content: application/json: schema: $ref: '#/components/schemas/IncomingPayersResponse' '405': description: Method Not Allowed. content: application/json: schema: $ref: '#/components/schemas/MethodNotAllowed' /api/Incoming/BanksList: post: tags: - Incoming - Reference Data operationId: Incoming_BanksList summary: List banks for a destination country. description: CountryCode is not strictly enforced — missing/unknown/wrong-typed returns 200 with empty Results. requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/IncomingBanksListRequest' examples: minimum: value: CountryCode: BR full: value: CountryCode: AR responses: '200': description: Bank list (may be empty). content: application/json: schema: $ref: '#/components/schemas/IncomingBanksResponse' '405': description: Method Not Allowed. content: application/json: schema: $ref: '#/components/schemas/MethodNotAllowed' /api/Incoming/PayerNetworkList: post: tags: - Incoming - Reference Data operationId: Incoming_PayerNetworkList summary: List payer-network branches for a given PayerID. description: Returns branches for a PayerID. PayerBranchID is what's later passed as Payment.PayerBranchReference in PreRegister/Create. Invalid/missing PayerID returns HTTP 200 with HasErrors=true and TRPR999. requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/IncomingPayerNetworkRequest' examples: minimum: value: PayerID: 827 full: value: PayerID: 827 responses: '200': description: Success OR soft-error (check HasErrors). content: application/json: schema: $ref: '#/components/schemas/IncomingPayerNetworkResponse' examples: success: value: Results: - PayerBranchID: 23825 PayerBranchName: Belmoney Payer Account Deposit - France CountryCode: FR PaymentTypes: - 1 Currencies: - EUR Errors: null HasErrors: false invalid_payer_id: value: Results: null Errors: - Message: The payer ID is not valid. ErrorCode: TRPR999 HasErrors: true '405': description: Method Not Allowed. content: application/json: schema: $ref: '#/components/schemas/MethodNotAllowed' /api/Incoming/RatesAndFeesList: post: tags: - Incoming - Reference Data operationId: Incoming_RatesAndFeesList summary: Full rates and fees matrix across all payers/branches/currencies. description: 'Returns the complete rate/fee matrix. Endpoint takes no request body. Response can be very large (tested: 16,486 rows / ~7.2 MB). Each row is one (PayerBranchID, PaymentTypeID, CurrencyCode, amount band) tuple with Rate, PercentageFee and FlatFee. Prefer the per-corridor RateRFQ for real-time quotes; this endpoint is for periodic sync / matrix cache.' requestBody: required: false content: application/json: schema: type: object additionalProperties: true examples: minimum: value: {} full: value: {} responses: '200': description: Full rates matrix. content: application/json: schema: $ref: '#/components/schemas/IncomingRatesAndFeesResponse' example: Results: - CountryCode: AD CountryName: Andorra PayerID: 827 PayerName: Belmoney Payer Account Deposit PayerBranchID: 27972 PayerBranchName: Belmoney Payer - Portugal CurrencyCode: EUR CurrencyTypeName: Euro PaymentTypeID: 2 PaymentTypeName: Office Pick Up FromAmount: 1 ToAmount: 5000 PercentageFee: 0 FlatFee: 0 RateTypeID: 1 RateTypeDescription: Standard Rate: 1 FromCurrencyCode: EUR Errors: null HasErrors: false '405': description: Method Not Allowed. content: application/json: schema: $ref: '#/components/schemas/MethodNotAllowed' /api/Incoming/Statuses: post: tags: - Incoming - Transaction Lifecycle operationId: Incoming_Statuses summary: Get current status for a batch of transfer References. description: 'Accepts a JSON array of Reference strings (the spec also advertises application/x-www-form-urlencoded with "=ref1&=ref2"). Returns one TransferStatusItem per matched Reference. Unknown references are silently dropped: the response has Results=null / HasErrors=false. An empty array or a JSON object (non-array) body is rejected with HTTP 406. ' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/IncomingStatusesRequest' examples: minimum: summary: Single reference value: - TEST001 full: summary: Batch lookup value: - REF001 - REF002 - REF003 application/x-www-form-urlencoded: schema: type: string example: =REF001&=REF002 responses: '200': description: Status lookup completed. Unknown refs are silently dropped. content: application/json: schema: $ref: '#/components/schemas/IncomingStatusesResponse' examples: unknown_refs: value: Results: null Errors: null HasErrors: false '406': description: Not Acceptable — empty array or non-array body. content: application/json: schema: type: string example: '' '405': description: Method Not Allowed. content: application/json: schema: $ref: '#/components/schemas/MethodNotAllowed' /api/Incoming/Receipts: post: tags: - Incoming - Transaction Lifecycle operationId: Incoming_Receipts summary: Batch-download receipts (proof of payment) for a list of References. description: 'Request body must be application/x-www-form-urlencoded with "=ref1&=ref2" shape. JSON body is accepted at the HTTP level but the server cannot parse it as references (it returns Results=null). Unknown References return an empty Results[] array. Empty body returns HTTP 406. Only POST is allowed. ' requestBody: required: true content: application/x-www-form-urlencoded: schema: type: string example: =REF001&=REF002 examples: minimum: summary: Single reference value: =REF001 full: summary: Batch lookup value: =REF001&=REF002&=REF003 responses: '200': description: Receipts retrieved (may be empty). content: application/json: schema: $ref: '#/components/schemas/IncomingReceiptsResponse' '406': description: Not Acceptable — empty body. content: application/json: schema: type: string example: '' '405': description: Method Not Allowed. content: application/json: schema: $ref: '#/components/schemas/MethodNotAllowed' /api/Incoming/Notes: post: tags: - Incoming - Transaction Lifecycle operationId: Incoming_Notes summary: Batch-lookup operator notes attached to a list of References. description: 'Request body must be application/x-www-form-urlencoded with "=ref1&=ref2" shape. application/json is rejected by the core_sender client. Unknown refs return empty Results[]. Empty body returns HTTP 406. Only POST is allowed. ' requestBody: required: true content: application/x-www-form-urlencoded: schema: type: string example: =REF001&=REF002 examples: minimum: value: =REF001 full: value: =REF001&=REF002&=REF003 responses: '200': description: Notes retrieved (may be empty). content: application/json: schema: $ref: '#/components/schemas/IncomingNotesResponse' '406': description: Not Acceptable — empty body. content: application/json: schema: type: string example: '' '405': description: Method Not Allowed. content: application/json: schema: $ref: '#/components/schemas/MethodNotAllowed' /api/Incoming/Rates: post: tags: - Incoming - Transaction Lifecycle operationId: Incoming_Rates summary: Batch-lookup applied Rate per Reference. description: 'Request body must be application/x-www-form-urlencoded with "=ref1&=ref2" shape. Returns Rate used at transfer creation time per Reference. Unknown refs return empty Results[]. ' requestBody: required: true content: application/x-www-form-urlencoded: schema: type: string examples: minimum: value: =REF001 full: value: =REF001&=REF002&=REF003 responses: '200': description: Rates retrieved. content: application/json: schema: $ref: '#/components/schemas/IncomingRatesResponse' '406': description: Not Acceptable — empty body. '405': description: Method Not Allowed. content: application/json: schema: $ref: '#/components/schemas/MethodNotAllowed' /api/Incoming/ValidateAccount: post: tags: - Incoming - Validation operationId: Incoming_ValidateAccount summary: Validate a beneficiary bank account before transfer creation. description: 'Permissive validator: returns HasErrors=true only when PayerID is unknown (TRPR999). Missing BeneficiaryBankAccount or empty body returns 200 with no errors. Best run before PreRegister with PaymentTypeID=1 (Account Deposit) to pre-flight an IBAN. ' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/IncomingValidateAccountRequest' examples: minimum: summary: PayerID + minimal bank account (PT IBAN) value: PayerID: 827 BeneficiaryBankAccount: CountryCode: PT BankCode: '1028' AccountNumber: PT50003600009991234567890 full: summary: All BeneficiaryBankAccount fields populated value: PayerID: 827 BeneficiaryBankAccount: CountryCode: PT BankCode: '1028' BankName: MILLENNIUM BCP BranchCode: '001' BranchName: Lisboa AccountType: 1 AccountNumber: PT50003600009991234567890 responses: '200': description: Validation completed. Check HasErrors + Errors[].ErrorCode. content: application/json: schema: $ref: '#/components/schemas/IncomingValidateAccountResponse' examples: ok: value: Errors: null HasErrors: false invalid_payer: value: Errors: - Message: The payer ID is not valid. ErrorCode: TRPR999 HasErrors: true '405': description: Method Not Allowed. content: application/json: schema: $ref: '#/components/schemas/MethodNotAllowed' /api/Incoming/RateRFQ: post: tags: - Incoming - Quote operationId: Incoming_RateRFQ summary: Request-for-quote — get Rate, Fee, TokenId for a corridor. description: 'Request a quote for a (PayerID, PayerBranchID, PaymentTypeID, currency pair, country, amount). RateID is required (use 1 = Standard). Successful quotes return Rate+Fee+TokenId; TokenId can be passed as AmountAndFees.TokenId in PreRegister/Create to lock the rate. In UAT, many corridors return TRPR999 because sandbox pricing is incomplete. ' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/RateRFQ' examples: minimum: value: Amount: 100 AmountType: 1 SenderCurrencyCode: EUR BeneficiaryCurrencyCode: EUR BeneficiaryCountryCode: FR PayerID: 827 PayerBranchID: 23825 PaymentTypeID: 1 RateID: 1 full: value: Amount: 100 AmountType: 1 SenderCurrencyCode: EUR BeneficiaryCurrencyCode: EUR BeneficiaryCountryCode: FR PayerID: 827 PayerBranchID: 23825 PaymentTypeID: 1 RateID: 1 responses: '200': description: Quote result (check HasErrors). content: application/json: schema: $ref: '#/components/schemas/IncomingRateRFQResponse' examples: missing_amount: value: Errors: - Message: A valid amount is required ErrorCode: TRPR006 HasErrors: true missing_rate_id: value: Errors: - Message: A valid Rate ID is required ErrorCode: TRPR006 HasErrors: true no_pricing: summary: Sandbox pricing gap value: Errors: - Message: Fees not available (sandbox config) ErrorCode: TRPR999 HasErrors: true '405': description: Method Not Allowed. content: application/json: schema: $ref: '#/components/schemas/MethodNotAllowed' /api/Incoming/RequestCancel: post: tags: - Incoming - Transaction Lifecycle operationId: Incoming_RequestCancelTransfer summary: Request cancellation of a transfer by Reference. description: 'Submits a cancellation request. Does not immediately void the transfer — the StatusID transitions to 8 (Cancel) only after operator/partner approval. Unknown Reference returns TRPR004. Empty body returns TRPR004 (Reference=null). ' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/IncomingRequestCancelTransferRequest' examples: minimum: value: Reference: TEST001 full: value: Reference: TEST001 ReasonID: 4 Note: Incorrect beneficiary name responses: '200': description: Cancellation request recorded or rejected (check HasErrors). content: application/json: schema: $ref: '#/components/schemas/IncomingRequestCancelTransferResponse' examples: invalid_reference: value: Reference: TEST001 Errors: - Message: The reference is not valid. ErrorCode: TRPR004 HasErrors: true '405': description: Method Not Allowed. content: application/json: schema: $ref: '#/components/schemas/MethodNotAllowed' /api/Incoming/Repair: post: tags: - Incoming - Transaction Lifecycle operationId: Incoming_RepairTransfer summary: Update beneficiary data on a transfer in Repair state. description: 'Patches beneficiary fields on an existing transfer (StatusID=9 Repair typically). Only populated fields are updated. Unknown Reference returns TRPR004. Missing Beneficiary subobject triggers HTTP 500 NullReferenceException in the UAT server — callers MUST include Beneficiary (even if empty) to avoid the 500. ' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/IncomingRepairTransferRequest' examples: minimum: value: Reference: TEST001 Beneficiary: FirstName: Jean LastName: Dupont full: value: Reference: TEST001 Beneficiary: FirstName: Jean MiddleName: Pierre LastName: Dupont SecondLastName: Moreau Address: 1 rue de la Paix PhoneNumber: 0612345678 PhoneCountryCode: '33' AccountNo: FR7612345678901234567890123 Note: Corrected beneficiary details responses: '200': description: Repair submitted OR rejected (check HasErrors). content: application/json: schema: $ref: '#/components/schemas/IncomingRepairTransferResponse' examples: invalid_reference: value: Reference: TEST001 Errors: - Message: The reference is not valid. ErrorCode: TRPR004 HasErrors: true '500': description: Server error — NullReferenceException when Beneficiary is missing/null. content: application/json: schema: $ref: '#/components/schemas/ServerError' '405': description: Method Not Allowed. content: application/json: schema: $ref: '#/components/schemas/MethodNotAllowed' /api/Incoming/Confirm: post: tags: - Incoming - Transaction Lifecycle operationId: Incoming_Confirm summary: Confirm a PreRegistered transfer after PSP payment settles. description: 'Moves the transfer from StatusID=1 (Created) to StatusID=2 (Hold) / 3 (Done, To Pay), once the caller confirms the PSP has successfully captured funds. Unknown Reference returns TRPR006. Empty body also returns TRPR006 with Reference=null in the error message. Only POST is allowed. ' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/IncomingConfirmTransferRequest' examples: minimum: value: Reference: TEST001 TransferPayment: PaymentTypeID: 4 PaymentConfirmationCode: AUTH12345 full: value: Reference: TEST001 TransferPayment: PaymentTypeID: 4 PaymentConfirmationCode: AUTH12345 PaymentProcessorCode: STRIPE PaymentProcessorFullResponse: '{"id":"pi_abc","status":"succeeded"}' responses: '200': description: Confirmation result (check HasErrors). content: application/json: schema: $ref: '#/components/schemas/IncomingConfirmTransferResponse' examples: invalid_reference: value: Reference: null TransferID: null TransferPIN: null StatusID: 0 Errors: - Message: A transfer with the reference TEST001 does not exist. ErrorCode: TRPR006 HasErrors: true '405': description: Method Not Allowed. content: application/json: schema: $ref: '#/components/schemas/MethodNotAllowed' /api/Incoming/AddSenderDocuments: post: tags: - Incoming - Sender KYC operationId: Incoming_AddSenderDocuments summary: Attach KYC documents (ID, proof of address, etc.) to a transfer. description: 'Uploads Base64-encoded documents for a sender, keyed on a real TransferID from PreRegister/Create. Submitting an unknown TransferID triggers HTTP 500 NullReferenceException on the UAT server (same misbehavior pattern as Repair without Beneficiary). In production a valid TransferID must be used. Documents[].TypeID picks the document category from the DocumentTypeID enum. ' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/IncomingAddSenderDocumentsRequest' examples: minimum: value: TransferID: TEST001 Documents: - TypeID: 2 DocumentData: iVBORw0KGgo= IDNo: A1234567 full: value: TransferID: TEST001 Documents: - TypeID: 2 DocumentData: iVBORw0KGgo= Description: Passport scan IDNo: A1234567 IssuedDate: '2020-01-15T00:00:00Z' ExpirationDate: '2030-01-15T00:00:00Z' IssuedCountryCode: FR responses: '200': description: Upload accepted. content: application/json: schema: $ref: '#/components/schemas/IncomingAddSenderDocumentsResponse' '500': description: Server error — NullReferenceException when TransferID is invalid/unknown. content: application/json: schema: $ref: '#/components/schemas/ServerError' '405': description: Method Not Allowed. content: application/json: schema: $ref: '#/components/schemas/MethodNotAllowed' /api/Incoming/AddSenderSelfieVideo: post: tags: - Incoming - Sender KYC operationId: Incoming_AddSenderSelfieVideo summary: Attach a selfie/liveness video to a transfer for KYC. description: 'Uploads Base64-encoded VideoData keyed on TransferID. Same behavior pattern as AddSenderDocuments: unknown/invalid TransferID triggers HTTP 500 NullReferenceException on UAT. Use a real TransferID from PreRegister/Create. ' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/SenderVideoSelfieModel' examples: minimum: value: TransferID: TEST001 VideoData: AAAAHGZ0eXBpc29tAAA= full: value: TransferID: TEST001 VideoData: AAAAHGZ0eXBpc29tAAA= responses: '200': description: Upload accepted. content: application/json: schema: $ref: '#/components/schemas/IncomingAddSenderSelfieVideoResponse' '500': description: Server error — NullReferenceException on invalid TransferID. content: application/json: schema: $ref: '#/components/schemas/ServerError' '405': description: Method Not Allowed. content: application/json: schema: $ref: '#/components/schemas/MethodNotAllowed' /api/Incoming/PreRegister: post: tags: - Incoming - Transfer Creation operationId: Incoming_PreRegister summary: Create a new remittance transfer (pre-register before PSP payment). description: 'Creates a transfer in StatusID=1 (Created) and returns a system-generated TransferID and TransferPIN. Reference is caller-supplied and must be unique. After PSP funds settle, call Confirm to move the transfer forward. TransferID in the request MUST be an empty string (the server generates it). In UAT many corridors return TRPR006 ''Pricing Sheet not defined or out of range'' because the sandbox lacks complete pricing data. ' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/IncomingPreRegisterTransferRequest' examples: minimum: summary: Required-only payload value: Reference: TEST_PREREG_20260416_001 Sender: FirstName: Juan LastName: Perez Address1: Rue Belliard 123 CountryCode: BE StateName: Brussels CityName: Bruxelles IDs: - IDType: 5 IDNo: BE123456 Beneficiary: FirstName: Jean LastName: Dupont CountryCode: FR AmountAndFees: PaymentAmount: 100 OriginalAmount: 100 Rate: 1.0 RateID: 1 PayerCurrencyCode: EUR PaymentCurrencyCode: EUR Payment: PayerBranchReference: 23825 PaymentTypeID: 1 BankAccount: AccountNo: FR7612345678901234567890123 AccountType: 1 BranchName: Paris Code: FR023 full: summary: Full payload — empirically validated maximum field set (PT=1 Account Deposit representative). value: Reference: TEST_PREREG_FULL_PT1 TransferID: '' TransConfirmation: PSP-AUTH-PLACEHOLDER TransferPIN: '' CreationDate: '2026-04-23T00:00:00.000Z' TransferReasonID: 2 Sender: AgencyReference: AGENT-001 FirstName: Jane MiddleName: Marie LastName: Smith SecondLastName: Johnson Address1: 123 Main Street CountryCode: US StateName: NY CityName: New York CityCode: NY ZipCode: '10001' PhoneNumber: '+12125551234' CellPhoneNumber: '+12125559999' PhoneNumberCountryCode: '1' Email: jane.smith@example.com Sex: F DOB: '1985-06-15T00:00:00.000Z' BirthCityName: Boston BirthCountryCode: US CitizenshipCountryCode: USA ProfessionID: 72 PEPTypeID: 2 SenderTypeID: 1 IDs: - IDType: 5 IDNo: AB1234567 IDIssuedDate: '2020-01-15T00:00:00.000Z' IDExpirationDate: '2030-01-15T00:00:00.000Z' IssuedCountryCode: US Documents: - TypeID: 2 DocumentData: iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNk+M9QDwADhgGAWjR9awAAAABJRU5ErkJggg== Description: Passport Front IDNo: AB1234567 IssuedDate: '2020-01-15T00:00:00.000Z' ExpirationDate: '2030-01-15T00:00:00.000Z' IssuedCountryCode: US Beneficiary: AgencyReference: BEN-REF-001 FirstName: Chinedu MiddleName: Emeka LastName: Okoro SecondLastName: Eze Address1: 45 Victoria Island CityName: Lagos CityCode: LA StateCode: LA CountryCode: NG ZipCode: '100001' PhoneNumber: 08012345678 CellPhoneNumber: 08098765432 PrimaryPhoneNumber: 08011111111 Email: chinedu.okoro@example.com RelationshipToSenderID: 9 IDs: - IDType: 14 IDNo: NG987654321 IDCopy: true AmountAndFees: PaymentAmount: '1680.00' OriginalAmount: '100' Rate: '1680' RateID: 1 PayerCurrencyCode: EUR PaymentCurrencyCode: NGN PercentFee: '1.5' FlatFee: '5.00' OtherFee: '0.00' Tax: '0.50' FeesTax: '0.25' Discount: '0.00' PayerFlatFee: '3.00' PayerPercentFee: '1.0' PayerRate: '1680' BankRate: '1675' Payment: PayerBranchReference: '24076' PayerBranchCode: '044' PaymentTypeID: 1 LocationCode: '136333' BankAccount: Code: '044' Name: Access Bank BranchCode: '00021' BranchName: Victoria Island Branch AccountType: 2 AccountNo: '1234567890' Notes: - Full payload — all spec fields responses: '200': description: Pre-registration result (check HasErrors). content: application/json: schema: $ref: '#/components/schemas/IncomingCreateOrPreRegisterResponse' examples: pricing_missing: value: Reference: TEST_PREREG_20260416_001 TransferID: null TransferPIN: null StatusID: 0 Errors: - Message: Pricing Sheet not defined or out of range. ErrorCode: TRPR006 HasErrors: true missing_sender: value: Reference: null TransferID: null TransferPIN: null StatusID: 0 Errors: - Message: Object reference not set to an instance of an object. ErrorCode: TRPR999 HasErrors: true '405': description: Method Not Allowed. content: application/json: schema: $ref: '#/components/schemas/MethodNotAllowed' /api/Incoming/Create: post: tags: - Incoming - Transfer Creation operationId: Incoming_Create summary: Single-call create (same schema as PreRegister). description: 'Alternative to PreRegister + Confirm for callers that do not need the two-phase commit. Same request/response shape as PreRegister. Same sandbox constraints apply (TRPR006 on missing pricing, TRPR999 on missing nested objects). ' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/IncomingCreateTransferRequest' examples: minimum: value: Reference: TEST_CREATE_20260416_001 Sender: FirstName: Juan LastName: Perez Address1: Rue Belliard 123 CountryCode: BE StateName: Brussels CityName: Bruxelles IDs: - IDType: 5 IDNo: BE123456 Beneficiary: FirstName: Jean LastName: Dupont CountryCode: FR AmountAndFees: PaymentAmount: 100 OriginalAmount: 100 Rate: 1.0 RateID: 1 PayerCurrencyCode: EUR PaymentCurrencyCode: EUR Payment: PayerBranchReference: 23825 PaymentTypeID: 1 BankAccount: AccountNo: FR7612345678901234567890123 AccountType: 1 BranchName: Paris Code: FR023 full: value: Reference: TEST_CREATE_20260416_002 TransferReasonID: 2 Sender: FirstName: Juan MiddleName: Carlos LastName: Perez SecondLastName: Lopez Address1: Rue Belliard 123 CountryCode: BE StateName: Brussels CityName: Bruxelles PhoneNumber: 0498123456 PhoneNumberCountryCode: '32' BirthCountryCode: ES DOB: '1985-03-15T00:00:00Z' Sex: M CitizenshipCountryCode: ESP ProfessionID: 72 SenderTypeID: 1 PEPTypeID: 2 IDs: - IDType: 5 IDNo: ES123456789 IDIssuedDate: '2020-01-15T00:00:00Z' IDExpirationDate: '2030-01-15T00:00:00Z' IssuedCountryCode: ES Beneficiary: FirstName: Jean LastName: Dupont CountryCode: FR PhoneNumber: 0612345678 RelationshipToSenderID: 9 AmountAndFees: PaymentAmount: 100 OriginalAmount: 100 Rate: 1.0 RateID: 1 PayerCurrencyCode: EUR PaymentCurrencyCode: EUR Payment: PayerBranchReference: 23825 PaymentTypeID: 1 LocationCode: '136333' BankAccount: AccountNo: FR7612345678901234567890123 AccountType: 1 BranchName: Paris Code: FR023 Notes: - Test full Create responses: '200': description: Create result (check HasErrors). content: application/json: schema: $ref: '#/components/schemas/IncomingCreateOrPreRegisterResponse' '405': description: Method Not Allowed. content: application/json: schema: $ref: '#/components/schemas/MethodNotAllowed'