--- title: "Create a Payment" method: POST path: "/v1/payments/requests" tags: ["Payment Requests"] --- # Create a Payment `POST /v1/payments/requests` ## Request - Base URL: `https://sandbox-api.spinwheel.io` - URL: `https://sandbox-api.spinwheel.io/v1/payments/requests` - Auth: API key in header `Authorization` This API will allow you to create a Payment request for a user. ## Request body - CreatePaymentRequest - `userId` string, required: Spinwheel userId of the user the payment request is created for. - `extRequestId` string, required: An id generated by you, a partner, to refer back the payment request. (Needs to be unique for a given request) - `amount` number, required: Payment amount. - `payerId` string, required: payerId of payer from whom the payment would go through. - `settlementAccountId` string: The ID of the settlement account to draw funds from. - `useOfFundsId` string: useOfFundsId of funds allocation you've configured. Either of useOfFundsId or useOfFunds object is required. - `useOfFunds` UseOfFundsPaymentRequest - `allocation` union[] - union - AllocationHomeLoan - `homeLoanId` string, required: Spinwheel generated home loan id of the loan you're posting the payment to. - `percentage` number, required: Percentage of the amount you're posting towards the loan. - `liabilityType` 'HOME_LOAN': Type of liability towards which the useOfFunds is allocated. - AllocationCreditCard - `creditCardId` string, required: Spinwheel generated credit card id of cards you're posting the payment to. - `percentage` number, required: Percentage of the amount you're posting towards the card. - `liabilityType` 'CREDIT_CARD': Type of liability towards which the useOfFunds is allocated. - AllocationPersonalLoan - `personalLoanId` string, required: Spinwheel generated loan id of personal loan you're posting the payment to - `percentage` number, required: Percentage of the amount you're posting towards the loan. - `liabilityType` 'PERSONAL_LOAN': Type of liability towards which the useOfFunds is allocated. - AllocationAutoLoan - `autoLoanId` string, required: Spinwheel generated loan id of the auto loan you're posting the payment to - `percentage` number, required: Percentage of the amount you're posting towards the loan. - `liabilityType` 'AUTO_LOAN': Type of liability towards which the useOfFunds is allocated. - AllocationStudentLoan - `studentLoanId` string, required: Spinwheel generated student loan id of the loan you're posting the payment to. - `percentage` number, required: Percentage of the amount you're posting towards the loan. - `liabilityType` 'STUDENT_LOAN': Type of liability towards which the useOfFunds is allocated. - AllocationBankAccount - `bankAccountId` string, required: Spinwheel generated bank account id of the payable bank account you're posting the payment to. - `percentage` number, required - `scheduleTs` number: Epoch timestamp value of schedule date - `schedule` Schedule - `startDate` string, date-time: Date (in YYYY-MM-DD format) on which the schedule starts. Defaults to the current date. - `endDate` string, date-time: Date (in YYYY-MM-DD format) on which the schedule ends. - `dayOfTheMonth` number: An integer value between 1-31 - `isLastDayOfMonth` boolean: Whether or not the transaction is to be on scheduled last day of every month. - `requestType` 'ONE_TIME', required: Type of the payment request. Only ONE_TIME is supported. - `settlementSpeed` 'STANDARD' | 'NEXT_DAY' | 'SAME_DAY': Settlement speed. If this field is not set, the default configuration will be used. - `tag` string: This is to tag payments with specific keywords. ## Response `200` Successful response - CreatePaymentRequestResponse - `status` ResponseStatus, required - `code` number - `desc` string - `messages` Message[] - `desc` string, required - `type` 'ERROR' | 'WARN' | 'INFO' - `data` PaymentRequestResponseData, required - `requestId` string, required: Spinwheel generated PaymentRequest Id. - `settlementAccountId` string: The settlement account associated with the payment request. - `userId` string, required: Spinwheel userId of the user the payment request is created for. - `extRequestId` string, required: An id generated by you, a partner, to refer back the payment request. (Needs to be unique for a given request) - `amount` number, required: Payment amount. - `payerId` string, required: payerId of payer from whom the payment would go through. - `useOfFundsId` string: useOfFundsId of funds allocation you've configured. Either of useOfFundsId or useOfFunds object is required. - `useOfFunds` UseOfFundsPaymentRequest - `allocation` union[] - union - AllocationHomeLoan - `homeLoanId` string, required: Spinwheel generated home loan id of the loan you're posting the payment to. - `percentage` number, required: Percentage of the amount you're posting towards the loan. - `liabilityType` 'HOME_LOAN': Type of liability towards which the useOfFunds is allocated. - AllocationCreditCard - `creditCardId` string, required: Spinwheel generated credit card id of cards you're posting the payment to. - `percentage` number, required: Percentage of the amount you're posting towards the card. - `liabilityType` 'CREDIT_CARD': Type of liability towards which the useOfFunds is allocated. - AllocationPersonalLoan - `personalLoanId` string, required: Spinwheel generated loan id of personal loan you're posting the payment to - `percentage` number, required: Percentage of the amount you're posting towards the loan. - `liabilityType` 'PERSONAL_LOAN': Type of liability towards which the useOfFunds is allocated. - AllocationAutoLoan - `autoLoanId` string, required: Spinwheel generated loan id of the auto loan you're posting the payment to - `percentage` number, required: Percentage of the amount you're posting towards the loan. - `liabilityType` 'AUTO_LOAN': Type of liability towards which the useOfFunds is allocated. - AllocationStudentLoan - `studentLoanId` string, required: Spinwheel generated student loan id of the loan you're posting the payment to. - `percentage` number, required: Percentage of the amount you're posting towards the loan. - `liabilityType` 'STUDENT_LOAN': Type of liability towards which the useOfFunds is allocated. - AllocationBankAccount - `bankAccountId` string, required: Spinwheel generated bank account id of the payable bank account you're posting the payment to. - `percentage` number, required - `scheduleTs` number: Epoch timestamp value of schedule date - `schedule` Schedule - `startDate` string, date-time: Date (in YYYY-MM-DD format) on which the schedule starts. Defaults to the current date. - `endDate` string, date-time: Date (in YYYY-MM-DD format) on which the schedule ends. - `dayOfTheMonth` number: An integer value between 1-31 - `isLastDayOfMonth` boolean: Whether or not the transaction is to be on scheduled last day of every month. - `requestType` 'ONE_TIME', required: Type of the payment request. - `settlementSpeed` 'STANDARD' | 'NEXT_DAY' | 'SAME_DAY': Settlement speed. If this field is not set, the default configuration will be used. - `goalId` string: This is to mark that this payment is made based on the goal. - `contributedBy` 'EMPLOYEE' | 'EMPLOYER': This is to mark that this payment is made by an employee or employer. - `tag` string: This is to tag payments with specific keywords. - `createdOn` number, required - `updatedOn` number, required ## Other responses - `400`: Bad request response - `401`: Unauthorized response - `404`: Not found response - `500`: Internal server error response --- [API](https://skmtc.dev/spinwheel/apis/pay.md) - [All operations](https://skmtc.dev/spinwheel/apis/pay/llms.txt) - [OpenAPI document](https://skmtc.dev/spinwheel/apis/pay/revisions/58ba91f8ae13?raw)