--- updatedAt: 2026-05-27T22:29:20.000Z agentTools: projectIndex: https://docs.spinwheel.io/llms.txt --- # Get a List of Payments This API will allow you to get list of the Payment requests created for a user with a provided userId, extRequestId or requestId. One of userId, extRequestId or requestId is required. # OpenAPI definition ```json { "openapi": "3.0.0", "paths": { "/v1/payments/requests": { "get": { "operationId": "Get Request", "summary": "Get a List of Payments", "description": "This API will allow you to get list of the Payment requests created for a user with a provided userId, extRequestId or requestId. One of userId, extRequestId or requestId is required.", "parameters": [ { "name": "userId", "required": false, "in": "query", "example": "ac89d6e8-c87b-415e-94e2-15367975218d", "description": "Spinwheel userId", "schema": { "type": "string" } }, { "name": "extRequestId", "required": false, "in": "query", "example": "12c9d6e8-c87b-415e-94e2-15367975218d", "description": "extRequestId passed by you in the payments request", "schema": { "type": "string" } }, { "name": "requestId", "required": false, "in": "query", "example": "fd97c6e8-c87b-415e-94e2-15367975218d", "description": "Spinwheel generated requestId of the payment request.", "schema": { "type": "string" } }, { "name": "requestType", "required": false, "in": "query", "example": "ONE_TIME", "description": "Filter on requestType", "schema": { "enum": [ "ONE_TIME", "RECURRING" ], "type": "string" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetPaymentRequests" }, "examples": { "Get Payment Requests example": { "value": { "status": { "code": 200, "desc": "success" }, "data": [ { "extRequestId": "12c9d6e8-c87b-415e-94e2-15367975218b", "amount": 100, "payerId": "12c9d6e8-c87b-415e-94e2-15367975218d", "userId": "ac89d6e8-c87b-415e-94e2-15367975218d", "tag": "Contribution", "requestType": "ONE_TIME", "useOfFunds": { "allocation": [ { "studentLoanId": "34a28279-b0df-4b6f-ad26-50cbef08f417", "percentage": 100, "liabilityType": "STUDENT_LOAN" } ] }, "settlementSpeed": "SAME_DAY", "scheduleTs": 1636250123000, "requestId": "fd97c6e8-c87b-415e-94e2-15367975218d", "settlementAccountId": "52c72bfb-fda2-44f1-8451-6a1d3a6a92d2", "createdOn": 1636250123000, "updatedOn": 1636250123000 }, { "extRequestId": "12c9d6e8-c87b-415e-94e2-15367975218c", "amount": 100, "payerId": "12c9d6e8-c87b-415e-94e2-15367975218d", "userId": "ac89d6e8-c87b-415e-94e2-15367975218d", "tag": "Contribution", "requestType": "ONE_TIME", "useOfFunds": { "allocation": [ { "homeLoanId": "34a28279-b0df-4b6f-ad26-50cbef08f417", "percentage": 100, "liabilityType": "HOME_LOAN" } ] }, "settlementSpeed": "SAME_DAY", "scheduleTs": 1636250123000, "requestId": "fd97c6e8-c87b-415e-94e2-15367975218d", "settlementAccountId": "52c72bfb-fda2-44f1-8451-6a1d3a6a92d2", "createdOn": 1636250123000, "updatedOn": 1636250123000 }, { "extRequestId": "12c9d6e8-c87b-415e-94e2-15367975218d", "amount": 100, "payerId": "12c9d6e8-c87b-415e-94e2-15367975218d", "userId": "ac89d6e8-c87b-415e-94e2-15367975218d", "tag": "Contribution", "requestType": "ONE_TIME", "useOfFunds": { "allocation": [ { "autoLoanId": "34a28279-b0df-4b6f-ad26-50cbef08f417", "percentage": 100, "liabilityType": "AUTO_LOAN" } ] }, "settlementSpeed": "SAME_DAY", "scheduleTs": 1636250123000, "requestId": "fd97c6e8-c87b-415e-94e2-15367975218d", "settlementAccountId": "52c72bfb-fda2-44f1-8451-6a1d3a6a92d2", "createdOn": 1636250123000, "updatedOn": 1636250123000 }, { "extRequestId": "12c9d6e8-c87b-415e-94e2-15367975218e", "amount": 100, "payerId": "12c9d6e8-c87b-415e-94e2-15367975218d", "userId": "ac89d6e8-c87b-415e-94e2-15367975218d", "tag": "Contribution", "requestType": "ONE_TIME", "useOfFunds": { "allocation": [ { "personalLoanId": "34a28279-b0df-4b6f-ad26-50cbef08f417", "percentage": 100, "liabilityType": "PERSONAL_LOAN" } ] }, "settlementSpeed": "SAME_DAY", "scheduleTs": 1636250123000, "requestId": "fd97c6e8-c87b-415e-94e2-15367975218d", "settlementAccountId": "52c72bfb-fda2-44f1-8451-6a1d3a6a92d2", "createdOn": 1636250123000, "updatedOn": 1636250123000 }, { "extRequestId": "12c9d6e8-c87b-415e-94e2-15367975218f", "amount": 100, "payerId": "12c9d6e8-c87b-415e-94e2-15367975218d", "userId": "ac89d6e8-c87b-415e-94e2-15367975218d", "tag": "Contribution", "requestType": "ONE_TIME", "useOfFunds": { "allocation": [ { "creditCardId": "34a28279-b0df-4b6f-ad26-50cbef08f417", "percentage": 100, "liabilityType": "CREDIT_CARD" } ] }, "settlementSpeed": "SAME_DAY", "scheduleTs": 1636250123000, "requestId": "fd97c6e8-c87b-415e-94e2-15367975218d", "settlementAccountId": "52c72bfb-fda2-44f1-8451-6a1d3a6a92d2", "createdOn": 1636250123000, "updatedOn": 1636250123000 }, { "extRequestId": "12c9d6e8-c87b-415e-94e2-15367975218h", "amount": 100, "payerId": "12c9d6e8-c87b-415e-94e2-15367975218d", "userId": "ac89d6e8-c87b-415e-94e2-15367975218d", "tag": "Contribution", "requestType": "RECURRING", "useOfFundsId": "a437c6e8-c87b-415e-94e2-15367975218d", "schedule": { "endDate": "2023-03-01T00:00:00.000Z", "startDate": "2021-03-01T00:00:00.000Z", "dayOfTheMonth": 2, "isLastDayOfMonth": true }, "requestId": "fd97c6e8-c87b-415e-94e2-15367975218d", "settlementAccountId": "52c72bfb-fda2-44f1-8451-6a1d3a6a92d2", "createdOn": 1636250123000, "updatedOn": 1636250123000 }, { "extRequestId": "12c9d6e8-c87b-415e-94e2-15367975218c", "amount": 100, "payerId": "12c9d6e8-c87b-415e-94e2-15367975218d", "userId": "ac89d6e8-c87b-415e-94e2-15367975218d", "tag": "Contribution", "requestType": "ONE_TIME", "useOfFunds": { "allocation": [ { "bankAccountId": "34a28279-b0df-4b6f-ad26-50cbef08f417", "percentage": 100 } ] }, "scheduleTs": 1636250123000, "requestId": "fd97c6e8-c87b-415e-94e2-15367975218d", "settlementAccountId": "52c72bfb-fda2-44f1-8451-6a1d3a6a92d2", "createdOn": 1636250123000, "updatedOn": 1636250123000 } ] } } } } } }, "400": { "description": "Bad request response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BadRequestResponse" } } } }, "401": { "description": "Unauthorized response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedResponse" } } } }, "404": { "description": "Not found response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFoundResponse" } } } }, "500": { "description": "Internal server error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InternalServerErrorResponse" } } } } }, "tags": [ "Payment Requests" ], "security": [ { "bearerAuth": [] } ] } } }, "info": { "title": "Pay", "description": "Welcome to Spinwheel's documentation! ", "version": "1.0", "contact": {} }, "tags": [ { "name": "Payment Requests" } ], "servers": [ { "url": "https://sandbox-api.spinwheel.io" }, { "url": "https://api.spinwheel.io" }, { "url": "https://secure-api.spinwheel.io" }, { "url": "https://secure-sandbox-api.spinwheel.io" } ], "components": { "securitySchemes": { "bearerAuth": { "type": "apiKey", "in": "header", "name": "Authorization", "description": "Once you've created a Spinwheel account and received credentials, you can access all of Spinwheel's APIs using a server-to-server call (in order to protect your credentials). When calling an API simply include your secretKey as a bearer token in an auth header like so: \n\n `Authorization: Bearer 8ae8d6fa-df8d-4c5d-9f9b-c4e4c10968b0`" } }, "schemas": { "BadRequest": { "type": "object", "properties": { "code": { "type": "number", "example": 400 }, "desc": { "type": "string", "example": "Bad request" } }, "required": [ "code", "desc" ] }, "BadRequestResponse": { "type": "object", "properties": { "status": { "$ref": "#/components/schemas/BadRequest" } }, "required": [ "status" ] }, "Unauthorized": { "type": "object", "properties": { "code": { "type": "number", "example": 401 }, "desc": { "type": "string", "example": "Invalid private key" } }, "required": [ "code", "desc" ] }, "UnauthorizedResponse": { "type": "object", "properties": { "status": { "$ref": "#/components/schemas/Unauthorized" } }, "required": [ "status" ] }, "NotFound": { "type": "object", "properties": { "code": { "type": "number", "example": 404 }, "desc": { "type": "string", "example": "Resource not found" } }, "required": [ "code", "desc" ] }, "NotFoundResponse": { "type": "object", "properties": { "status": { "$ref": "#/components/schemas/NotFound" } }, "required": [ "status" ] }, "InternalServerError": { "type": "object", "properties": { "code": { "type": "number", "example": 500 }, "desc": { "type": "string", "example": "Internal server error" } }, "required": [ "code", "desc" ] }, "InternalServerErrorResponse": { "type": "object", "properties": { "status": { "$ref": "#/components/schemas/InternalServerError" } }, "required": [ "status" ] }, "Message": { "type": "object", "properties": { "desc": { "type": "string", "example": "Example status description" }, "type": { "enum": [ "ERROR", "WARN", "INFO" ], "type": "string", "example": "ERROR" } }, "required": [ "desc" ] }, "ResponseStatus": { "type": "object", "properties": { "code": { "type": "number", "example": 200 }, "desc": { "type": "string", "example": "success" }, "messages": { "example": [ { "desc": "Example description" } ], "type": "array", "items": { "$ref": "#/components/schemas/Message" } } } }, "UseOfFundsPaymentRequest": { "type": "object", "properties": { "allocation": { "type": "array", "items": { "anyOf": [ { "$ref": "#/components/schemas/AllocationHomeLoan" }, { "$ref": "#/components/schemas/AllocationCreditCard" }, { "$ref": "#/components/schemas/AllocationPersonalLoan" }, { "$ref": "#/components/schemas/AllocationAutoLoan" }, { "$ref": "#/components/schemas/AllocationStudentLoan" }, { "$ref": "#/components/schemas/AllocationBankAccount" } ] } } } }, "Schedule": { "type": "object", "properties": { "startDate": { "format": "date-time", "type": "string", "example": "2022-01-01T00:00:00.000Z", "description": "Date (In YYYY-MM-DD format) to determine when the recurring payments to be started. Defaults to current date." }, "endDate": { "format": "date-time", "type": "string", "example": "2022-02-02T00:00:00.000Z", "description": "Date (In YYYY-MM-DD format) to determine when the recurring payments to be ended." }, "dayOfTheMonth": { "type": "number", "minimum": 1, "maximum": 31, "example": 5, "description": "An integer value between 1-31" }, "isLastDayOfMonth": { "type": "boolean", "example": false, "default": false, "description": "Whether or not the transaction is to be on scheduled last day of every month." } } }, "PaymentRequestResponseData": { "type": "object", "properties": { "requestId": { "type": "string", "example": "435ed671-28ee-4000-8e72-21aa7e65faf1", "description": "Spinwheel generated PaymentRequest Id." }, "settlementAccountId": { "type": "string", "example": "52c72bfb-fda2-44f1-8451-6a1d3a6a92d2", "description": "The settlement account associated with the payment request." }, "userId": { "type": "string", "example": "f1bba401-451a-42f0-bb4e-417359d02db7", "description": "Spinwheel userId of the user you're posting the recurringTransaction towards." }, "extRequestId": { "type": "string", "example": "fa5e8b72-a89d-431f-8db5-1e1d45eb6ecc", "description": "An id generated by you, a partner, to refer back the payment request. (Needs to be unique for a given request)" }, "amount": { "type": "number", "minimum": 1, "example": 500, "description": "Recurring transaction amount." }, "payerId": { "type": "string", "example": "52c72bfb-fda2-44f1-8451-6a1d3a6a92d2", "description": "payerId of payer from whom the payment would go through." }, "useOfFundsId": { "type": "string", "example": "89b40fb3-edc3-4f5f-893c-3bda78717111", "description": "useOfFundsId of funds allocation you've configured. Either of useOfFundsId or useOfFunds object is required." }, "useOfFunds": { "$ref": "#/components/schemas/UseOfFundsPaymentRequest" }, "scheduleTs": { "type": "number", "example": 1665682828, "description": "Epoch timestamp value of schedule date" }, "schedule": { "description": "If not provided, Current date will be taken as the date for posting recurring transactions.", "allOf": [ { "$ref": "#/components/schemas/Schedule" } ] }, "requestType": { "enum": [ "ONE_TIME", "RECURRING", "ROUND_UP", "AUTO_DEBIT" ], "type": "string", "example": "ONE_TIME", "description": "Whether the payment request is one-time or recurring." }, "settlementSpeed": { "enum": [ "STANDARD", "NEXT_DAY", "SAME_DAY" ], "type": "string", "example": "SAME_DAY", "description": "Settlement speed. If this field is not set, the default configuration will be used." }, "goalId": { "type": "string", "description": "This is to mark that this payment is made based on the goal.", "example": "53908eeb-9d98-49d9-aa3c-aa670c8e5bdc" }, "contributedBy": { "enum": [ "EMPLOYEE", "EMPLOYER" ], "type": "string", "description": "This is to mark that this payment is made by an employee or employer.", "example": "EMPLOYEE" }, "tag": { "type": "string", "description": "This is to tag payments with specific keywords.", "example": "Tag1" }, "createdOn": { "type": "number", "example": 1614602485926 }, "updatedOn": { "type": "number", "example": 1614602485926 } }, "required": [ "requestId", "userId", "extRequestId", "amount", "payerId", "requestType", "createdOn", "updatedOn" ] }, "GetPaymentRequests": { "type": "object", "properties": { "status": { "$ref": "#/components/schemas/ResponseStatus" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/PaymentRequestResponseData" } } }, "required": [ "status", "data" ] }, "AllocationStudentLoan": { "type": "object", "properties": { "studentLoanId": { "type": "string", "example": "435ed671-2800-4a7f-8e72-21aa7e65faf1", "description": "Spinwheel generated student loan id of the loan you're posting the payment to." }, "percentage": { "type": "number", "maximum": 100, "minimum": 1, "example": 50, "description": "Percentage of the amount you're posting towards the loan." }, "liabilityType": { "type": "string", "example": "STUDENT_LOAN", "description": "Type of liability towards which the useOfFunds is allocated.", "enum": [ "STUDENT_LOAN" ] } }, "required": [ "studentLoanId", "percentage" ] }, "AllocationHomeLoan": { "type": "object", "properties": { "homeLoanId": { "type": "string", "example": "435ed671-2800-4a7f-8e72-21aa7e65faf1", "description": "Spinwheel generated home loan id of the loan you're posting the payment to." }, "percentage": { "type": "number", "maximum": 100, "minimum": 1, "example": 50, "description": "Percentage of the amount you're posting towards the loan." }, "liabilityType": { "type": "string", "example": "HOME_LOAN", "description": "Type of liability towards which the useOfFunds is allocated.", "enum": [ "HOME_LOAN" ] } }, "required": [ "homeLoanId", "percentage" ] }, "AllocationAutoLoan": { "type": "object", "properties": { "autoLoanId": { "type": "string", "example": "435ed671-28ee-4000-8e72-21aa7e65faf1", "description": "Spinwheel generated loan id of the auto loan you're posting the payment to" }, "percentage": { "type": "number", "maximum": 100, "minimum": 1, "example": 53, "description": "Percentage of the amount you're posting towards the loan." }, "liabilityType": { "type": "string", "example": "AUTO_LOAN", "description": "Type of liability towards which the useOfFunds is allocated.", "enum": [ "AUTO_LOAN" ] } }, "required": [ "autoLoanId", "percentage" ] }, "AllocationCreditCard": { "type": "object", "properties": { "creditCardId": { "type": "string", "example": "435ed671-2000-4000-8e72-21aa7e65faf1", "description": "Spinwheel generated credit card id of cards you're posting the payment to." }, "percentage": { "type": "number", "maximum": 100, "minimum": 1, "example": 50, "description": "Percentage of the amount you're posting towards the card." }, "liabilityType": { "type": "string", "example": "CREDIT_CARD", "description": "Type of liability towards which the useOfFunds is allocated.", "enum": [ "CREDIT_CARD" ] } }, "required": [ "creditCardId", "percentage" ] }, "AllocationPersonalLoan": { "type": "object", "properties": { "personalLoanId": { "type": "string", "example": "435ed671-28ee-4000-8e72-21aa7e65faf1", "description": "Spinwheel generated loan id of personal loan you're posting the payment to" }, "percentage": { "type": "number", "maximum": 100, "minimum": 1, "example": 53, "description": "Percentage of the amount you're posting towards the loan." }, "liabilityType": { "type": "string", "example": "PERSONAL_LOAN", "description": "Type of liability towards which the useOfFunds is allocated.", "enum": [ "PERSONAL_LOAN" ] } }, "required": [ "personalLoanId", "percentage" ] }, "AllocationBankAccount": { "type": "object", "properties": { "bankAccountId": { "type": "string", "example": "435ed671-2800-4a7f-8e72-21aa7e65faf1", "description": "Spinwheel generated bank account id of the payable bank account you're posting the payment to." }, "percentage": { "type": "number", "maximum": 100, "minimum": 1 } }, "required": [ "bankAccountId", "percentage" ] } } } } ```