Payment Requests

openapi: 3.0.1 info: title: Victor REST API version: 2.0.0 servers: - url: https://api.stage.victorfi.com description: Victor Staging Environment - url: https://api.victorfi.com description: Victor Production Environment tags: - name: Payment Requests description: Payment Requests Controller paths: /v2/payment-requests: get: description: 'The Real-Time Payments (RTP) network from The Clearing House is a real-time payments platform that all federally insured US depository institutions are eligible to use. RTP payments are real-time, immediately available to the recipient (including weekends, holidays, and during non-bank hours), and settlement finality. The FedNow Service is a new instant payment infrastructure developed by the Federal Reserve that allows eligible depository institutions of different sizes across the U.S. to provide instant payment services. These Instant Payments can be made in real time, around the clock, every day of the year, including weekends and holidays. This endpoint allows for the retrieval of inbound and outbound payment requests (RfP requests). ' operationId: listPaymentRequests parameters: - description: Payment request and the page that should be returned. in: query name: PaymentRequestsFilter required: false schema: $ref: '#/components/schemas/ListPaymentRequests' explode: true style: form responses: '200': content: application/json: schema: $ref: '#/components/schemas/ListPaymentRequestsResponse' description: Request succeeded. '400': content: application/json: schema: $ref: '#/components/schemas/ValidationErrors' description: Invalid list payment requests request. summary: List Payment Requests tags: - Payment Requests /v2/payment-requests/request-payment: post: description: 'The Real-Time Payments (RTP) network from The Clearing House is a real-time payments platform that all federally insured US depository institutions are eligible to use. RTP payments are real-time, immediately available to the recipient (including weekends, holidays, and during non-bank hours), and settlement finality. The FedNow Service is a new instant payment infrastructure developed by the Federal Reserve that allows eligible depository institutions of different sizes across the U.S. to provide instant payment services. These Instant Payments can be made in real time, around the clock, every day of the year, including weekends and holidays. This endpoint allows for the creation of a Request for Payment (RfP) on the RTP Network or the FedNow Network using Victor. RfPs can be sent to a recipient to approve the release of funds as payment to the entity making the request. Please note that not all institutions are currently participating on the RTP Network or FedNow Network. You can verify bank eligibility prior to submitting the request using the endpoint documented at [Instant Payment Service Eligibility](https://docs.victorfi.com/reference/instantpaymentbankeligibility). ' operationId: createRequestPayment parameters: - in: header name: Idempotency-Key schema: type: string example: 1145f601-b8b0-4de7-9210-4ccb74a68ef5 description: A client provided unique value used by the server to identify subsequent retries of the same request. minLength: 20 maxLength: 128 required: false requestBody: content: application/json: schema: $ref: '#/components/schemas/NewRtpRfpPaymentRequest' required: true responses: '200': content: application/json: schema: $ref: '#/components/schemas/PaymentRequestReceipt' description: Request succeeded. '400': content: application/json: schema: $ref: '#/components/schemas/ApiErrorResponse' description: Invalid payment request. summary: Create Request for Payment (RfP) tags: - Payment Requests /v2/payment-requests/respond-to-request/{victor_payment_request_id}: post: description: 'The Real-Time Payments (RTP) network from The Clearing House is a real-time payments platform that all federally insured US depository institutions are eligible to use. RTP payments are real-time, immediately available to the recipient (including weekends, holidays, and during non-bank hours), and settlement finality. The FedNow Service is a new instant payment infrastructure developed by the Federal Reserve that allows eligible depository institutions of different sizes across the U.S. to provide instant payment services. These Instant Payments can be made in real time, around the clock, every day of the year, including weekends and holidays. This endpoint is used to provide a response to an inbound payment request. The confirmation can be an acceptance or rejection. ' operationId: respondToPaymentRequest parameters: - in: path name: victor_payment_request_id schema: type: string required: true description: Unique ID to reference the payment request. example: b34783af0 requestBody: content: application/json: schema: $ref: '#/components/schemas/RfpInboundPaymentRequestResponseRequestDetails' required: true responses: '200': content: application/json: schema: $ref: '#/components/schemas/RfpInboundPaymentRequestResponseDetails' description: Request succeeded. '400': content: application/json: schema: $ref: '#/components/schemas/ValidationErrors' description: Invalid payment request. summary: Respond to Request tags: - Payment Requests /v2/payment-requests/{victor_payment_request_id}: get: description: "The Real-Time Payments (RTP) network from The Clearing House is a real-time payments platform that all\ \ federally insured US depository institutions are eligible to use. RTP payments are real-time, immediately available\ \ to the recipient (including weekends, holidays, and during non-bank hours), and settlement finality. The FedNow\ \ Service is a new instant payment infrastructure developed by the Federal Reserve that allows eligible depository\ \ institutions of different sizes across the U.S. to provide instant payment services. These Instant Payments can\ \ be made in real time, around the clock, every day of the year, including weekends and holidays.\n\n This\ \ endpoint allows for the retrieval of an inbound and outbound payment request. Please note the `payment_request_response`\ \ object only exists for INBOUND payment requests and the payer details are either account details or a counterparty\ \ depending on the direction of the payment request.\n" operationId: getPaymentRequest parameters: - description: The Victor ID of the payment request in: path name: victor_payment_request_id required: true schema: type: string responses: '200': content: application/json: schema: $ref: '#/components/schemas/GetPaymentRequestResponse' description: Request succeeded. '400': content: application/json: schema: $ref: '#/components/schemas/ValidationErrors' description: Invalid list payment requests request. summary: Get Payment Request tags: - Payment Requests components: schemas: ApiError: description: The error information for a failed request properties: code: type: integer example: 101 message: type: string example: error.amount.invalid field: type: string example: paymentDetails.amount ApiErrorResponse: description: A response to a failed request properties: status: type: integer example: 0 data: type: object example: null error: $ref: '#/components/schemas/ApiError' ConfigurationProperty: properties: name: $ref: '#/components/schemas/ConfigurationPropertyName' origin: $ref: '#/components/schemas/Origin' value: type: object type: object ConfigurationPropertyName: properties: empty: type: boolean lastElementIndexed: type: boolean numberOfElements: format: int32 type: integer parent: $ref: '#/components/schemas/ConfigurationPropertyName' type: object GetPaymentRequestResponse: description: Response details of payment request. properties: victor_payment_request_id: description: Unique ID to reference the payment request. type: string example: b34783af0 client_reference_id: type: string example: a1b2c3d4567890 direction: description: Indicates if the request was originated by the caller (OUTBOUND) or an incoming RfP request (INBOUND) type: string example: INBOUND error_message: description: Message describing the error/failure reason. type: string example: Routing Number 800000219 is available on the RTP network but is not configured to support receiving a Payment Request at this time. It is not currently signed into the FedNow network. status: description: Either “Pending” or “Error”. Pending confirms the successful submission to the RTP network. type: string example: Pending payment_request: $ref: '#/components/schemas/RfpInboundPaymentRequestDetails' type: object ListPaymentRequests: properties: page: format: int32 minimum: 0 type: integer default: 0 description: Uses 0 based indexing. page_size: format: int32 minimum: 1 type: integer default: 50 victor_id: description: The Victor Id of the Payment Request example: LVDOAEFJKH type: string start_datetime: description: ISO 8601 date and time format requiring Zulu timezone. example: YYYY-MM-DDThh:mm:ss.sTZD type: string end_datetime: description: ISO 8601 date and time format requiring Zulu timezone. example: YYYY-MM-DDThh:mm:ss.sTZD type: string status: type: string description: The status of the payment request. enum: - accepted - completed - declined - expired - failed - pending - processing - created - needs-review direction: enum: - inbound - outbound type: string description: Indicates if the request was originated by the caller (outbound) or an incoming RfP request (inbound). due_date_start_date: description: ISO 8601 date format. example: YYYY-MM-DD type: string due_date_end_date: description: ISO 8601 date format. example: YYYY-MM-DD type: string approval_start_datetime: description: ISO 8601 date and time format requiring Zulu timezone. example: YYYY-MM-DDThh:mm:ss.sTZD type: string approval_end_datetime: description: ISO 8601 date and time format requiring Zulu timezone. example: YYYY-MM-DDThh:mm:ss.sTZD type: string victor_payment_request_parent_id: description: The Victor Id of the parent (outbound) payment request of the given payment request example: 1DZOLW34GI type: string victor_payment_request_child_id: description: The Victor Id of the child (inbound) payment request of the given payment request example: QNNEVS9JL4 type: string network_type: description: The instant payments network the payment request was sent through type: string enum: - FedNow - RTP tracking_id: description: The Tracking Id type: string example: 202509089R0VR201452208 instant_payment_rails_id: description: The ID on the instant payments network type: string example: 20250908083957044PAIN13161448151 type: object ListPaymentRequestsResponse: description: Response details of list payment requests request. properties: page: default: 0 format: int32 type: integer page_size: default: 25 format: int32 type: integer description: This property is due to be removed results: items: $ref: '#/components/schemas/PaymentRequestReceipt' type: array type: object NewRtpRfpPaymentRequest: description: Details of a new request for payment (RfP). properties: payee: $ref: '#/components/schemas/RfpPayeeRequestDetails' payer: $ref: '#/components/schemas/RfpPayerDetails' payment_details: $ref: '#/components/schemas/RfpBasePaymentDetails' client_reference_id: maxLength: 128 minLength: 0 type: string example: a1b2c3d4567890 required: - payee - payer - payment_details type: object ObjectError: properties: arguments: items: type: object type: array code: type: string codes: items: type: string type: array defaultMessage: type: string objectName: type: string type: object Origin: properties: parent: $ref: '#/components/schemas/Origin' type: object PaymentRequestReceipt: description: Details of a request for payment (RfP). properties: victor_payment_request_id: description: Unique ID to reference the payment request. type: string example: a7ffd43c37c1 client_reference_id: type: string example: a1b2c3d4567890 error_message: description: Message describing the error/failure reason. type: string example: Routing Number 800000219 is available on the RTP network but is not configured to support receiving a Payment Request at this time. It is not currently signed into the FedNow network. direction: description: Indicates if the request was originated by the caller (outbound) or an incoming RfP request (inbound) type: string example: OUTBOUND enum: - inbound - outbound status: description: The status of the RFP. The "Create RFP" endpoint will always return an RFP in the "created" status. type: string example: created enum: - created - accepted - completed - declined - expired - failed - pending - processing - needs-review payment_network: description: The instant payments network the payment request was sent through type: string enum: - FedNow - RTP victor_payment_request_parent_id: description: The Victor Id of the parent (outbound) payment request of the given payment request example: 1DZOLW34GI type: string victor_payment_request_child_id: description: The Victor Id of the child (inbound) payment request of the given payment request example: QNNEVS9JL4 type: string payment_request: $ref: '#/components/schemas/PaymentRequestReceiptInfo' type: object PaymentRequestReceiptInfo: properties: payee: $ref: '#/components/schemas/RfpPayeeResponseDetails' payer: $ref: '#/components/schemas/RfpPayerDetails' payment_details: $ref: '#/components/schemas/ReceiptPaymentDetails' approved_at: type: number description: Timestamp of when the payment request was approved. created_at: type: number description: Timestamp of when the payment request was created. ReceiptPaymentDetails: allOf: - $ref: '#/components/schemas/RtpPaymentDetails' required: - due_date - biller_type properties: biller_type: description: Specifies the biller type, must be BUSINESS or CONSUMER. enum: - BUSINESS - CONSUMER type: string example: BUSINESS due_date: description: Date the payment is due. The system default is 24 hours from transaction submission and values set to further out than that will be rejected by the API. If the payment is not confirmed by the debtor within this timeframe, the RfP request will be canceled by the network. type: string example: '2021-10-25' amount_modification_allowed: description: Whether this request for payment supports a change in payment amount by the payer on approval type: boolean example: true default: false original_amount: description: The original payment request amount. type: string approval_notes: description: The notes provided by the receiver of the request when responding. type: string RfpBasePaymentDetails: type: object properties: amount: description: The payment amount. type: string minLength: 0 pattern: \d+(\.\d{1,2})? example: '44.23' biller_type: description: Specifies the biller type, must be BUSINESS or CONSUMER. enum: - BUSINESS - CONSUMER type: string example: BUSINESS due_date: description: Date the payment is due. The system default is 24 hours from transaction submission and values set to further out than that will be rejected by the API. If the payment is not confirmed by the debtor within this timeframe, the RfP request will be canceled by the network. type: string example: '2021-10-25' amount_modification_allowed: description: Whether this request for payment supports a change in payment amount by the payer on approval type: boolean example: true default: false notes: description: Notes associated with the payment. type: string maxLength: 150 example: Notes regarding sample payment. required: - amount - biller_type - due_date RfpInboundPaymentRequestDetails: properties: payee: $ref: '#/components/schemas/RfpPayeeResponseDetails' payer: properties: account_number: description: The payer’s account number. type: string pattern: '[0-9]+' example: '243884643621' routing_number: description: The payer’s routing number. type: string pattern: '[0-9]+' example: '011401533' name: description: The name of the payer. type: string pattern: '^[A-Za-z0-9.]+(?: +[A-Za-z0-9.]+)*$' example: Victor Doe type: object payment_details: $ref: '#/components/schemas/ReceiptPaymentDetails' payment_request_response: $ref: '#/components/schemas/RfpInboundPaymentRequestResponseDetails' RfpInboundPaymentRequestResponseDetails: description: Object containing the payment request response for an INBOUND payment request. This is an empty object if a response has not been submitted. properties: victor_payment_request_id: description: Unique ID to reference the payment request. type: string example: b34783af0 status: description: 'Enum Values: Accepted, Rejected' enum: - Accepted - Rejected type: string original_amount: description: The original payment request amount. type: string minLength: 0 pattern: \d+(\.\d{1,2})? example: '44.23' modified_amount: description: If the payment was accepted with a modified amount, the modified amount is shown here. type: string minLength: 0 pattern: \d+(\.\d{1,2})? example: '34.23' notes: description: Notes about payment request response type: string maxLength: 150 example: Notes regarding accepted request. type: object RfpInboundPaymentRequestResponseRequestDetails: properties: status: description: 'Enum Values: Accepted, Declined' enum: - Accepted - Declined type: string modified_amount: description: Define the accepted amount on approving the payment request. This property is optional, with the payment defaulting to the original amount of the Payment Request if not provided. A `modified_amount` different from the original `amount` is only allowed if the Payment Request was created with the `amount_modification_allowed` flag enabled. type: string minLength: 0 pattern: \d+(\.\d{1,2})? example: '34.23' notes: description: Notes about payment request response type: string maxLength: 150 minLength: 1 example: Notes regarding accepted request. required: - status - notes type: object RfpPayeeRequestDetails: required: - account_number properties: account_number: description: The payee’s account number. Note this must be a Victor account or linked account. type: string minLength: 3 maxLength: 20 pattern: '[0-9]+' example: 043987673645 ultimate_creditor: description: The name of the ultimate creditor. Ultimate creditor can only be set if the biller_type is BUSINESS. type: string pattern: '^[A-Za-z0-9.]+(?: +[A-Za-z0-9.]+)*$' maxLength: 100 example: SampleCo Billing Inc. RfpPayeeResponseDetails: properties: account_number: description: The payee’s account number. type: string pattern: '[0-9]+' example: 043987673645 ultimate_creditor: description: The name of the ultimate creditor. type: string pattern: '^[A-Za-z0-9.]+(?: +[A-Za-z0-9.]+)*$' example: SampleCo Billing Inc. RfpPayerDetails: required: - victor_counterparty_id properties: victor_counterparty_id: description: The counterparty reference to the counterparty that contains the payer’s RTP bank information. maxLength: 16 minLength: 0 type: string example: aHeq349838 RtpPaymentDetails: required: - amount properties: amount: description: The payment amount. type: string minLength: 0 pattern: \d+(\.\d{1,2})? example: '44.23' notes: description: Notes associated with the payment. type: string maxLength: 150 example: Notes regarding sample payment. ValidationErrors: properties: allErrors: items: $ref: '#/components/schemas/ObjectError' type: array boundProperties: items: $ref: '#/components/schemas/ConfigurationProperty' type: array uniqueItems: true name: $ref: '#/components/schemas/ConfigurationPropertyName' type: object

Please ignore this field