{"openapi":"3.0.1","info":{"title":"OpenAPI definition","version":"v0"},"servers":[{"url":"https://api.pesawise.xyz","description":"Generated server url"}],"tags":[{"name":"Pesawise Payment Endpoints","description":"Pesawise Payments API"},{"name":"OAuth2 Endpoints","description":"OAuth2 Token Generation API"},{"name":"Account Lookup","description":"Account Number Lookup API"}],"paths":{"/oauth2/v1/generate":{"post":{"tags":["OAuth2 Endpoints","access-token"],"summary":"Generate OAuth2 Access Token","description":"Generate an OAuth2 access token using client credentials from Basic Authentication header","operationId":"generateToken","parameters":[{"name":"Authorization","in":"header","description":"Basic Authentication header with Base64 encoded client_id:client_secret","required":true,"schema":{"type":"string"},"example":"Basic QWJUQm9pTEd5MnRBWHU1RDA5QWM3OFpvNEd2bHg0VW5mRVlRMFZFcmlUSkt4UTkwOkIzZXhEZndaWEhCUzBqT3lKb2hBYlNxOWFCS0FpR2xMSWxWckFTS0lBNUtBMmJSUXU3a3NnUXd4d1hFenlLQTU="},{"name":"grant_type","in":"query","description":"OAuth2 grant type - must be 'client_credentials'","required":true,"schema":{"type":"string"},"example":"client_credentials"}],"responses":{"400":{"description":"Bad request - missing or invalid grant_type","content":{"*/*":{"schema":{"$ref":"#/components/schemas/OAuth2ErrorResponse"}}}},"200":{"description":"Access token generated successfully","content":{"*/*":{"schema":{"$ref":"#/components/schemas/OAuth2TokenResponse"}}}},"401":{"description":"Invalid client credentials","content":{"*/*":{"schema":{"$ref":"#/components/schemas/OAuth2ErrorResponse"}}}}}}},"/api/v1/account/lookup":{"post":{"tags":["account-lookup","Account Lookup"],"summary":"Lookup Account Number","description":"Retrieve account name by account number and shortcode. Requires Bearer token authentication.","operationId":"lookupAccountNumber","parameters":[{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AccountNumberLookupRequest"}}},"required":true},"responses":{"422":{"description":"Missing or malformed required fields in the request","content":{"*/*":{"schema":{"$ref":"#/components/schemas/AccountNumberErrorResponse"}}}},"200":{"description":"Successful request with valid account information returned","content":{"*/*":{"schema":{"$ref":"#/components/schemas/AccountNumberLookupResponse"}}}},"400":{"description":"Invalid input, such as incorrect account number","content":{"*/*":{"schema":{"$ref":"#/components/schemas/AccountNumberErrorResponse"}}}},"500":{"description":"Unexpected server-side failure","content":{"*/*":{"schema":{"$ref":"#/components/schemas/AccountNumberErrorResponse"}}}},"401":{"description":"Unauthorized - Invalid or expired bearer token","content":{"*/*":{"schema":{"$ref":"#/components/schemas/AccountNumberErrorResponse"}}}}},"security":[{"bearerAuth":[]}]}},"/api/payments/stk-push":{"post":{"tags":["Pesawise Payment Endpoints","h"],"summary":"M-PESA STK Push ","description":"Collect funds from a phone number","operationId":"stkPush","parameters":[{"name":"api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"api-secret","in":"header","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StkPushPayment"}}},"required":true},"responses":{"200":{"description":"STK Push was sucessful","headers":{"x-request-id":{"description":"Request Id for traceability","style":"simple"},"x-event-type":{"description":"stk-push","style":"simple"}},"content":{"*/*":{"schema":{"$ref":"#/components/schemas/PaymentResponse"}}}},"400":{"description":"Error occurred - bad request","content":{"*/*":{"schema":{"$ref":"#/components/schemas/StkFailedResponse"}}}}}}},"/api/payments/resend-otp":{"post":{"tags":["Pesawise Payment Endpoints","g"],"summary":"Resend Payment OTP","description":"Resend an OTP to your webhook","operationId":"resendOtp","parameters":[{"name":"api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"api-secret","in":"header","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResendOtp"}}},"required":true},"responses":{"400":{"description":"Error occurred - bad request","content":{"*/*":{"schema":{"$ref":"#/components/schemas/ResendOtpMessage"}}}},"201":{"description":"Otp was sent successfully","headers":{"x-request-id":{"description":"Request Id for traceability","style":"simple"},"x-event-type":{"description":"resend-otp","style":"simple"}},"content":{"*/*":{"schema":{"$ref":"#/components/schemas/ResendOtpSuccessMessage"}}}}}}},"/api/payments/pesalink-payment":{"post":{"tags":["Pesawise Payment Endpoints","b-pesalink"],"summary":"Create Pesalink Payment","description":"Initiate Pesalink payment for a balance","operationId":"pesalinkPayment","parameters":[{"name":"api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"api-secret","in":"header","required":true,"schema":{"type":"string"}},{"name":"is-virtual","in":"query","required":false,"schema":{"type":"boolean","default":false}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PesalinkPayment"}}},"required":true},"responses":{"201":{"description":"Pesalink payment was initiated successfully","headers":{"x-request-id":{"description":"Request Id for traceability","style":"simple"},"x-event-type":{"description":"create-pesalink-payment","style":"simple"}},"content":{"*/*":{"schema":{"$ref":"#/components/schemas/PaymentResponse"}}}},"400":{"description":"Error occurred - bad request","content":{"*/*":{"schema":{"$ref":"#/components/schemas/PaymentCreatedMessage"}}}}}}},"/api/payments/mpesa-payment":{"post":{"tags":["Pesawise Payment Endpoints","b-mpesa"],"summary":"Create M-PESA Payment","description":"Initiate M-PESA payment for a balance","operationId":"mpesaPayment","parameters":[{"name":"api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"api-secret","in":"header","required":true,"schema":{"type":"string"}},{"name":"is-virtual","in":"query","description":"virtual transactions ?","required":false,"schema":{"type":"boolean","default":false},"example":false}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MPesaPayment"}}},"required":true},"responses":{"400":{"description":"Error occurred - bad request","content":{"*/*":{"schema":{"$ref":"#/components/schemas/PaymentCreatedMessage"}}}},"201":{"description":"M-PESA payment was initiated successfully","headers":{"x-request-id":{"description":"Request Id for traceability","style":"simple"},"x-event-type":{"description":"create-mpesa-payment","style":"simple"}},"content":{"*/*":{"schema":{"$ref":"#/components/schemas/PaymentResponse"}}}}}}},"/api/payments/get-fee":{"post":{"tags":["Pesawise Payment Endpoints","z-fees"],"summary":"Fetch Fee for Payment","description":"Get Fees charged for a payment","operationId":"getFee","parameters":[{"name":"api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"api-secret","in":"header","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FeeRequest"}}},"required":true},"responses":{"400":{"description":"Error occurred - bad request","content":{"*/*":{"schema":{"$ref":"#/components/schemas/FeeResponseMessage"}}}},"200":{"description":"Fees fetched successfully","headers":{"x-request-id":{"description":"Request Id for traceability","style":"simple"},"x-event-type":{"description":"fee-info","style":"simple"}},"content":{"*/*":{"schema":{"$ref":"#/components/schemas/Fee"}}}}}}},"/api/payments/get-bank-info":{"post":{"tags":["Pesawise Payment Endpoints","za-bank"],"summary":"Get all supported banks","description":"Get all banks supported by Pesawise to make payments to","operationId":"bankInfo","parameters":[{"name":"api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"api-secret","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"400":{"description":"Error occurred - bad request","content":{"*/*":{"schema":{"$ref":"#/components/schemas/MessageResponse"}}}},"200":{"description":"Fetched banks successfully","headers":{"x-request-id":{"description":"Request Id for traceability","style":"simple"},"x-event-type":{"description":"bank-info","style":"simple"}},"content":{"*/*":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/BankInfo"}}}}}}}},"/api/payments/generate-qr-code":{"post":{"tags":["ab","Pesawise Payment Endpoints"],"summary":"Generate QR Code for Balance","description":"Generate QR Code for Balance","operationId":"generateQRCode","parameters":[{"name":"api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"api-secret","in":"header","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenerateQRRequest"}}},"required":true},"responses":{"400":{"description":"Error occurred - bad request","headers":{"x-request-id":{"description":"Request Id for traceability","style":"simple"}},"content":{"*/*":{"schema":{"$ref":"#/components/schemas/GenerateQRResponse"}}}},"200":{"description":"QR Code generated successfully","headers":{"x-request-id":{"description":"Request Id for traceability","style":"simple"},"x-event-type":{"description":"generate-qr-code","style":"simple"}},"content":{"*/*":{"schema":{"$ref":"#/components/schemas/GenerateQRResponse"}}}}}}},"/api/payments/generate-qr-code-string":{"post":{"tags":["ab","Pesawise Payment Endpoints"],"summary":"Generate QR Code for Balance - String","description":"Generate QR Code for Balance - String","operationId":"generateQRCodeString","parameters":[{"name":"api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"api-secret","in":"header","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenerateQRRequest"}}},"required":true},"responses":{"200":{"description":"QR Code generated successfully","headers":{"x-request-id":{"description":"Request Id for traceability","style":"simple"},"x-event-type":{"description":"generate-qr-code","style":"simple"}},"content":{"*/*":{"schema":{"$ref":"#/components/schemas/GenerateQRStringResponse"}}}},"400":{"description":"Error occurred - bad request","headers":{"x-request-id":{"description":"Request Id for traceability","style":"simple"}},"content":{"*/*":{"schema":{"$ref":"#/components/schemas/GenerateQRStringResponse"}}}}}}},"/api/payments/create-direct-payment":{"post":{"tags":["Pesawise Payment Endpoints","bc-single-payment"],"summary":"Single Payment Request (No callback token)","description":"Create a direct payment request (No callback)","operationId":"completeTransferNonOtp","parameters":[{"name":"api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"api-secret","in":"header","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnsafeTransferRequest"}}},"required":true},"responses":{"400":{"description":"Invalid api keys","content":{"*/*":{"schema":{"$ref":"#/components/schemas/UnsafeCompleteTransferResponse"}}}},"200":{"description":"Payment Response","headers":{"x-request-id":{"description":"Request Id for traceability","style":"simple"}},"content":{"*/*":{"schema":{"$ref":"#/components/schemas/UnsafeCompleteTransferResponse"}}}}}}},"/api/payments/create-balance":{"post":{"tags":["ac","Pesawise Payment Endpoints"],"summary":"Create Wallet","description":"Create Balance / Wallet in the Pesawise system","operationId":"createBalance","parameters":[{"name":"api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"api-secret","in":"header","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateBalance"}}},"required":true},"responses":{"400":{"description":"Error occurred - bad request","content":{"*/*":{"schema":{"$ref":"#/components/schemas/CreateBalanceResponse"}}}},"200":{"description":"Balance created","headers":{"x-request-id":{"description":"Request Id for traceability","style":"simple"},"x-event-type":{"description":"create-wallet","style":"simple"}},"content":{"*/*":{"schema":{"$ref":"#/components/schemas/CreateBalanceResponse"}}}}}}},"/api/payments/complete-payment":{"post":{"tags":["Pesawise Payment Endpoints","g"],"summary":"Complete Payment","description":"Complete a payment sent to your token webhook","operationId":"completePayment","parameters":[{"name":"api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"api-secret","in":"header","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CompletePayment"}}},"required":true},"responses":{"400":{"description":"Error occurred - bad request","content":{"*/*":{"schema":{"$ref":"#/components/schemas/CompletePaymentFailedMessage"}}}},"200":{"description":"Payment was completed","headers":{"x-request-id":{"description":"Request Id for traceability","style":"simple"},"x-event-type":{"description":"complete-payment","style":"simple"}},"content":{"*/*":{"schema":{"$ref":"#/components/schemas/CompletePaymentSuccessMessage"}}}}}}},"/api/payments/check-qr-code-status":{"post":{"tags":["Pesawise Payment Endpoints","q-status"],"summary":"QR Code Payment status","description":"Get the status of a QR Code payment","operationId":"getQrPaymentStatus","parameters":[{"name":"api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"api-secret","in":"header","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/QRStatusRequest"}}},"required":true},"responses":{"200":{"description":"Payment status","headers":{"x-request-id":{"description":"Request Id for traceability","style":"simple"},"x-event-type":{"description":"payment-status","style":"simple"}},"content":{"*/*":{"schema":{"$ref":"#/components/schemas/QRStatusResponse"}}}},"404":{"description":"Status not found","content":{"*/*":{"schema":{"$ref":"#/components/schemas/QRStatusResponse"}}}}}}},"/api/payments/bulk-payment":{"post":{"tags":["Pesawise Payment Endpoints","b-bulk"],"summary":"Bulk Payment","description":"Bulk Payment Transfer","operationId":"bulkPayment","parameters":[{"name":"api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"api-secret","in":"header","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BulkPaymentRequest"}}},"required":true},"responses":{"200":{"description":"Bulk Payment Response","headers":{"x-request-id":{"description":"Request Id for traceability","style":"simple"}},"content":{"*/*":{"schema":{"$ref":"#/components/schemas/BulkPaymentResponse"}}}},"400":{"description":"Invalid api keys","content":{"*/*":{"schema":{"$ref":"#/components/schemas/BulkPaymentResponse"}}}}}}},"/api/payments/bank-recipient":{"post":{"tags":["ab","Pesawise Payment Endpoints"],"summary":"Bank Recipient Validation","description":"Check bank account is valid","operationId":"bankRecipient","parameters":[{"name":"api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"api-secret","in":"header","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GetBankRecipient"}}},"required":true},"responses":{"400":{"description":"Error occurred - bad request","headers":{"x-request-id":{"description":"Request Id for traceability","style":"simple"}},"content":{"*/*":{"schema":{"$ref":"#/components/schemas/GetBankRecpientMessageResponse"}}}},"200":{"description":"Bank account validation success response","headers":{"x-request-id":{"description":"Request Id for traceability","style":"simple"},"x-event-type":{"description":"bank-recipient","style":"simple"}},"content":{"*/*":{"schema":{"$ref":"#/components/schemas/GetBankRecipientResponse"}}}}}}},"/api/payments/b2b-payment":{"post":{"tags":["b2b","Pesawise Payment Endpoints"],"summary":"Create B2B Payment","description":"Initiate B2B payment ","operationId":"b2bPayment","parameters":[{"name":"api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"api-secret","in":"header","required":true,"schema":{"type":"string"}},{"name":"is-virtual-account","in":"header","required":false,"schema":{"type":"boolean","default":false}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/B2BRequest"}}},"required":true},"responses":{"400":{"description":"Error occurred - bad request","content":{"*/*":{"schema":{"$ref":"#/components/schemas/PaymentCreatedMessage"}}}},"201":{"description":"B2B payment was initiated successfully","headers":{"x-request-id":{"description":"Request Id for traceability","style":"simple"},"x-event-type":{"description":"b2b-payment","style":"simple"}},"content":{"*/*":{"schema":{"$ref":"#/components/schemas/PaymentResponse"}}}}}}},"/api/payments/b2b-checker":{"post":{"tags":["b2b","Pesawise Payment Endpoints"],"summary":"B2B Recipient Validation","description":"Check B2B recipient is valid. For Paybill (providerId 1), the shortcode is the Paybill Number. For Till Number (providerId 3), the shortcode is the Merchant Till Number.","operationId":"b2bChecker","parameters":[{"name":"api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"api-secret","in":"header","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/B2BCheckerRequest"}}},"required":true},"responses":{"400":{"description":"Error occurred - bad request","content":{"*/*":{"schema":{"$ref":"#/components/schemas/MessageResponse"}}}},"200":{"description":"B2B validation success response","headers":{"x-request-id":{"description":"Request Id for traceability","style":"simple"},"x-event-type":{"description":"b2b-checker","style":"simple"}},"content":{"*/*":{"schema":{"$ref":"#/components/schemas/B2BCheckerResponse"}}}}}}},"/api/e-com/create-order":{"post":{"tags":["h"],"summary":"Create Payment Order","description":"Create order","operationId":"createOrder","parameters":[{"name":"api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"api-secret","in":"header","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateOrderRequest"}}},"required":true},"responses":{"400":{"description":"Error occurred - bad request","content":{"*/*":{"schema":{"$ref":"#/components/schemas/MessageResponse"}}}},"200":{"description":"Create order was successful","headers":{"x-request-id":{"description":"Request Id for traceability","style":"simple"}},"content":{"*/*":{"schema":{"$ref":"#/components/schemas/CreateOrderResponse"}}}}}}},"/api/payments/webhook-sample-stk-push":{"get":{"tags":["Pesawise Payment Endpoints","h"],"summary":"Webhook for STK push","description":"Webhook payload description for sample STK push","operationId":"webhookSampleStkPush","responses":{"200":{"description":"Sample Webhook response for stk push","headers":{"x-event-type":{"description":"Webhook type (merchant.stk-push.update)","style":"simple"},"x-secret-hash":{"description":"Secret hash provided","style":"simple"}},"content":{"*/*":{"schema":{"$ref":"#/components/schemas/WebhookStkResponse"}}}}}}},"/api/payments/webhook-sample-payment-complete":{"get":{"tags":["Pesawise Payment Endpoints","h"],"summary":"Webhook for complete payment","description":"Webhook payload description for sample complete","operationId":"webhookSamplePaymentComplete","responses":{"200":{"description":"Sample Webhook response for payment","headers":{"x-connection-password":{"description":"Connection Password in dashboard","style":"simple"},"x-event-type":{"description":"Webhook type (merchant.transfer.update)","style":"simple"},"x-connection-id":{"description":"Connection ID provided in dashboard","style":"simple"},"x-secret-hash":{"description":"Secret hash provided in dashboard","style":"simple"}},"content":{"*/*":{"schema":{"$ref":"#/components/schemas/WebhookStatusResponse"}}}}}}},"/api/payments/wallets":{"get":{"tags":["Pesawise Payment Endpoints","a-wallets"],"summary":"Get All Wallets","description":"Get all balances for a merchant","operationId":"getBalances","parameters":[{"name":"api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"api-secret","in":"header","required":true,"schema":{"type":"string"}},{"name":"isVirtual","in":"query","description":"Indicates whether the account is virtual","required":true,"schema":{"type":"boolean"}}],"responses":{"400":{"description":"Error occurred - bad request","content":{"*/*":{"schema":{"$ref":"#/components/schemas/GetAllBalancesMessageResponse"}}}},"200":{"description":"Wallet information","headers":{"x-request-id":{"description":"Request Id for traceability","style":"simple"}},"content":{"*/*":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/Balance"}}}}}}}},"/api/payments/wallet":{"get":{"tags":["Pesawise Payment Endpoints","a-wallet-a"],"summary":"Get one wallet by Id","description":"Wallet retrieval by id","operationId":"getBalance","parameters":[{"name":"api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"api-secret","in":"header","required":true,"schema":{"type":"string"}},{"name":"walletId","in":"query","description":"The unique identifier of the wallet","required":true,"schema":{"type":"integer","format":"int64"}},{"name":"isVirtual","in":"query","description":"Indicates whether the account is virtual","required":true,"schema":{"type":"boolean"}}],"responses":{"400":{"description":"Error occurred - bad request","content":{"*/*":{"schema":{"$ref":"#/components/schemas/GetBalanceMessageResponse"}}}},"200":{"description":"Wallet information","headers":{"x-request-id":{"description":"Request Id for traceability","style":"simple"}},"content":{"*/*":{"schema":{"$ref":"#/components/schemas/Balance"}}}}}}},"/api/payments/transactions":{"get":{"tags":["Pesawise Payment Endpoints","e"],"summary":"Fetch Transaction Per Wallet","description":"Wallet Transactions","operationId":"getWalletTransaction","parameters":[{"name":"api-key","in":"header","description":"API key for authentication","required":true,"schema":{"type":"string"}},{"name":"api-secret","in":"header","description":"API secret for authentication","required":true,"schema":{"type":"string"}},{"name":"page-size","in":"header","description":"Size of the page to be returned","required":false,"schema":{"type":"integer","format":"int32","default":10}},{"name":"page-number","in":"header","description":"Page number to be returned (starts from 1)","required":false,"schema":{"type":"integer","format":"int32","default":1}},{"name":"start-date","in":"header","description":"Start date for transaction filtering (yyyy/MM/dd)","required":false,"schema":{"type":"string","format":"date"}},{"name":"end-date","in":"header","description":"End date for transaction filtering (yyyy/MM/dd)","required":false,"schema":{"type":"string","format":"date"}},{"name":"wallet-id","in":"query","description":"The unique identifier of the wallet","required":true,"schema":{"type":"integer","format":"int64"}},{"name":"isVirtual","in":"query","description":"Indicates whether the account is virtual","required":true,"schema":{"type":"boolean"}}],"responses":{"400":{"description":"Balance not found","content":{"*/*":{"schema":{"$ref":"#/components/schemas/GetTransactionResponse"}}}},"200":{"description":"Wallet Transaction Response","headers":{"x-request-id":{"description":"Request Id for traceability","style":"simple"}},"content":{"*/*":{"schema":{"$ref":"#/components/schemas/GetTransactionResponse"}}}}}}},"/api/payments/qr-code-webhook":{"get":{"tags":["Pesawise Payment Endpoints","h"],"summary":"Webhook for QR code Payment","description":"Webhook payload for QR Code Payment","operationId":"p2mSample","responses":{"200":{"description":"QR Code Payload for successful payment","headers":{"x-event-type":{"description":"Webhook type (merchant.qr-code.payment)","style":"simple"},"x-secret-hash":{"description":"Secret hash provided","style":"simple"}},"content":{"*/*":{"schema":{"$ref":"#/components/schemas/P2MNotification"}}}}}}},"/api/payments/payment-status":{"get":{"tags":["Pesawise Payment Endpoints","c-status"],"summary":"Payment status","description":"Get the status of a payment","operationId":"getPaymentStatus","parameters":[{"name":"api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"api-secret","in":"header","required":true,"schema":{"type":"string"}},{"name":"paymentId","in":"query","description":"The unique identifier of the payment","required":false,"schema":{"type":"string","format":"uuid"}},{"name":"uniqueReference","in":"query","description":"The unique reference of the payment","required":false,"schema":{"type":"string","default":""}}],"responses":{"404":{"description":"Status not found","content":{"*/*":{"schema":{"$ref":"#/components/schemas/ErrorDTO"}}}},"200":{"description":"Payment status","headers":{"x-request-id":{"description":"Request Id for traceability","style":"simple"},"x-event-type":{"description":"payment-status","style":"simple"}},"content":{"*/*":{"schema":{"$ref":"#/components/schemas/BulkPaymentStateResponse"}}}}}}},"/api/payments/bulk-payment-status":{"get":{"tags":["Pesawise Payment Endpoints","d-bulk-status"],"summary":"Bulk Payment status","description":"Get the status of a Bulk payment with Batch ID","operationId":"getBulkPaymentStatus","parameters":[{"name":"api-key","in":"header","description":"API key for authentication","required":true,"schema":{"type":"string"}},{"name":"api-secret","in":"header","description":"API secret for authentication","required":true,"schema":{"type":"string"}},{"name":"page-size","in":"header","description":"Size of the page to be returned","required":false,"schema":{"type":"integer","format":"int32","default":10}},{"name":"page-number","in":"header","description":"Page number to be returned","required":false,"schema":{"type":"integer","format":"int32","default":1}},{"name":"batch-id","in":"query","description":"The unique batch identifier of the payment","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"400":{"description":"Invalid api keys","content":{"*/*":{"schema":{"$ref":"#/components/schemas/ErrorDTO"}}}},"200":{"description":"Bulk Payment status","headers":{"x-request-id":{"description":"Request Id for traceability","style":"simple"},"x-event-type":{"description":"bulk-payment-status","style":"simple"}},"content":{"*/*":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/BulkPaymentStateResponse"}}}}}}}}},"components":{"schemas":{"AccountNumberErrorResponse":{"type":"object","properties":{"requestId":{"type":"string","description":"The unique request identifier, matching the original request","example":"dcd1c2ab-7a26-4170-939d-9dc2e879b0e5"},"errorMessage":{"type":"string","description":"A description of the error encountered","example":"Invalid account number"}},"description":"Error response for account number lookup"},"OAuth2ErrorResponse":{"type":"object","properties":{"errorCode":{"type":"string"},"errorMessage":{"type":"string"}}},"OAuth2TokenResponse":{"type":"object","properties":{"access_token":{"type":"string","description":"The generated access token","example":"zoBcDCyxe4Isbvk6ZECr8MYfv79L"},"expires_in":{"type":"string","description":"Token expiry time in seconds","example":"3599"}},"description":"OAuth2 Token Response"},"AccountNumberLookupRequest":{"required":["accountNumber","requestId","shortcode","timestamp"],"type":"object","properties":{"requestId":{"type":"string","description":"A unique identifier for the request. Typically a UUID.","example":"dcd1c2ab-7a26-4170-939d-9dc2e879b0e5"},"timestamp":{"type":"string","description":"The timestamp at which the request is made. Format: UNIX timestamp or ISO 8601.","example":"1728897681"},"accountNumber":{"type":"string","description":"The account number to retrieve account name for","example":"66925336"},"shortcode":{"type":"integer","description":"The Organisation paybill shortcode","format":"int32","example":415010}},"description":"Request payload for account number lookup"},"AccountNumberLookupResponse":{"type":"object","properties":{"requestId":{"type":"string","description":"The unique request identifier, matching the original request","example":"dcd1c2ab-7a26-4170-939d-9dc2e879b0e5"},"timestamp":{"type":"string","description":"The timestamp of the request, matching the original request","example":"1728897681"},"accountName":{"type":"string","description":"The name of the account corresponding to the provided account number","example":"Money Market Account"},"accountNumber":{"type":"string","description":"The account number returned from the request","example":"66925336"},"shortcode":{"type":"integer","description":"The shortcode associated with the account number","format":"int32","example":415010}},"description":"Successful response for account number lookup"},"StkPushPayment":{"required":["amount","balanceId","phoneNumber","reference"],"type":"object","properties":{"balanceId":{"type":"integer","description":"Balance Id being collected into","format":"int64","example":100121},"amount":{"type":"number","description":"Amount being collected","format":"double","example":786},"phoneNumber":{"type":"string","description":"Phone number collecting from","example":"254712121212"},"reference":{"type":"string","description":"Your reference for the transaction","example":"INVOICE 2"}}},"PaymentResponse":{"required":["detail","paymentId","reference","success"],"type":"object","properties":{"paymentId":{"type":"string","description":"Unique identifier for the payment","format":"uuid","example":"f9eb1b23-4f78-495c-968c-9dfdfc89a16d"},"success":{"type":"boolean","description":"Was the payment successful?","example":true},"detail":{"type":"string","description":"Details of the payment","example":"Payment processed successfully"},"reference":{"type":"string","description":"Reference provided for the payment","example":"TESTREF1"}}},"StkFailedResponse":{"type":"object","properties":{"requestId":{"type":"string","description":"Request Id for traceability","format":"uuid","example":"d4265597-5317-45fd-8d2f-8012870633d5"},"detail":{"type":"string","description":"Detail of the message.","example":"API key not valid or Internal error"},"status":{"type":"string","description":"Status","example":"INTERNAL_ERROR","enum":["API_KEYS_INVALID","INTERNAL_ERROR","API_NOT_ACTIVATED","INSUFFICIENT_FUNDS","NOT_SUPPORTED","CURRENCY_NOT_SUPPORTED","MOBILE_MONEY_NOT_WHOLE_NUMBER","BALANCE_NOT_FOUND","BALANCE_NOT_AUTHORISED","BALANCE_NOT_NUMERIC","WEB_HOOK_NOT_SPECIFIED_FOR_OTP","CLIENT_SIDE_ERROR"]}}},"ResendOtp":{"required":["paymentId"],"type":"object","properties":{"paymentId":{"type":"string","description":"Unique identifier of the payment.","format":"uuid","example":"ca959474-f61d-424c-8204-bd6e8abc6f11"}}},"ResendOtpMessage":{"type":"object","properties":{"requestId":{"type":"string","description":"Request Id for traceability","format":"uuid","example":"d4265597-5317-45fd-8d2f-8012870633d5"},"detail":{"type":"string","description":"Detail of the message.","example":"API key not valid or Internal error"},"status":{"type":"string","description":"Status","example":"INTERNAL_ERROR","enum":["API_KEYS_INVALID","INTERNAL_ERROR","API_NOT_ACTIVATED","WEBHOOK_NOT_SPECIFIED_FOR_OTP","PAYMENT_NOT_FOUND"]}}},"ResendOtpSuccessMessage":{"required":["message"],"type":"object","properties":{"message":{"type":"string","description":"Description of the request.","example":"Otp was sent successfully"}}},"PesalinkPayment":{"required":["accountNumber","amount","balanceId","bankId","currency","recipient","reference"],"type":"object","properties":{"balanceId":{"type":"integer","description":"Wallet Id making the payment","format":"int64","example":100121},"bankId":{"type":"integer","description":"Pesawise Bank identifier","format":"int64","example":2},"amount":{"type":"number","description":"Amount being sent","format":"double","example":786.12},"currency":{"type":"string","description":"Currency","example":"KES"},"accountNumber":{"type":"string","description":"Bank Account Number","example":"1122331122"},"reference":{"type":"string","description":"Bank payment reference","example":"REF122"},"recipient":{"type":"string","description":"Recipient Name","example":"Pesa Enterprises"},"tagId":{"type":"integer","description":"Tag ID","format":"int64","example":1},"recipientId":{"type":"string","description":"Client unique identifier for payment","example":"EMP12345"}}},"PaymentCreatedMessage":{"type":"object","properties":{"requestId":{"type":"string","description":"Request Id for traceability","format":"uuid","example":"d4265597-5317-45fd-8d2f-8012870633d5"},"detail":{"type":"string","description":"Detail of the message.","example":"API key not valid or Internal error"},"status":{"type":"string","description":"Status","example":"INTERNAL_ERROR","enum":["API_KEYS_INVALID","INTERNAL_ERROR","API_NOT_ACTIVATED","INSUFFICIENT_FUNDS","NOT_SUPPORTED","CURRENCY_NOT_SUPPORTED","MOBILE_MONEY_NOT_WHOLE_NUMBER","BALANCE_NOT_FOUND","BALANCE_NOT_AUTHORISED","BALANCE_NOT_NUMERIC","WEB_HOOK_NOT_SPECIFIED_FOR_OTP","CLIENT_SIDE_ERROR"]}}},"MPesaPayment":{"required":["amount","balanceId","phoneNumber","recipient","reference"],"type":"object","properties":{"amount":{"type":"number","description":"Amount being sent","format":"double","example":786.12},"phoneNumber":{"type":"string","description":"Phone number of receiver","example":"254712121212"},"balanceId":{"type":"integer","description":"Wallet Id of the account to send from","format":"int64","example":1001002},"balanceIdCharge":{"type":"integer","description":"Wallet Id to charge, if left empty the balance that is being debited from will be charged","format":"int64","example":1001004},"reference":{"type":"string","description":"Reference","example":"REF123"},"recipient":{"type":"string","description":"Recipient Name","example":"Khan Enterprises"},"recipientIdNumber":{"type":"string","description":"Recipient ID number","example":"28277111"},"tagId":{"type":"integer","description":"Tag ID","format":"int64","example":1},"recipientId":{"type":"string","description":"Client unique identifier for payment","example":"EMP12345"}}},"FeeRequest":{"required":["amount","currency","paymentType"],"type":"object","properties":{"paymentType":{"type":"string","description":"Payment type being ","example":"PESALINK","enum":["MPESA","PESALINK","RTGS","SWIFT"]},"amount":{"type":"number","description":"Amount being sent","format":"double","example":786.12},"currency":{"type":"string","description":"Currency","example":"KES"}}},"FeeResponseMessage":{"type":"object","properties":{"requestId":{"type":"string","description":"Request Id for traceability","format":"uuid","example":"d4265597-5317-45fd-8d2f-8012870633d5"},"detail":{"type":"string","description":"Detail of the message.","example":"API key not valid or Internal error"},"status":{"type":"string","description":"Status","example":"INTERNAL_ERROR","enum":["API_KEYS_INVALID","INTERNAL_ERROR","API_NOT_ACTIVATED","NOT_SUPPORTED","CURRENCY_NOT_SUPPORTED","MOBILE_MONEY_NOT_WHOLE_NUMBER"]}}},"Fee":{"type":"object","properties":{"paymentType":{"type":"string","description":"Payment type","example":"PESALINK","enum":["MPESA","PESALINK","RTGS","SWIFT"]},"fee":{"type":"number","description":"Fee chargeable","format":"double","example":12.2},"currency":{"type":"string","description":"Currency","example":"KES"}}},"MessageResponse":{"type":"object","properties":{"detail":{"type":"string","description":"Detail of the message.","example":"API key not valid or Insufficient funds"},"status":{"type":"string","description":"Status.","example":"API_KEYS_INVALID","enum":["SUCCESS","FAILED","API_KEYS_INVALID","INSUFFICIENT_FUNDS","NOT_FOUND","MALFORMED_URL","INTERNAL_ERROR","NOT_SUPPORTED","CURRENCY_NOT_SUPPORTED","MOBILE_MONEY_NOT_WHOLE_NUMBER","BALANCE_NOT_FOUND","BALANCE_NOT_AUTHORISED","BALANCE_NOT_NUMERIC","WEB_HOOK_NOT_SPECIFIED_FOR_OTP","TOKEN_RESENT","CLIENT_SIDE_ERROR"]}}},"BankInfo":{"required":["bankCode","bankName","id"],"type":"object","properties":{"id":{"type":"integer","description":"Pesawise Bank identifier","format":"int64","example":2},"bankCode":{"type":"string","description":"Kenya Bankers Association Code","example":"0001"},"bankName":{"type":"string","description":"Name of Bank","example":"KCB"}}},"GenerateQRRequest":{"required":["balanceId","currency"],"type":"object","properties":{"balanceId":{"type":"integer","description":"Wallet/Account Number to collect for","format":"int64","example":100121},"currency":{"type":"string","description":"Currency","example":"KES"},"amount":{"type":"number","description":"Amount being requested - if dynamic QR code","format":"double","example":100},"reference":{"type":"string","description":"Reference","example":"abcd"},"dynamic":{"type":"boolean"}}},"GenerateQRResponse":{"required":["status"],"type":"object","properties":{"requestId":{"type":"string","description":"Request Id for traceability","format":"uuid","example":"d4265597-5317-45fd-8d2f-8012870633d5"},"detail":{"type":"string","description":"Detail of the message.","example":"API key not valid or Internal error"},"status":{"type":"string","description":"Status","example":"INTERNAL_ERROR","enum":["API_KEYS_INVALID","INTERNAL_ERROR","API_NOT_ACTIVATED","NOT_SUPPORTED","CURRENCY_NOT_SUPPORTED","BALANCE_NOT_FOUND","BALANCE_NOT_AUTHORISED","BALANCE_NOT_NUMERIC","TOKEN_INVALID","SUCCESS"]},"success":{"type":"boolean","description":"Success","example":true},"qrUrl":{"type":"string","description":"QR Code Link","example":"https://pesawise.blob.core.windows.net/assets/sample_qr.png"}}},"GenerateQRStringResponse":{"required":["status"],"type":"object","properties":{"requestId":{"type":"string","description":"Request Id for traceability","format":"uuid","example":"d4265597-5317-45fd-8d2f-8012870633d5"},"detail":{"type":"string","description":"Detail of the message.","example":"API key not valid or Internal error"},"status":{"type":"string","description":"Status","example":"INTERNAL_ERROR","enum":["API_KEYS_INVALID","INTERNAL_ERROR","API_NOT_ACTIVATED","NOT_SUPPORTED","CURRENCY_NOT_SUPPORTED","BALANCE_NOT_FOUND","BALANCE_NOT_AUTHORISED","BALANCE_NOT_NUMERIC","TOKEN_INVALID","SUCCESS"]},"success":{"type":"boolean","description":"Success","example":true},"qrString":{"type":"string","description":"QR Code String","example":"00020101021128270008ke.go.qr08000070678611029260008ke.go.qr011013126709675204000061020053034045802KE5912PESAWISE KES6007NAIROBI620605020182310008ke.go.qr011520251117T08411788530013wise.pesa.xyz0132ECE1DD262C1D45698020ABE914C6883883380010m-pesa.com01020203050000004050000026230008ke.go.qr0107554723763040601"}}},"UnsafeTransferRequest":{"required":["amount","balanceId","currency","recipient","reference","transferType"],"type":"object","properties":{"balanceId":{"type":"integer","description":"Wallet Id of the account to send from","format":"int64","example":1001002},"balanceIdCharge":{"type":"integer","description":"Wallet Id to charge, if left empty the balance that is being debited from will be charged","format":"int64","example":1001004},"currency":{"type":"string","description":"Currency","example":"KES"},"amount":{"type":"number","description":"Amount being sent","format":"double","example":786},"transferType":{"type":"string","description":"Type of transfer","example":"BANK","enum":["BANK","B2B","B2C","BUSINESS_PAY_BILL","BUSINESS_BUY_GOODS","COUNTER_PARTY_TRANSFER"]},"phoneNumber":{"type":"string","description":"Phone number of receiver","example":"254712121212"},"reference":{"type":"string","description":"Reference for the payment","example":"REF123"},"recipient":{"type":"string","description":"Recipient Name","example":"Khan Enterprises"},"recipientIdNumber":{"type":"string","description":"Recipient ID number","example":"28277111"},"bankId":{"type":"integer","description":"Pesawise Bank identifier","format":"int64","example":2},"accountNumber":{"type":"string","description":"Account Number","example":"1122331122"},"paybillNumber":{"type":"string","description":"Paybill Number","example":"123456"},"tillNumber":{"type":"string","description":"Till Number","example":"654321"},"beneficiaryId":{"type":"integer","description":"Beneficiary ID","format":"int64","example":1002003},"walletIdTo":{"type":"integer","description":"Wallet ID To (Pesawise to Pesawise wallet)","format":"int64","example":1003004},"uniqueReference":{"type":"string","description":"Unique Reference","example":"PW-1001-1222"},"virtual":{"type":"boolean"}}},"UnsafeCompleteTransferResponse":{"required":["detail","paymentId","reference","status"],"type":"object","properties":{"paymentId":{"type":"string","description":"unique identifier of the payment"},"detail":{"type":"string","description":"Transfer outcome message","example":"invalid api keys"},"status":{"type":"string","description":"Transfer Status","example":"ERROR","enum":["INSUFFICIENT_FUNDS","MALFORMED_REQUEST","ERROR","SUCCESS","INVALID_API_KEYS","API_NOT_ENABLED","INTERNAL_ERROR","NON_UNIQUE_CLIENT_REFERENCE"]},"reference":{"type":"string","description":"Transfer narration reference "},"uniqueReference":{"type":"string","description":"Transfer unique reference if provided"},"success":{"type":"boolean","description":"Is successful"}}},"CreateBalance":{"required":["accountType","currency","name"],"type":"object","properties":{"currency":{"type":"string","description":"Currency for the balance","example":"KES"},"name":{"type":"string","description":"Name for the balance","example":"Payroll Account"},"accountType":{"type":"string","description":"Type of the account.","example":"CLIENT_VIRTUAL_ACCOUNT","enum":["CLIENT_ACCOUNT","CLIENT_VIRTUAL_ACCOUNT","CLIENT_SHARED_ACCOUNT","CLIENT_HYBRID_ACCOUNT"]}}},"Balance":{"required":["balanceAmount","balanceName","id","status"],"type":"object","properties":{"status":{"type":"string","description":"Status code","example":"SUCCESS","enum":["SUCCESS","FAILED","API_KEYS_INVALID","INSUFFICIENT_FUNDS","NOT_FOUND","MALFORMED_URL","INTERNAL_ERROR","NOT_SUPPORTED","CURRENCY_NOT_SUPPORTED","MOBILE_MONEY_NOT_WHOLE_NUMBER","BALANCE_NOT_FOUND","BALANCE_NOT_AUTHORISED","BALANCE_NOT_NUMERIC","WEB_HOOK_NOT_SPECIFIED_FOR_OTP","TOKEN_RESENT","CLIENT_SIDE_ERROR"]},"id":{"type":"integer","description":"Unique identifier of the balance.","format":"int64","example":100121},"balanceName":{"type":"string","description":"Balance name.","example":"Jamal's KES balance"},"balanceAmount":{"type":"number","description":"Amount held for this balance.","format":"double","example":12332.11},"bankAccountNumber":{"type":"string","description":"Bank Account Number","example":"8000010000150"},"branchCode":{"type":"string","description":"Branch Code","example":"118"},"bankName":{"type":"string","description":"Bank Name","example":"Pesawise Bank"},"bankCode":{"type":"string","description":"Bank Code","example":"0001"},"active":{"type":"boolean"},"virtualAccount":{"type":"boolean","writeOnly":true}}},"CreateBalanceResponse":{"required":["status"],"type":"object","properties":{"status":{"type":"string","description":"Status code","example":"SUCCESS","enum":["SUCCESS","FAILED","API_KEYS_INVALID","INSUFFICIENT_FUNDS","NOT_FOUND","MALFORMED_URL","INTERNAL_ERROR","NOT_SUPPORTED","CURRENCY_NOT_SUPPORTED","MOBILE_MONEY_NOT_WHOLE_NUMBER","BALANCE_NOT_FOUND","BALANCE_NOT_AUTHORISED","BALANCE_NOT_NUMERIC","WEB_HOOK_NOT_SPECIFIED_FOR_OTP","TOKEN_RESENT","CLIENT_SIDE_ERROR"]},"detail":{"type":"string","description":"Detail of the message.","example":"API key not valid or Internal error"},"balance":{"$ref":"#/components/schemas/Balance"}}},"CompletePayment":{"required":["otp","paymentId"],"type":"object","properties":{"paymentId":{"type":"string","description":"Unique identifier for the payment","format":"uuid","example":"f9eb1b23-4f78-495c-968c-9dfdfc89a16d"},"otp":{"type":"string","description":"OTP sent via email, webhook or SMS","example":"123131"}}},"CompletePaymentFailedMessage":{"type":"object","properties":{"requestId":{"type":"string","description":"Request Id for traceability","format":"uuid","example":"d4265597-5317-45fd-8d2f-8012870633d5"},"detail":{"type":"string","description":"Detail of the message.","example":"API key not valid or Internal error"},"status":{"type":"string","description":"Status","example":"INTERNAL_ERROR","enum":["API_KEYS_INVALID","INSUFFICIENT_FUNDS","INTERNAL_ERROR","API_NOT_ACTIVATED","NOT_SUPPORTED","CURRENCY_NOT_SUPPORTED","MOBILE_MONEY_NOT_WHOLE_NUMBER","BALANCE_NOT_FOUND","BALANCE_NOT_AUTHORISED","BALANCE_NOT_NUMERIC","WEB_HOOK_NOT_SPECIFIED_FOR_OTP","TOKEN_INVALID","PAYMENT_NOT_FOUND","RECIPIENT_INVALID_ID"]}}},"CompletePaymentSuccessMessage":{"required":["paymentId","reference","success"],"type":"object","properties":{"paymentId":{"type":"string","description":"Unique identifier for the payment","format":"uuid","example":"f9eb1b23-4f78-495c-968c-9dfdfc89a16d"},"reference":{"type":"string","description":"Reference set by the initiator","example":"test-ref"},"success":{"type":"boolean","description":"Is success","example":true}}},"QRStatusRequest":{"required":["balanceId"],"type":"object","properties":{"balanceId":{"type":"integer","description":"Wallet/Account Number to collect for","format":"int64","example":100121},"reference":{"type":"string","description":"Reference","example":"abcd"}}},"QRStatusResponse":{"required":["amount","detail","reference","requestId","status","success"],"type":"object","properties":{"requestId":{"type":"string","description":"Request ID for traceability","format":"uuid","example":"f9eb1b23-4f78-495c-968c-9dfdfc89a16d"},"detail":{"type":"string","description":"Detail","example":"true"},"status":{"type":"string","description":"Status","example":"SUCESS","enum":["API_KEYS_INVALID","INTERNAL_ERROR","API_NOT_ACTIVATED","NOT_SUPPORTED","CURRENCY_NOT_SUPPORTED","BALANCE_NOT_FOUND","BALANCE_NOT_AUTHORISED","BALANCE_NOT_NUMERIC","PAYMENT_NOT_FOUND","RECIPIENT_INVALID_ID","PAYMENT_PENDING","SUCCESS","REFERENCE_NOT_SPECIFIED"]},"success":{"type":"boolean","description":"Was the payment successful?","example":true},"reference":{"type":"string","description":"Reference provided for the payment","example":"TESTREF1"},"amount":{"type":"number","description":"Amount processed","format":"double","example":12.33}}},"BulkPayment":{"required":["amount","recipient","reference","transferType"],"type":"object","properties":{"amount":{"type":"number","description":"Amount being sent","format":"double","example":786},"transferType":{"type":"string","description":"Type of transfer","example":"BANK","enum":["BANK","B2B","B2C","BUSINESS_PAY_BILL","BUSINESS_BUY_GOODS","COUNTER_PARTY_TRANSFER"]},"phoneNumber":{"type":"string","description":"Phone number of receiver","example":"254712121212"},"reference":{"type":"string","description":"Reference for the payment","example":"REF123"},"recipient":{"type":"string","description":"Recipient Name","example":"Khan Enterprises"},"recipientIdNumber":{"type":"string","description":"Recipient ID number","example":"28277111"},"bankId":{"type":"integer","description":"Pesawise Bank identifier","format":"int64","example":2},"accountNumber":{"type":"string","description":"Account Number","example":"1122331122"},"paybillNumber":{"type":"string","description":"Paybill Number","example":"123456"},"tillNumber":{"type":"string","description":"Till Number","example":"654321"},"beneficiaryId":{"type":"integer","description":"Beneficiary ID","format":"int64","example":1002003},"uniqueReference":{"type":"string","description":"Unique Reference","example":"PW-1001-1222"},"walletIdTo":{"type":"integer","description":"Wallet ID To (Pesawise to Pesawise wallet)","format":"int64","example":1003004}},"description":"List of bulk payments to be processed"},"BulkPaymentRequest":{"required":["balanceId","bulkPayments","currency"],"type":"object","properties":{"balanceId":{"type":"integer","description":"Wallet Id of the account to send from","format":"int64","example":1001002},"balanceIdCharge":{"type":"integer","description":"Wallet Id to charge, if left empty the balance that is being debited from will be charged","format":"int64","example":1001004},"currency":{"type":"string","description":"Currency","example":"KES"},"bulkPayments":{"type":"array","description":"List of bulk payments to be processed","items":{"$ref":"#/components/schemas/BulkPayment"}},"virtual":{"type":"boolean"}}},"BulkPaymentResponse":{"required":["batchId","bulkResponseStatus","message"],"type":"object","properties":{"batchId":{"type":"string","description":"Unique identifier used to query the batch transfer status","format":"uuid"},"success":{"type":"boolean","description":"Indicates whether the payment was staged or not","example":true},"bulkResponseStatus":{"type":"string","description":"Status of the bulk operation.","example":"SUCCESS","enum":["INSUFFICIENT_FUNDS","MALFORMED_REQUEST","ERROR","SUCCESS","INVALID_API_KEYS","API_NOT_ENABLED","INTERNAL_ERROR","NON_UNIQUE_CLIENT_REFERENCE"]},"message":{"type":"string","description":"Message related to the bulk operation status.","example":"Bulk operation staged successfully."}}},"GetBankRecipient":{"required":["bankAccountNumber","bankId"],"type":"object","properties":{"bankId":{"type":"integer","description":"Bank Identifier","format":"int64","example":2},"bankAccountNumber":{"type":"string","description":"Bank Account Number","example":"123131"}}},"GetBankRecpientMessageResponse":{"type":"object","properties":{"requestId":{"type":"string","description":"Request Id for traceability","format":"uuid","example":"d4265597-5317-45fd-8d2f-8012870633d5"},"detail":{"type":"string","description":"Detail of the message.","example":"API key not valid or Internal error"},"status":{"type":"string","description":"Status","example":"INTERNAL_ERROR","enum":["API_KEYS_INVALID","INTERNAL_ERROR"]}}},"GetBankRecipientResponse":{"required":["accountValidationStatus"],"type":"object","properties":{"accountValidationStatus":{"type":"string","description":"Recipient status code","example":"RECIPIENT_VALID","enum":["RECIPIENT_VALID","RECIPIENT_CHECK_NOT_SUPPORTED","DESTINATION_INVALID","RECIPIENT_INVALID"]},"recipient":{"type":"string","description":"Recipient Name, only present if account validation status is RECIPIENT_VALID","example":"Jay Z"},"requestId":{"type":"string","description":"Request Id for traceability","format":"uuid","example":"d4265597-5317-45fd-8d2f-8012870633d5"}}},"B2BRequest":{"required":["amount","balanceId","paymentReason","providerId"],"type":"object","properties":{"providerId":{"type":"integer","description":"Identifier for payment type. Allowed values: 1 (Paybill), 2 (Till Number). Required.","format":"int64","example":1},"balanceId":{"type":"integer","description":"The wallet ID to be debited. Required.","format":"int64","example":100101},"paybillNumber":{"type":"string","description":"The paybill number (e.g., '247247'). Required if providerId is 1.","example":"247247"},"account":{"type":"string","description":"The account number (e.g., '101010100101'). Required if providerId is 1.","example":"101010100101"},"tillNumber":{"type":"string","description":"The recipient's till number (e.g., '901201'). Required if providerId is 2.","example":"901201"},"amount":{"type":"number","description":"The payment amount. Required.","format":"double","example":10.0},"paymentReason":{"type":"string","description":"A brief description of the payment purpose. Required.","example":"Payment for services"},"tagCode":{"type":"integer","description":"Client Tag code.","format":"int64","example":1001},"recipientId":{"type":"string","description":"Client unique identifier.","example":"EMP101"},"projectCode":{"type":"string","description":"Client Project code.","example":"DEPT-10110"}}},"B2BCheckerRequest":{"required":["providerId","shortcode"],"type":"object","properties":{"shortcode":{"type":"string","description":"the paybill Number for paybill provider 1, or merchant till number for till number provider 3","example":"303030"},"providerId":{"type":"integer","description":"providerId should be 1 for paybill, 3 for till number","format":"int64","example":1}}},"B2BCheckerResponse":{"required":["status"],"type":"object","properties":{"status":{"type":"string","description":"Recipient status code","example":"RECIPIENT_VALID","enum":["RECIPIENT_VALID","RECIPIENT_CHECK_NOT_SUPPORTED","DESTINATION_INVALID","RECIPIENT_INVALID","API_KEY_INVALID","API_NOT_ACTIVATED","INTERNAL_ERROR"]},"recipient":{"type":"string","description":"Valid recipient name. only present if account validation status is RECIPIENT_VALID"},"errorMessage":{"type":"string","description":"Error Message. only present in case an error occurred"}}},"CreateOrderCustomerData":{"required":["phoneNumber"],"type":"object","properties":{"email":{"type":"string","description":"Email of the customer making the payment.","example":"acme@pesawise.com"},"phoneNumber":{"type":"string","description":"Phone number of the customer making the order.","example":"254724106569"},"city":{"type":"string","description":"City of the customer making the order.","example":"Nairobi"},"state":{"type":"string","description":"State of the customer making the order.","example":"Nairobi County"},"address":{"type":"string","description":"Address of the customer making the order.","example":"Park Place, 2nd Parklands Avenue"},"countryCode":{"type":"string","description":"Country code of the country of the payment.","example":"KE"}},"description":"Customer details - only phone number is mandatory.\n\nIf provided, this will be provided in the payload.\n.\n."},"CreateOrderRequest":{"required":["amount","balanceId","callbackUrl","currency","customerData","customerName","description","externalId"],"type":"object","properties":{"amount":{"type":"number","description":"Amount of the order.","format":"double","example":123.11},"customerName":{"type":"string"},"currency":{"type":"string","description":"Currency of the order, either KES or USD.","example":"KES"},"externalId":{"type":"string","description":"Identifier of the order in the customer system.","example":"acme_123311222"},"description":{"type":"string","description":"Description of the order.","example":"Payment for Flight XYZ"},"balanceId":{"type":"integer","description":"Balance ID to settle funds to, if null the primary balance will be selected.","format":"int64","example":1231311},"callbackUrl":{"type":"string","description":"A valid URL which Pesawise will redirect your clients to once payment has been processed.\n.","example":"https://www.mystore.com/success"},"cancellationUrl":{"type":"string","description":"A valid URL which Pesawise will redirect your clients to in-case they click on cancel request whilst making payment.\n\nIf provided, a cancellation link will appear next to the pay button.\n.\n.","example":"https://www.mystore.com/cancel"},"notificationId":{"type":"string","description":"An optional notification identifier send with the payment success, failure or cancellation payload.\n\nIf provided, this will be provided in the payload.\n.\n.","example":"abcdef-order-12"},"timeValidityMinutes":{"type":"integer","description":"An optional notification identifier send with the payment success, failure or cancellation payload.\n\nIf provided, this will be provided in the payload.\n.\n.","format":"int64"},"customerData":{"$ref":"#/components/schemas/CreateOrderCustomerData"}}},"CreateOrderResponse":{"type":"object","properties":{"requestId":{"type":"string","description":"Request Id for traceability","format":"uuid","example":"d4265597-5317-45fd-8d2f-8012870633d5"},"detail":{"type":"string","description":"Detail of the message.","example":"API key not valid or Internal error"},"status":{"type":"string","description":"Status","example":"INTERNAL_ERROR","enum":["API_KEYS_INVALID","INTERNAL_ERROR","API_NOT_ACTIVATED","NOT_SUPPORTED","CURRENCY_NOT_SUPPORTED","BALANCE_NOT_FOUND","BALANCE_NOT_AUTHORISED","BALANCE_NOT_NUMERIC","TOKEN_INVALID","SUCCESS"]},"success":{"type":"boolean","description":"Success","example":true},"createdPaymentOrder":{"$ref":"#/components/schemas/CreatedPaymentOrder"}}},"CreatedPaymentOrder":{"type":"object","properties":{"orderId":{"type":"string","description":"Order ID generated by Pesawise.","example":"11767013-7ac4-47fe-b9d4-824751fd31a2"},"loadUrl":{"type":"string","description":"Payment URL generated by Pesawise. You can load this or embed it in an iFrame","example":"https://pay.pesawise.com/checkout/11767013-7ac4"},"orderRequestId":{"type":"string","description":"Identifier of the order passed by the merchant","example":"od_12312211111"}},"description":"Created Payment order - only if success is true, otherwise null","example":"Create Payment Order"},"WebhookStkResponse":{"type":"object","properties":{"requestId":{"type":"string","format":"uuid"},"reference":{"type":"string"},"success":{"type":"boolean"},"details":{"type":"string"},"amount":{"type":"number","format":"double"}}},"WebhookStatusResponse":{"type":"object","properties":{"transactionId":{"type":"string"},"recipientId":{"type":"string"},"detail":{"type":"string"},"paymentStatus":{"type":"string","enum":["PENDING","COMPLETE","FAILED","PENDING_AUTHORIZATION","PENDING_MFA","CANCELLED","TOKEN_INVALID","INSUFFICIENT_FUNDS","SUCCESS"]},"paymentId":{"type":"string","format":"uuid"},"reference":{"type":"string"},"uniqueReference":{"type":"string"},"amount":{"type":"number","format":"double"},"amountFee":{"type":"number","format":"double"},"amountTax":{"type":"number","format":"double"},"timestamp":{"type":"string"},"transferType":{"type":"string","enum":["BANK","B2B","MOBILE_MONEY","INTERNAL","INTERNAL_FX","BILL_PAYMENT","COUNTERPARTY_TRANSFER"]},"currency":{"type":"string"},"description":{"type":"string"},"globalAccountId":{"type":"string"},"runningBalance":{"type":"number","format":"double"},"tagName":{"type":"string"},"tagCode":{"type":"string"}}},"GetAllBalancesMessageResponse":{"type":"object","properties":{"requestId":{"type":"string","description":"Request Id for traceability","format":"uuid","example":"d4265597-5317-45fd-8d2f-8012870633d5"},"detail":{"type":"string","description":"Detail of the message.","example":"API key not valid or Internal error"},"status":{"type":"string","description":"Status","example":"INTERNAL_ERROR","enum":["API_KEYS_INVALID","INTERNAL_ERROR","API_NOT_ACTIVATED"]}}},"GetBalanceMessageResponse":{"type":"object","properties":{"requestId":{"type":"string","description":"Request Id for traceability","format":"uuid","example":"d4265597-5317-45fd-8d2f-8012870633d5"},"detail":{"type":"string","description":"Detail of the message.","example":"API key not valid or Internal error"},"status":{"type":"string","description":"Status","example":"INTERNAL_ERROR","enum":["API_KEYS_INVALID","NOT_FOUND","INTERNAL_ERROR","API_NOT_ACTIVATED"]}}},"CommonTransaction":{"type":"object","properties":{"approvedTwoAt":{"type":"string","format":"date-time"},"approverThree":{"type":"string"},"approvedThreeAt":{"type":"string","format":"date-time"},"batchId":{"type":"string"},"date":{"type":"string","format":"date"},"tled":{"$ref":"#/components/schemas/CommonTransaction"},"dateString":{"type":"string"},"timeString":{"type":"string"},"commonTransactionId":{"type":"string","format":"uuid","writeOnly":true},"transactionStatusStatus":{"type":"string","writeOnly":true,"enum":["PENDING","COMPLETE","FAILED","ERROR","SUCCESSFUL","ERROR_PERM","INSUFFICIENT_FUNDS","ALREADY_PROCESSED"]},"id":{"type":"string"},"transactionId":{"type":"string","format":"uuid"},"amount":{"type":"number","format":"double"},"fees":{"type":"number","format":"double"},"tax":{"type":"number","format":"double"},"currency":{"type":"string"},"description":{"type":"string"},"reference":{"type":"string"},"debit":{"type":"boolean"},"settled":{"type":"boolean"},"imageUrl":{"type":"string"},"transactionAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"type":{"type":"string","enum":["BANK_TRANSFER","CARD","B2B","MOBILE_MONEY","FEE","TAX","REVENUE","REFUND","CHARGEBACK","REVERSAL","PAYMENT_LINK","INVOICE","BILL_PAYMENT","WITHDRAWAL","DEPOSIT","COST","INTERNAL","CARD_PAYMENT","BANK_FEE","MOBILE_MONEY_FEE","B2B_FEE","BILL_PAYMENT_FEE","BANK_COST","MOBILE_MONEY_COST","MOBILE_MONEY_REVENUE","BANK_TRANSFER_REVENUE","CARD_REVENUE","BILL_PAYMENT_REVENUE","B2B_REVENUE"]},"transactionStatus":{"type":"string","enum":["PENDING","COMPLETE","FAILED","ERROR","SUCCESSFUL","ERROR_PERM","INSUFFICIENT_FUNDS","ALREADY_PROCESSED"]},"metadata":{"type":"object","additionalProperties":{"type":"string"}},"initials":{"type":"string"},"merchantId":{"type":"integer","format":"int64"},"merchantName":{"type":"string"},"deviceId":{"type":"integer","format":"int64"},"transferId":{"type":"integer","format":"int64"},"accountId":{"type":"integer","format":"int64"},"otherAccountId":{"type":"integer","format":"int64"},"otherAccountRunningTotal":{"type":"integer","format":"int64"},"downloadableReceipt":{"type":"boolean"},"receipt":{"type":"string"},"runningTotal":{"type":"string"},"tagId":{"type":"integer","format":"int64"},"tagName":{"type":"string"},"tagCode":{"type":"string"},"attachmentUrl":{"type":"string"},"bankName":{"type":"string"},"bankAccountNumber":{"type":"string"},"departmentId":{"type":"integer","format":"int64"},"departmentName":{"type":"string"},"projectId":{"type":"integer","format":"int64"},"projectName":{"type":"string"},"projectCode":{"type":"string"},"customerName":{"type":"string"},"customerId":{"type":"integer","format":"int64"},"recipientId":{"type":"string"},"externalReference":{"type":"string"},"initiator":{"type":"string"},"initiatedAt":{"type":"string","format":"date-time"},"approverOne":{"type":"string"},"approvedOneAt":{"type":"string","format":"date-time"},"approverTwo":{"type":"string"}}},"GetTransactionResponse":{"required":["status"],"type":"object","properties":{"requestId":{"type":"string","description":"Request Id for traceability","format":"uuid","example":"d4265597-5317-45fd-8d2f-8012870633d5"},"detail":{"type":"string","description":"Detail of the message.","example":"API key not valid or Internal error"},"status":{"type":"string","description":"Status","example":"INTERNAL_ERROR","enum":["API_KEYS_INVALID","INTERNAL_ERROR","API_NOT_ACTIVATED","BALANCE_NOT_FOUND","SUCCESS","FAILED"]},"transactions":{"type":"array","items":{"$ref":"#/components/schemas/CommonTransaction"}},"metadata":{"$ref":"#/components/schemas/TransactionMetadata"}}},"TransactionMetadata":{"type":"object","properties":{"pageSize":{"type":"string"},"pageNumber":{"type":"string"},"totalElements":{"type":"string"},"totalPages":{"type":"string"}},"description":"Pagination metadata"},"P2MNotification":{"type":"object","properties":{"sender":{"type":"string","description":"Sender of funds","example":"Rushda Sheikh"},"rrn":{"type":"string","description":"Remote Id for traceability","example":"106800242025012901571921TC5592"},"amount":{"type":"number","description":"Amount sent","format":"double","example":2321.0},"paymentReason":{"type":"string","description":"Reason for payment - if entered","example":"Supermarket payment"},"status":{"type":"string","description":"Payment status","example":"ACCP"},"date":{"type":"string","description":"Payment date","example":"2025-02-03 11:28:58"},"billReference":{"type":"string","description":"Biller reference","example":"Biller reference - if applicable - otherwise empty"},"tillNumber":{"type":"string","description":"Unique till number","example":"171000155"},"balanceId":{"type":"integer","description":"Balance Id funds settled to","format":"int64","example":1000144}}},"ErrorDTO":{"type":"object","properties":{"detail":{"type":"string","description":"Detail of the message.","example":"API key Provided Not Valid "}}},"BulkPaymentStateResponse":{"required":["amount","currency","description","globalAccountId","paymentId","paymentStatus","reference","uniqueReference"],"type":"object","properties":{"paymentStatus":{"type":"string","description":"Status ","example":"PENDING","enum":["SUCCESS","FAILED","PENDING","NOT_FOUND","INVALID_API_KEYS","API_NOT_ENABLED"]},"paymentId":{"type":"string","description":"Unique identifier for the payment","format":"uuid","example":"f9eb1b23-4f78-495c-968c-9dfdfc89a16d"},"reference":{"type":"string","description":"Reference for the transfer","example":" June Payroll"},"uniqueReference":{"type":"string","description":"Unique Reference for the transfer","example":"PW-1001-1222"},"amount":{"type":"number","description":"Amount of the transfer","format":"double","example":100},"amountFee":{"type":"number","description":"Fee of the transfer","format":"double","example":10},"amountTax":{"type":"number","description":"Tax of the transfer","format":"double","example":10},"timestamp":{"type":"string","description":"Transfer Time","format":"date-time","example":"2024-07-02T09:26:29.062039Z"},"transferType":{"type":"string","description":"Transfer Type","example":"BANK","enum":["BANK","B2B","MOBILE_MONEY","INTERNAL","INTERNAL_FX","BILL_PAYMENT","COUNTERPARTY_TRANSFER"]},"currency":{"type":"string","description":"Currency of the transfer","example":"KES"},"description":{"type":"string","description":"Detail result of the transfer","example":"Payment failed"},"globalAccountId":{"type":"string","description":"Wallet ID","example":"1010911"}}}}}}