openapi: "3.0.1" info: version: "0.2" title: Juspay Router - API Documentation x-logo: url: "https://fresheropenings.com/wp-content/uploads/2019/09/Juspay-off-campus-drive-2019.png" altText: "Juspay logo" contact: name: Juspay Support url: "https://juspay.io" email: support@juspay.in termsOfService: "https://www.juspay.io/terms" description: > ## Get started Juspay Router provides a collection of APIs that enable you to process and manage payments. Our APIs accept and return JSON in the HTTP body, and return standard HTTP response codes. You can consume the APIs directly using your favorite HTTP/REST library. We have a testing environment referred to "sandbox", which you can setup to test API calls without affecting production data. ### Base URLs Use the following base URLs when making requests to the APIs: | Environment | Base URL | |---------------|------------------------------------------------------| | Sandbox | | | Production | | # Authentication When you sign up on our [dashboard](https://app.hyperswitch.io) and create a merchant account, you are given a secret key (also referred as api-key). You may authenticate all API requests with Juspay server by providing the appropriate key in the request Authorization header. Never share your secret api keys. Keep them guarded and secure. servers: - url: https://sandbox.hyperswitch.io description: Sandbox Environment - url: https://router.juspay.io description: Production Environment tags: - name: QuickStart description: Quickly get started with our API suite. - name: Payments description: Process and manage payments across wide range of payment processors using the Unified Payments API. - name: Customers description: Create a Customer entity which you can use to store and retrieve specific customers' data and payment methods. # TODO: Add descriptions for each of these tags - name: PaymentMethods - name: Refunds - name: Mandates - name: MerchantAccounts - name: PaymentConnectors x-tagGroups: - name: Quick Start tags: - QuickStart - name: Payments tags: - Payments - name: Customers tags: - Customers - name: Payment Methods tags: - PaymentMethods - name: Refunds tags: - Refunds - name: Mandates tags: - Mandates - name: Merchant Accounts tags: - MerchantAccounts - name: Payment Connectors tags: - PaymentConnectors security: - ApiSecretKey: [] paths: /accounts: post: tags: - MerchantAccounts - QuickStart summary: Merchant Account - Create operationId: createMerchantAccount description: "Create a new account for a merchant. The merchant could be a seller or retailer or client who likes to receive and send payments." security: - AdminSecretKey: [] requestBody: content: application/json: schema: $ref: "#/components/schemas/MerchantAccountCreateRequest" responses: "200": description: Merchant Account Created content: application/json: schema: $ref: "#/components/schemas/MerchantAccountResponse" "400": description: Invalid data content: application/json: schema: $ref: "#/components/schemas/Error" example: error: type: "invalid_request_error" code: "invalid_data" message: "merchant_name can't be empty or null" "401": description: Unauthorized request content: application/json: schema: $ref: "#/components/schemas/Error" example: error: type: "invalid_request_error" code: "invalid_api_authentication" message: "Access forbidden, invalid api-key was used" /accounts/{id}: get: parameters: - in: path name: id schema: type: string required: true description: The unique identifier for the merchant account tags: - MerchantAccounts summary: Merchant Account - Retrieve operationId: retrieveMerchantAccount description: Retrieve a merchant account details. security: - AdminSecretKey: [] responses: "200": description: Merchant Account retrieved successfully content: application/json: schema: $ref: "#/components/schemas/MerchantAccountResponse" "404": description: Merchant Account does not exist in records content: application/json: schema: $ref: "#/components/schemas/Error" example: error: type: "object_not_found" code: "merchant_account_not_found" message: "Merchant Account does not exist in records" "401": description: Unauthorized request content: application/json: schema: $ref: "#/components/schemas/Error" example: error: type: "invalid_request_error" code: "invalid_api_authentication" message: "Access forbidden, invalid api-key was used" post: parameters: - in: path name: id schema: type: string required: true description: The unique identifier for the merchant account tags: - MerchantAccounts summary: Merchant Account - Update operationId: updateMerchantAccount description: "To update an existing merchant account. Helpful in updating merchant details such as email, contact details, or other configuration details like webhook, routing algorithm etc" security: - AdminSecretKey: [] requestBody: content: application/json: schema: $ref: "#/components/schemas/MerchantAccountUpdateRequest" responses: "200": description: Merchant Account Updated content: application/json: schema: $ref: "#/components/schemas/MerchantAccountResponse" "404": description: Merchant Account does not exist in records content: application/json: schema: $ref: "#/components/schemas/Error" example: error: type: "object_not_found" code: "merchant_account_not_found" message: "Merchant Account does not exist in records" "400": description: Invalid data content: application/json: schema: $ref: "#/components/schemas/Error" example: error: type: "invalid_request_error" code: "invalid_data" message: "Update Field can't be empty" "401": description: Unauthorized request content: application/json: schema: $ref: "#/components/schemas/Error" example: error: type: "invalid_request_error" code: "invalid_api_authentication" message: "Access forbidden, invalid api-key was used" delete: parameters: - in: path name: id schema: type: string required: true description: The unique identifier for the merchant account tags: - MerchantAccounts summary: Merchant Account - Delete operationId: deleteMerchantAccount description: Delete a Merchant Account security: - AdminSecretKey: [] responses: "200": description: Merchant Account deleted successfully content: application/json: schema: $ref: "#/components/schemas/MerchantAccountDeleteResponse" "404": description: Merchant Account does not exist in records content: application/json: schema: $ref: "#/components/schemas/Error" example: error: type: "object_not_found" code: "merchant_account_not_found" message: "Merchant Account does not exist in records" "401": description: Unauthorized request content: application/json: schema: $ref: "#/components/schemas/Error" example: error: type: "invalid_request_error" code: "invalid_api_authentication" message: "Access forbidden, invalid api-key was used" /customers/{customer_id}/mandates: get: parameters: - in: path name: customer_id schema: type: string required: true description: Unique customer id for which the list of mandates to be retrieved. tags: - Mandates summary: Mandate - List all mandates against a customer id operationId: listMandateDetails description: "To list the all the mandates for a customer" responses: "200": description: Customer's mandates retrieved successfully content: application/json: schema: type: array items: type: object $ref: "#/components/schemas/MandateListResponse" "404": description: Payment does not exist in records content: application/json: schema: $ref: "#/components/schemas/Error" example: error: type: "object_not_found" code: "payment_not_found" message: "Payment does not exist in records" "400": description: Invalid data content: application/json: schema: $ref: "#/components/schemas/Error" example: error: type: "invalid_request_error" code: "invalid_data" message: "Amount shall be passed as: " "401": description: Unauthorized request content: application/json: schema: $ref: "#/components/schemas/Error" example: error: type: "invalid_request_error" code: "invalid_api_authentication" message: "Access forbidden, invalid api-key was used" /customers/{customer_id}/payment_methods: get: parameters: # - in: path # name: customer_id # schema: # type: string # required: true # description: The unique ID for the Customer. - in: query name: accepted_country schema: type: array items: type: string description: | The two-letter ISO currency code example: ["US", "UK", "IN"] maxLength: 2 minLength: 2 - in: query name: accepted_currency schema: type: array items: type: string description: | The three-letter ISO currency code example: ["USD", "EUR"] - in: query name: minimum_amount schema: type: integer description: | The minimum amount accepted for processing by the particular payment method. example: 100 - in: query name: maximum_amount schema: type: integer description: | The minimum amount accepted for processing by the particular payment method. example: 10000000 - in: query name: recurring_payment_enabled schema: type: boolean description: Indicates whether the payment method is eligible for recurring payments example: true - in: query name: installment_payment_enabled schema: type: boolean description: Indicates whether the payment method is eligible for installment payments example: true security: - ApiSecretKey: [] tags: - PaymentMethods summary: List payment methods for a Customer operationId: listPaymentMethodsByCustomerId description: "To filter and list the applicable payment methods for a particular Customer ID" responses: "200": description: Payment Methods retrieved content: application/json: schema: $ref: "#/components/schemas/CustomerPaymentMethods" "404": description: Payment Methods does not exist in records content: application/json: schema: $ref: "#/components/schemas/Error" example: error: type: "object_not_found" code: "payment_method_not_found" message: "Payment Methods does not exist in records" "400": description: Invalid data content: application/json: schema: $ref: "#/components/schemas/Error" example: error: type: "invalid_request_error" code: "invalid_data" message: "accepted_currency shall be passed as: " "401": description: Unauthorized request content: application/json: schema: $ref: "#/components/schemas/Error" example: error: type: "invalid_request_error" code: "invalid_api_authentication" message: "Access forbidden, invalid api-key was used" /mandates/{id}: get: parameters: - in: path name: id schema: type: string required: true description: Unique mandate id tags: - Mandates summary: Mandate - List details of a mandate operationId: listMandateDetails description: "To list the details of a mandate" # requestBody: # content: # application/json: # schema: # $ref: "#/components/schemas/MandateListResponse" responses: "200": description: Mandate retrieved successfully content: application/json: schema: $ref: "#/components/schemas/MandateListResponse" "404": description: Mandate does not exist in records content: application/json: schema: $ref: "#/components/schemas/Error" example: error: type: "object_not_found" code: "payment_not_found" message: "Payment does not exist in records" "401": description: Unauthorized request content: application/json: schema: $ref: "#/components/schemas/Error" example: error: type: "invalid_request_error" code: "invalid_api_authentication" message: "Access forbidden, invalid api-key was used" /mandates/{id}/revoke: post: parameters: - in: path name: id schema: type: string required: true description: Unique mandate id tags: - Mandates summary: Mandate - Revoke a mandate operationId: revokeMandateDetails description: "To revoke a mandate registered against a customer" # requestBody: # content: # application/json: # schema: # type: object # properties: # command: # type: string # description: The command for revoking a mandate. # example: "revoke" responses: "200": description: Mandate Revoked content: application/json: schema: type: object properties: mandate_id: type: string description: | The unique id corresponding to the mandate. example: "mandate_end38934n12s923d0" status: type: string description: The status of the mandate. example: "revoked" "404": description: Mandate does not exist in records content: application/json: schema: $ref: "#/components/schemas/Error" example: error: type: "object_not_found" code: "payment_not_found" message: "Payment does not exist in records" "400": description: Invalid data content: application/json: schema: $ref: "#/components/schemas/Error" example: error: type: "invalid_request_error" code: "invalid_data" message: "command shall be passed as: " # "400": # description: Invalid parameter # content: # application/json: # schema: # $ref: "#/components/responses/BadRequestError" # example: # error: # type: "invalid_request_error" # code: "invalid_parameter" # message: "The return_url cannot be passed unless confirm is set to true" "401": description: Unauthorized request content: application/json: schema: $ref: "#/components/schemas/Error" example: error: type: "invalid_request_error" code: "invalid_api_authentication" message: "Access forbidden, invalid api-key was used" /account/{account_id}/connectors: post: parameters: - in: path name: account_id schema: type: string required: true description: The unique identifier for the merchant account tags: - PaymentConnectors - QuickStart summary: Payment Connector - Create operationId: createPaymentConnector description: "Create a new Payment Connector for the merchant account. The connector could be a payment processor / facilitator / acquirer or specialized services like Fraud / Accounting etc." security: - AdminSecretKey: [] requestBody: content: application/json: schema: $ref: "#/components/schemas/PaymentConnectorCreateRequest" responses: "200": description: Payment Connector Created content: application/json: schema: $ref: "#/components/schemas/PaymentConnectorResponse" "400": description: Invalid data content: application/json: schema: $ref: "#/components/schemas/Error" example: error: type: "invalid_request_error" code: "invalid_data" message: "connector_name can't be empty or null" "401": description: Unauthorized request content: application/json: schema: $ref: "#/components/schemas/Error" example: error: type: "invalid_request_error" code: "invalid_api_authentication" message: "Access forbidden, invalid api-key was used" /account/{account_id}/connectors/{connector_id}: get: parameters: - in: path name: account_id schema: type: string required: true description: The unique identifier for the merchant account - in: path name: connector_id schema: type: string required: true description: The unique identifier for the payment connector tags: - PaymentConnectors summary: Payment Connector - Retrieve operationId: retrievePaymentConnector description: Retrieve Payment Connector details. security: - AdminSecretKey: [] responses: "200": description: Payment Connector retrieved successfully content: application/json: schema: $ref: "#/components/schemas/PaymentConnectorResponse" "404": description: Payment Connector does not exist in records content: application/json: schema: $ref: "#/components/schemas/Error" example: error: type: "object_not_found" code: "payment_connector_not_found" message: "Payment Connector does not exist in records" "401": description: Unauthorized request content: application/json: schema: $ref: "#/components/schemas/Error" example: error: type: "invalid_request_error" code: "invalid_api_authentication" message: "Access forbidden, invalid api-key was used" post: parameters: - in: path name: id1 schema: type: string required: true description: The unique identifier for the merchant account - in: path name: id2 schema: type: string required: true description: The unique identifier for the payment connector tags: - PaymentConnectors summary: Payment Connector - Update operationId: updatePaymentConnector description: "To update an existing Payment Connector. Helpful in enabling / disabling different payment methods and other settings for the connector etc" security: - AdminSecretKey: [] requestBody: content: application/json: schema: $ref: "#/components/schemas/PaymentConnectorUpdateRequest" responses: "200": description: Payment Connector Updated content: application/json: schema: $ref: "#/components/schemas/PaymentConnectorResponse" "404": description: Payment Connector does not exist in records content: application/json: schema: $ref: "#/components/schemas/Error" example: error: type: "object_not_found" code: "payment_connector_not_found" message: "Payment Connector does not exist in records" "400": description: Invalid data content: application/json: schema: $ref: "#/components/schemas/Error" example: error: type: "invalid_request_error" code: "invalid_data" message: "Update Field can't be empty" "401": description: Unauthorized request content: application/json: schema: $ref: "#/components/schemas/Error" example: error: type: "invalid_request_error" code: "invalid_api_authentication" message: "Access forbidden, invalid api-key was used" delete: parameters: - in: path name: id1 schema: type: string required: true description: The unique identifier for the merchant account - in: path name: id2 schema: type: string required: true description: The unique identifier for the payment connector tags: - PaymentConnectors summary: Payment Connector - Delete operationId: deletePaymentConnector description: Delete or Detach a Payment Connector from Merchant Account security: - AdminSecretKey: [] responses: "200": description: Payment Connector detached successfully content: application/json: schema: $ref: "#/components/schemas/PaymentConnectorDeleteResponse" "404": description: Payment Connector does not exist in records content: application/json: schema: $ref: "#/components/schemas/Error" example: error: type: "object_not_found" code: "payment_connector_not_found" message: "Payment Connector does not exist in records" "401": description: Unauthorized request content: application/json: schema: $ref: "#/components/schemas/Error" example: error: type: "invalid_request_error" code: "invalid_api_authentication" message: "Access forbidden, invalid api-key was used" /customers: post: tags: - Customers summary: Create Customer operationId: createCustomer description: Create a customer object and store the customer details to be reused for future payments. Incase the customer already exists in the system, this API will respond with the customer details. requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/CustomerCreateRequest" example: customer_id: "cus_udst2tfldj6upmye2reztkmm4i" email: "guest@example.com" name: "John Doe" phone: "999999999" phone_country_code: "+65" description: "First customer" address: city: "Bangalore" country: "IN" line1: "Juspay router" line2: "Koramangala" line3: "Stallion" state: "Karnataka" zip: "560095" first_name: "John" last_name: "Doe" metadata: udf1: "value1" new_customer: "true" login_date: "2019-09-10T10:11:12Z" responses: "200": description: Customer created successfully content: application/json: schema: $ref: "#/components/schemas/CustomerCreateResponse" example: customer_id: "cus_udst2tfldj6upmye2reztkmm4i" email: "guest@example.com" name: "John Doe" phone: "999999999" phone_country_code: "+65" description: "First customer" address: city: "Bangalore" country: "IN" line1: "Juspay router" line2: "Koramangala" line3: "Stallion" state: "Karnataka" zip: "560095" first_name: "John" last_name: "Doe" metadata: udf1: "value1" new_customer: "true" login_date: "2019-09-10T10:11:12Z" "401": description: Bad request content: application/json: schema: $ref: "#/components/schemas/Error" example: error: type: "invalid_request_error" code: "invalid_api_authentication" message: "Access forbidden, invalid api-key was used" /customers/{id}: get: parameters: - in: path name: id schema: type: string required: true description: unique customer id tags: - Customers summary: Retrieve Customer operationId: retrieveCustomer description: Retrieve a customer's details. responses: "200": description: Customer retrieved successfully content: application/json: schema: $ref: "#/components/schemas/CustomerCreateResponse" example: customer_id: "cus_udst2tfldj6upmye2reztkmm4i" email: "guest@example.com" name: "John Doe" phone: "999999999" phone_country_code: "+65" description: "First customer" address: city: "Bangalore" country: "IN" line1: "Juspay router" line2: "Koramangala" line3: "Stallion" state: "Karnataka" zip: "560095" first_name: "John" last_name: "Doe" metadata: udf1: "value1" new_customer: "true" login_date: "2019-09-10T10:11:12Z" "404": description: Customer does not exist in records content: application/json: schema: $ref: "#/components/schemas/Error" example: error: type: "object_not_found" code: "customer_not_found" message: "Customer does not exist in records" "401": description: Unauthorized request content: application/json: schema: $ref: "#/components/schemas/Error" example: error: type: "invalid_request_error" code: "invalid_api_authentication" message: "Access forbidden, invalid api-key was used" post: parameters: - in: path name: id schema: type: string required: true description: unique customer id tags: - Customers summary: Update Customer operationId: updateCustomer description: Updates the customer's details in a customer object. requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/CustomerUpdateRequest" responses: "200": description: Customer created successfully content: application/json: schema: $ref: "#/components/schemas/CustomerCreateResponse" "404": description: Customer does not exist in records content: application/json: schema: $ref: "#/components/schemas/Error" example: error: type: "object_not_found" code: "customer_not_found" message: "Customer does not exist in records" "401": description: Unauthorized request content: application/json: schema: $ref: "#/components/schemas/Error" example: error: type: "invalid_request_error" code: "invalid_api_authentication" message: "Access forbidden, invalid api-key was used" delete: parameters: - in: path name: id schema: type: string required: true description: unique customer id tags: - Customers summary: Delete Customer operationId: deleteCustomer description: Delete a customer record. responses: "200": description: Customer deleted successfully content: application/json: schema: $ref: "#/components/schemas/CustomerDeleteResponse" "404": description: Customer does not exist in records content: application/json: schema: $ref: "#/components/schemas/Error" example: error: type: "object_not_found" code: "customer_not_found" message: "Customer does not exist in records" "401": description: Unauthorized request content: application/json: schema: $ref: "#/components/schemas/Error" example: error: type: "invalid_request_error" code: "invalid_api_authentication" message: "Access forbidden, invalid api-key was used" /payments: post: tags: - Payments - QuickStart summary: Payments - Create operationId: createPayment description: "To process a payment you will have to create a payment, attach a payment method and confirm. Depending on the user journey you wish to achieve, you may opt to all the steps in a single request or in a sequence of API request using following APIs: (i) Payments - Update, (ii) Payments - Confirm, and (iii) Payments - Capture" requestBody: content: application/json: schema: oneOf: - $ref: "#/components/schemas/PaymentsCreateRequest" responses: "200": description: Payment created content: application/json: schema: oneOf: - $ref: "#/components/schemas/PaymentsCreateResponse" "400": description: Missing Mandatory fields content: application/json: schema: $ref: "#/components/schemas/Error" example: error: type: "invalid_request_error" code: "parameter_missing" message: "Missing required param: " "401": description: Unauthorized request content: application/json: schema: $ref: "#/components/schemas/Error" example: error: type: "invalid_request_error" code: "invalid_api_authentication" message: "Access forbidden, invalid api-key was used" /payments/{id}: post: parameters: - in: path name: id schema: type: string required: true description: unique payment id tags: - Payments summary: Payments - Update operationId: updatePayment description: "To update the properties of a PaymentIntent object. This may include attaching a payment method, or attaching customer object or metadata fields after the Payment is created " requestBody: content: application/json: schema: $ref: "#/components/schemas/PaymentsUpdateRequest" example: amount: 6540 currency: "USD" capture_method: "automatic" capture_on: "2022-09-10T10:11:12Z" amount_to_capture: 6540 amount_capturable: 6540 customer_id: "cus_udst2tfldj6upmye2reztkmm4i" email: "guest@example.com" name: "John Doe" phone: "999999999" phone_country_code: "+65" description: "Its my first payment request" setup_future_usage: "optional" authentication_type: "no_three_ds" payment_method: "card" save_payment_method: true payment_method_data: card: card_number: "4242424242424242" card_exp_month: "10" card_exp_year: "35" card_holder_name: "John Doe" card_cvc: "123" statement_descriptor_name: "Juspay" statement_descriptor_suffix: "Router" shipping: city: "Bangalore" country: "IN" line1: "Juspay router" line2: "Koramangala" line3: "Stallion" state: "Karnataka" zip: "560095" first_name: "John" last_name: "Doe" billing: city: "Bangalore" country: "IN" line1: "Juspay router" line2: "Koramangala" line3: "Stallion" state: "Karnataka" zip: "560095" first_name: "John" last_name: "Doe" metadata: udf1: "value1" new_customer: "true" login_date: "2019-09-10T10:11:12Z" responses: "200": description: Payment updated content: application/json: schema: $ref: "#/components/schemas/PaymentsCreateResponse" example: payment_id: "pay_mbabizu24mvu3mela5njyhpit4" amount: 6540 currency: "USD" status: "requires_customer_action" merchant_id: "juspay_merchant" capture_method: "automatic" capture_on: "2022-09-10T10:11:12Z" amount_to_capture: 6540 amount_capturable: 6540 amount_received: 0 customer_id: "cus_udst2tfldj6upmye2reztkmm4i" email: "guest@example.com" name: "John Doe" phone: "999999999" phone_country_code: "+65" description: "Its my first payment request" return_url: "http://example.com/payments" setup_future_usage: "optional" authentication_type: "no_three_ds" shipping: city: "Bangalore" country: "IN" line1: "Juspay router" line2: "Koramangala" line3: "Stallion" state: "Karnataka" zip: "560095" first_name: "John" last_name: "Doe" billing: city: "Bangalore" country: "IN" line1: "Juspay router" line2: "Koramangala" line3: "Stallion" state: "Karnataka" zip: "560095" first_name: "John" last_name: "Doe" next_action: type: "redirect_to_url" redirect_to_url: "https://pg-redirect-page.com" metadata: udf1: "value1" new_customer: "true" login_date: "2019-09-10T10:11:12Z" "404": description: Payment does not exist in records content: application/json: schema: $ref: "#/components/schemas/Error" example: error: type: "object_not_found" code: "payment_not_found" message: "Payment does not exist in records" "400": description: Invalid data content: application/json: schema: $ref: "#/components/schemas/Error" example: error: type: "invalid_request_error" code: "invalid_data" message: "Amount shall be passed as: " "401": description: Unauthorized request content: application/json: schema: $ref: "#/components/schemas/Error" example: error: type: "invalid_request_error" code: "invalid_api_authentication" message: "Access forbidden, invalid api-key was used" get: parameters: - in: path name: id schema: type: string required: true description: unique payment id tags: - Payments - QuickStart summary: Payments - Retrieve operationId: retrievePayment description: "To retrieve the properties of a Payment. This may be used to get the status of a previously initiated payment or next action for an ongoing payment" responses: "200": description: Payment retrieved successfully content: application/json: schema: $ref: "#/components/schemas/PaymentsCreateResponse" example: payment_id: "pay_mbabizu24mvu3mela5njyhpit4" amount: 6540 currency: "USD" status: "requires_customer_action" merchant_id: "juspay_merchant" capture_method: "automatic" capture_on: "2022-09-10T10:11:12Z" amount_to_capture: 6540 amount_capturable: 6540 customer_id: "cus_udst2tfldj6upmye2reztkmm4i" email: "guest@example.com" name: "John Doe" phone: "999999999" phone_country_code: "+65" description: "Its my first payment request" return_url: "http://example.com/payments" setup_future_usage: "optional" authentication_type: "no_three_ds" shipping: city: "Bangalore" country: "IN" line1: "Juspay router" line2: "Koramangala" line3: "Stallion" state: "Karnataka" zip: "560095" first_name: "John" last_name: "Doe" billing: city: "Bangalore" country: "IN" line1: "Juspay router" line2: "Koramangala" line3: "Stallion" state: "Karnataka" zip: "560095" first_name: "John" last_name: "Doe" next_action: type: "redirect_to_url" redirect_to_url: "https://pg-redirect-page.com" metadata: udf1: "value1" new_customer: "true" login_date: "2019-09-10T10:11:12Z" "404": description: Payment does not exist in records content: application/json: schema: $ref: "#/components/schemas/Error" example: error: type: "object_not_found" code: "payment_not_found" message: "Payment does not exist in records" "401": description: Unauthorized request content: application/json: schema: $ref: "#/components/schemas/Error" example: error: type: "invalid_request_error" code: "invalid_api_authentication" message: "Access forbidden, invalid api-key was used" /payments/{id}/capture: post: parameters: - in: path name: id schema: type: string required: true description: unique payment id tags: - Payments summary: Payments - Capture operationId: capturePayment description: "To capture the funds for an uncaptured payment" requestBody: content: application/json: schema: $ref: "#/components/schemas/PaymentsCaptureRequest" example: amount_to_capture: 6540 statement_descriptor_name: "Juspay" statement_descriptor_suffix: "Router" responses: "200": description: Payment captured content: application/json: schema: $ref: "#/components/schemas/PaymentsCreateResponse" example: payment_id: "pay_mbabizu24mvu3mela5njyhpit4" amount: 6540 currency: "USD" status: "succeeded" merchant_id: "juspay_merchant" capture_method: "automatic" capture_on: "2022-09-10T10:11:12Z" amount_to_capture: 6540 amount_capturable: 0 customer_id: "cus_udst2tfldj6upmye2reztkmm4i" email: "guest@example.com" name: "John Doe" phone: "999999999" phone_country_code: "+65" description: "Its my first payment request" return_url: "http://example.com/payments" setup_future_usage: "optional" authentication_type: "no_three_ds" shipping: city: "Bangalore" country: "IN" line1: "Juspay router" line2: "Koramangala" line3: "Stallion" state: "Karnataka" zip: "560095" first_name: "John" last_name: "Doe" billing: city: "Bangalore" country: "IN" line1: "Juspay router" line2: "Koramangala" line3: "Stallion" state: "Karnataka" zip: "560095" first_name: "John" last_name: "Doe" next_action: null metadata: udf1: "value1" new_customer: "true" login_date: "2019-09-10T10:11:12Z" "404": description: Payment does not exist in records content: application/json: schema: $ref: "#/components/schemas/Error" example: error: type: "object_not_found" code: "payment_not_found" message: "Payment does not exist in records" "400": description: Invalid data content: application/json: schema: $ref: "#/components/schemas/Error" example: error: type: "invalid_request_error" code: "invalid_data" message: "Amount shall be passed as: " "401": description: Unauthorized request content: application/json: schema: $ref: "#/components/schemas/Error" example: error: type: "invalid_request_error" code: "invalid_api_authentication" message: "Access forbidden, invalid api-key was used" /payments/{id}/confirm: post: parameters: - in: path name: id schema: type: string required: true description: unique payment id tags: - Payments summary: Payments - Confirm operationId: confirmPayment description: "This API is to confirm the payment request and forward payment to the payment processor. This API provides more granular control upon when the API is forwarded to the payment processor. Alternatively you can confirm the payment within the Payments-Create API" requestBody: content: application/json: schema: $ref: "#/components/schemas/PaymentsConfirmRequest" example: return_url: "http://example.com/payments" setup_future_usage: "optional" authentication_type: "no_three_ds" payment_method: "card" save_payment_method: true payment_method_data: card: card_number: "4242424242424242" card_exp_month: "10" card_exp_year: "35" card_holder_name: "John Doe" card_cvc: "123" shipping: city: "Bangalore" country: "IN" line1: "Juspay router" line2: "Koramangala" line3: "Stallion" state: "Karnataka" zip: "560095" first_name: "John" last_name: "Doe" billing: city: "Bangalore" country: "IN" line1: "Juspay router" line2: "Koramangala" line3: "Stallion" state: "Karnataka" zip: "560095" first_name: "John" last_name: "Doe" responses: "200": description: Payment confirmed content: application/json: schema: $ref: "#/components/schemas/PaymentsCreateResponse" example: amount: 6540 currency: "USD" confirm: true payment_id: "pay_mbabizu24mvu3mela5njyhpit4" merchant_id: "juspay_merchant" capture_method: "automatic" capture_on: "2022-09-10T10:11:12Z" amount_to_capture: 6540 customer_id: "cus_udst2tfldj6upmye2reztkmm4i" email: "guest@example.com" name: "John Doe" phone: "999999999" phone_country_code: "+65" description: "Its my first payment request" return_url: "http://example.com/payments" setup_future_usage: "optional" authentication_type: "no_three_ds" payment_method: "card" save_payment_method: true payment_method_data: card: card_number: "4242424242424242" card_exp_month: "10" card_exp_year: "35" card_holder_name: "John Doe" card_cvc: "123" statement_descriptor_name: "Juspay" statement_descriptor_suffix: "Router" shipping: city: "Bangalore" country: "IN" line1: "Juspay router" line2: "Koramangala" line3: "Stallion" state: "Karnataka" zip: "560095" first_name: "John" last_name: "Doe" billing: city: "Bangalore" country: "IN" line1: "Juspay router" line2: "Koramangala" line3: "Stallion" state: "Karnataka" zip: "560095" first_name: "John" last_name: "Doe" metadata: udf1: "value1" new_customer: "true" login_date: "2019-09-10T10:11:12Z" "404": description: Payment does not exist in records content: application/json: schema: $ref: "#/components/schemas/Error" example: error: type: "object_not_found" code: "payment_not_found" message: "Payment does not exist in records" "400": description: Invalid data content: application/json: schema: $ref: "#/components/schemas/Error" example: error: type: "invalid_request_error" code: "invalid_data" message: "cancellation_reason shall be passed as: " "401": description: Unauthorized request content: application/json: schema: $ref: "#/components/schemas/Error" example: error: type: "invalid_request_error" code: "invalid_api_authentication" message: "Access forbidden, invalid api-key was used" /payments/{id}/cancel: post: parameters: - in: path name: id schema: type: string required: true description: unique payment id tags: - Payments summary: Payments - Cancel operationId: cancelPayment description: "A Payment could can be cancelled when it is in one of these statuses: requires_payment_method, requires_capture, requires_confirmation, requires_customer_action" requestBody: content: application/json: schema: $ref: "#/components/schemas/PaymentsCancelRequest" example: cancellation_reason: "Payment attempt expired" responses: "200": description: Payment cancelled content: application/json: schema: $ref: "#/components/schemas/PaymentsCreateResponse" example: payment_id: "pay_mbabizu24mvu3mela5njyhpit4" amount: 6540 currency: "USD" cancellation_reason: "Payment attempt expired" status: "cancelled" merchant_id: "juspay_merchant" capture_method: "automatic" capture_on: "2022-09-10T10:11:12Z" amount_to_capture: 6540 amount_capturable: 0 customer_id: "cus_udst2tfldj6upmye2reztkmm4i" email: "guest@example.com" name: "John Doe" phone: "999999999" phone_country_code: "+65" description: "Its my first payment request" return_url: "http://example.com/payments" setup_future_usage: "optional" authentication_type: "no_three_ds" shipping: city: "Bangalore" country: "IN" line1: "Juspay router" line2: "Koramangala" line3: "Stallion" state: "Karnataka" zip: "560095" first_name: "John" last_name: "Doe" billing: city: "Bangalore" country: "IN" line1: "Juspay router" line2: "Koramangala" line3: "Stallion" state: "Karnataka" zip: "560095" first_name: "John" last_name: "Doe" next_action: null metadata: udf1: "value1" new_customer: "true" login_date: "2019-09-10T10:11:12Z" "404": description: Payment does not exist in records content: application/json: schema: $ref: "#/components/schemas/Error" example: error: type: "object_not_found" code: "payment_not_found" message: "Payment does not exist in records" "400": description: Invalid data content: application/json: schema: $ref: "#/components/schemas/Error" example: error: type: "invalid_request_error" code: "invalid_data" message: "cancellation_reason shall be passed as: " "401": description: Unauthorized request content: application/json: schema: $ref: "#/components/schemas/Error" example: error: type: "invalid_request_error" code: "invalid_api_authentication" message: "Access forbidden, invalid api-key was used" /refunds: post: tags: - Refunds - QuickStart summary: Refunds - Create operationId: createRefunds description: "To create a refund against an already processed payment" requestBody: content: application/json: schema: $ref: "#/components/schemas/RefundsCreateRequest" example: payment_id: "pay_mbabizu24mvu3mela5njyhpit4" refund_id: "a8537066-2569-4ac4-a7d3-87453387b09b" amount: 100 currency: "USD" reason: "Customer returned product" metadata: udf1: "value1" new_customer: "true" login_date: "2019-09-10T10:11:12Z" responses: "200": description: Refund created content: application/json: schema: $ref: "#/components/schemas/RefundsObject" example: payment_id: "pay_mbabizu24mvu3mela5njyhpit4" refund_id: "a8537066-2569-4ac4-a7d3-87453387b09b" amount: 100 status: "pending" currency: "USD" reason: "Customer returned product" metadata: udf1: "value1" new_customer: "true" login_date: "2019-09-10T10:11:12Z" created_at: "2022-09-10T10:11:12Z" "400": description: Missing Mandatory fields content: application/json: schema: $ref: "#/components/schemas/Error" example: error: type: "invalid_request_error" code: "parameter_missing" message: "Missing required param: " /refunds/{id}: post: parameters: - in: path name: id schema: type: string required: true description: unique refund id tags: - Refunds summary: Refunds - Update operationId: updateRefund description: "To update the properties of a Refund object. This may include attaching a reason for the refund or metadata fields" requestBody: content: application/json: schema: $ref: "#/components/schemas/RefundsUpdateRequest" example: reason: "Customer returned product" metadata: udf1: "value1" new_customer: "true" login_date: "2019-09-10T10:11:12Z" responses: "200": description: Refund updated content: application/json: schema: $ref: "#/components/schemas/RefundsObject" example: payment_id: "pay_mbabizu24mvu3mela5njyhpit4" refund_id: "a8537066-2569-4ac4-a7d3-87453387b09b" amount: 100 status: "pending" currency: "USD" reason: "Customer returned product" metadata: udf1: "value1" new_customer: "true" login_date: "2019-09-10T10:11:12Z" created_at: "2022-09-10T10:11:12Z" "404": description: Refund does not exist in records content: application/json: schema: $ref: "#/components/schemas/Error" example: error: type: "object_not_found" code: "refund_not_found" message: "Refund does not exist in records" "400": description: Invalid data content: application/json: schema: $ref: "#/components/schemas/Error" example: error: type: "invalid_request_error" code: "invalid_data" message: "Amount shall be passed as: " "401": description: Unauthorized request content: application/json: schema: $ref: "#/components/schemas/Error" example: error: type: "invalid_request_error" code: "invalid_api_authentication" message: "Access forbidden, invalid api-key was used" get: parameters: - in: path name: id schema: type: string required: true description: unique refund id tags: - Refunds - QuickStart summary: Refunds - Retrieve operationId: retrieveRefund description: "To retrieve the properties of a Refund. This may be used to get the status of a previously initiated payment or next action for an ongoing payment" responses: "200": description: Refund retrieved successfully content: application/json: schema: $ref: "#/components/schemas/RefundsObject" example: payment_id: "pay_mbabizu24mvu3mela5njyhpit4" refund_id: "a8537066-2569-4ac4-a7d3-87453387b09b" amount: 100 status: "pending" currency: "USD" reason: "Customer returned product" metadata: udf1: "value1" new_customer: "true" login_date: "2019-09-10T10:11:12Z" created_at: "2022-09-10T10:11:12Z" "404": description: Refund does not exist in records content: application/json: schema: $ref: "#/components/schemas/Error" example: error: type: "object_not_found" code: "refund_not_found" message: "Refund does not exist in records" "401": description: Unauthorized request content: application/json: schema: $ref: "#/components/schemas/Error" example: error: type: "invalid_request_error" code: "invalid_api_authentication" message: "Access forbidden, invalid api-key was used" /payment_methods: post: tags: - PaymentMethods summary: PaymentMethods - Create operationId: createPaymentMethodForCustomer description: "To create a payment method against a customer object. In case of cards, this API could be used only by PCI compliant merchants" requestBody: content: application/json: schema: $ref: "#/components/schemas/PaymentMethodsCreateRequest" responses: "200": description: Payment Method Created content: application/json: schema: $ref: "#/components/schemas/PaymentMethodsResponseObject" "400": description: Invalid data content: application/json: schema: $ref: "#/components/schemas/Error" example: error: type: "invalid_request_error" code: "invalid_data" message: "accepted_country shall be passed as: " "401": description: Unauthorized request content: application/json: schema: $ref: "#/components/schemas/Error" example: error: type: "invalid_request_error" code: "invalid_api_authentication" message: "Access forbidden, invalid api-key was used" /payment_methods/{id}: post: parameters: - in: path name: id schema: type: string required: true description: The unique identifier for the payment method tags: - PaymentMethods summary: PaymentMethods - Update operationId: updatePaymentMethodForCustomer description: "To update an existing a payment method attached to a customer object. This API is useful for use cases such as updating the card number for expired cards, to prevent discontinuity in recurring payments" requestBody: content: application/json: schema: $ref: "#/components/schemas/PaymentMethodsUpdateRequest" responses: "200": description: Payment Method Updated content: application/json: schema: $ref: "#/components/schemas/PaymentMethodsResponseObject" "404": description: Payment Method does not exist in records content: application/json: schema: $ref: "#/components/schemas/Error" example: error: type: "object_not_found" code: "payment_method_not_found" message: "Payment Method does not exist in records" "400": description: Invalid data content: application/json: schema: $ref: "#/components/schemas/Error" example: error: type: "invalid_request_error" code: "invalid_data" message: "accepted_country shall be passed as: " "401": description: Unauthorized request content: application/json: schema: $ref: "#/components/schemas/Error" example: error: type: "invalid_request_error" code: "invalid_api_authentication" message: "Access forbidden, invalid api-key was used" /payment_methods/{id}/detach: post: parameters: - in: path name: id schema: type: string required: true description: The unique identifier for the payment method tags: - PaymentMethods summary: Delete PaymentMethods operationId: deletePaymentMethods description: Detaches a PaymentMethod object from a Customer. responses: "200": description: Payment Method detached successfully content: application/json: schema: $ref: "#/components/schemas/PaymentMethodDeleteResponse" "404": description: Payment Method does not exist in records content: application/json: schema: $ref: "#/components/schemas/Error" example: error: type: "object_not_found" code: "payment_method_not_found" message: "Payment Method does not exist in records" "401": description: Unauthorized request content: application/json: schema: $ref: "#/components/schemas/Error" example: error: type: "invalid_request_error" code: "invalid_api_authentication" message: "Access forbidden, invalid api-key was used" /payment_methods/{merchant_id}: get: parameters: - in: query name: accepted_country schema: type: array items: type: string description: | The two-letter ISO currency code example: [US, UK, IN] maxLength: 2 minLength: 2 - in: query name: accepted_currency schema: type: array items: type: string description: | The three-letter ISO currency code example: [USD, EUR] - in: query name: minimum_amount schema: type: integer description: The minimum amount accepted for processing by the particular payment method. example: 100 - in: query name: maximum_amount schema: type: integer description: The minimum amount accepted for processing by the particular payment method. example: 10000000 - in: query name: recurring_payment_enabled schema: type: boolean description: Indicates whether the payment method is eligible for recurring payments example: true - in: query name: installment_payment_enabled schema: type: boolean description: Indicates whether the payment method is eligible for installment payments example: true tags: - PaymentMethods summary: List payment methods for a Merchant operationId: listPaymentMethodsByMerchantId description: "To filter and list the applicable payment methods for a particular merchant id." responses: "200": description: Payment Methods retrieved content: application/json: schema: $ref: "#/components/schemas/ArrayOfMerchantPaymentMethods" "404": description: Payment Methods does not exist in records content: application/json: schema: $ref: "#/components/schemas/Error" example: error: type: "object_not_found" code: "payment_method_not_found" message: "Payment Methods does not exist in records" "400": description: Invalid data content: application/json: schema: $ref: "#/components/schemas/Error" example: error: type: "invalid_request_error" code: "invalid_data" message: "accepted_currency shall be passed as: " "401": description: Unauthorized request content: application/json: schema: $ref: "#/components/schemas/Error" example: error: type: "invalid_request_error" code: "invalid_api_authentication" message: "Access forbidden, invalid api-key was used" components: schemas: ArrayOfMerchantPaymentMethods: type: array items: properties: payment_method: type: string $ref: "#/components/schemas/PaymentMethod" example: card payment_method_types: type: array items: $ref: "#/components/schemas/PaymentMethodType" example: [CREDIT] payment_method_issuers: type: array description: List of payment method issuers to be enabled for this payment method items: type: string example: [CHASE, WELLS_FARGO] payment_method_issuer_codes: type: string description: | A standard code representing the issuer of payment method example: [PM_CHASE, PM_WELLS] payment_schemes: type: array description: List of payment schemes accepted or has the processing capabilities of the processor items: $ref: "#/components/schemas/PaymentSchemes" example: [MASTER, VISA, DINERS] accepted_currencies: type: array description: List of currencies accepted or has the processing capabilities of the processor items: $ref: "#/components/schemas/CurrencyISO" example: [USD, EUR, AED] accepted_countries: type: array description: List of Countries accepted or has the processing capabilities of the processor items: $ref: "#/components/schemas/CountryISO" example: [US, IN] minimum_amount: type: integer description: Minimum amount supported by the processor. To be represented in the lowest denomination of the target currency (For example, for USD it should be in cents) example: 1 maximum_amount: type: integer description: Maximum amount supported by the processor. To be represented in the lowest denomination of the target currency (For example, for USD it should be in cents) example: null recurring_enabled: type: boolean description: Boolean to enable recurring payments / mandates. Default is true. example: true installment_payment_enabled: type: boolean description: Boolean to enable installment / EMI / BNPL payments. Default is true. example: true payment_experience: type: array description: Type of payment experience enabled with the connector items: $ref: "#/components/schemas/NextAction" example: ["redirect_to_url"] # payment_method: # type: string # description: | # The type of payment method use for the payment. # enum: # - card # - payment_container # - bank_transfer # - bank_debit # - pay_later # - upi # - netbanking # example: card # payment_method_type: # type: string # description: | # This is a sub-category of payment method. # enum: # - credit_card # - debit_card # - upi_intent # - upi_collect # - credit_card_installments # - pay_later_installments # example: credit_card # payment_method_issuer: # type: string # description: | # The name of the bank/ provider issuing the payment method to the end user # example: Citibank # payment_method_issuer_code: # type: string # description: | # A standard code representing the issuer of payment method # example: PM_CHASE # accepted_country: # type: array # items: # type: string # description: | # The two-letter ISO currency code # example: [US, UK, IN] # maxLength: 2 # minLength: 2 # accepted_currency: # type: array # items: # type: string # description: | # The three-letter ISO currency code # example: [USD, EUR] # minimum_amount: # type: integer # description: | # The minimum amount accepted for processing by the particular payment method. # example: 100 # maximum_amount: # type: integer # description: | # The minimum amount accepted for processing by the particular payment method. # example: 10000000 # recurring_payment_enabled: # type: boolean # description: Indicates whether the payment method is eligible for recurring payments # example: true # installment_payment_enabled: # type: boolean # description: Indicates whether the payment method is eligible for installment payments # example: true # payment_experience: # type: array # items: # type: string # description: "This indicates type of next_action (refer the response of Payment Create ) that is required in order to complete the payment with inputs from the user. This may involve actions such as redirecting the user to a URL, displaying a QR code, invoking the SDK client" # enum: # - redirect_to_url # - display_qr_code # - invoke_sdk_client # example: ["redirect_to_url", "display_qr_code"] CustomerPaymentMethods: type: object properties: enabled_payment_methods: type: array items: type: object $ref: "#/components/schemas/PaymentMethodsEnabled" customer_payment_methods: type: array items: type: object description: Refers to the Parent Merchant ID if the merchant being created is a sub-merchant $ref: "#/components/schemas/PaymentMethodsResponseObject" # ArrayOfCustomerPaymentMethods: # type: array # items: # type: object # properties: # payment_method_id: # type: string # description: | # The id corresponding to the payment method. # example: "pm_end38934n12s923d0" # payment_method: # type: string # description: | # The type of payment method use for the payment. # enum: # - card # - payment_container # - bank_transfer # - bank_debit # - pay_later # - upi # - netbanking # example: card # payment_method_type: # type: string # description: | # This is a sub-category of payment method. # enum: # - credit_card # - debit_card # - upi_intent # - upi_collect # - credit_card_installments # - pay_later_installments # example: credit_card # payment_method_issuer: # type: string # description: | # The name of the bank/ provider issuing the payment method to the end user # example: Citibank # payment_method_issuer_code: # type: string # description: | # A standard code representing the issuer of payment method # example: PM_CHASE # payment_scheme: # type: array # items: # type: string # description: | # The network scheme to which the payment method belongs # example: [MASTER, VISA] # accepted_country: # type: array # items: # type: string # description: | # The two-letter ISO currency code # example: [US, UK, IN] # maxLength: 2 # minLength: 2 # accepted_currency: # type: array # items: # type: string # description: | # The three-letter ISO currency code # example: [USD, EUR] # minimum_amount: # type: integer # description: | # The minimum amount accepted for processing by the particular payment method. # example: 100 # maximum_amount: # type: integer # description: | # The minimum amount accepted for processing by the particular payment method. # example: 10000000 # recurring_payment_enabled: # type: boolean # description: Indicates whether the payment method is eligible for recurring payments # example: true # installment_payment_enabled: # type: boolean # description: Indicates whether the payment method is eligible for installment payments # example: true # payment_experience: # type: array # items: # type: string # description: "This indicates type of next_action (refer the response of Payment Create ) that is required in order to complete the payment with inputs from the user. This may involve actions such as redirecting the user to a URL, displaying a QR code, invoking the SDK client" # enum: # - redirect_to_url # - display_qr_code # - invoke_sdk_client # example: ["redirect_to_url", "display_qr_code"] # card: # description: The card identifier information to be displayed on the user interface # $ref: "#/components/schemas/CardPaymentMethodResponse" # metadata: # type: object # description: You can specify up to 50 keys, with key names up to 40 characters long and values up to 500 characters long. Metadata is useful for storing additional, structured information on an object. # maxLength: 255 # example: { "city": "NY", "unit": "245" } Address: type: object properties: line1: type: string description: The first line of the address maxLength: 200 example: Juspay Router line2: type: string description: The second line of the address maxLength: 200 example: Koramangala line3: type: string description: The second line of the address maxLength: 200 example: Stallion city: type: string description: The address city maxLength: 50 example: Bangalore state: type: string description: The address state maxLength: 50 example: Karnataka zip: type: string description: The address zip/postal code maxLength: 50 example: "560095" country: type: string description: The two-letter ISO country code example: IN maxLength: 2 minLength: 2 CustomerCreateRequest: type: object description: The customer details properties: customer_id: type: string description: The identifier for the customer object. If not provided the customer ID will be autogenerated. maxLength: 255 example: cus_y3oqhf46pyzuxjbcn2giaqnb44 email: type: string format: email description: The customer's email address maxLength: 255 example: JohnTest@test.com name: type: string description: The customer's name maxLength: 255 example: John Test phone_country_code: type: string description: The country code for the customer phone number maxLength: 255 example: "+65" phone: type: string description: The customer's phone number maxLength: 255 example: 9999999999 description: type: string description: An arbitrary string that you can attach to a customer object. maxLength: 255 example: First customer address: type: object description: The address for the customer $ref: "#/components/schemas/Address" metadata: type: object description: You can specify up to 50 keys, with key names up to 40 characters long and values up to 500 characters long. Metadata is useful for storing additional, structured information on an object. maxLength: 255 example: { "city": "NY", "unit": "245" } CustomerUpdateRequest: type: object description: The customer details to be updated properties: email: type: string format: email description: The customer's email address maxLength: 255 example: JohnTest@test.com name: type: string description: The customer's name maxLength: 255 example: John Test phone_country_code: type: string description: The country code for the customer phone number maxLength: 255 example: "+65" phone: type: string description: The customer's phone number maxLength: 255 example: 9999999999 address: type: object description: The address for the customer $ref: "#/components/schemas/Address" description: type: string description: An arbitrary string that you can attach to a customer object. maxLength: 255 example: First customer metadata: type: object description: You can specify up to 50 keys, with key names up to 40 characters long and values up to 500 characters long. Metadata is useful for storing additional, structured information on an object. maxLength: 255 example: { "city": "NY", "unit": "245" } CustomerCreateResponse: type: object description: Customer required: - customer_id properties: customer_id: type: string description: The identifier for the customer object. If not provided the customer ID will be autogenerated. maxLength: 255 example: cus_y3oqhf46pyzuxjbcn2giaqnb44 email: type: string format: email description: The customer's email address maxLength: 255 example: JohnTest@test.com name: type: string description: The customer's name maxLength: 255 example: John Test phone_country_code: type: object description: The country code for the customer phone number maxLength: 255 example: +65 phone: type: object description: The customer's phone number maxLength: 255 example: 9999999999 address: type: object description: The address for the customer $ref: "#/components/schemas/Address" description: type: object description: An arbitrary string that you can attach to a customer object. maxLength: 255 example: First customer metadata: type: object description: You can specify up to 50 keys, with key names up to 40 characters long and values up to 500 characters long. Metadata is useful for storing additional, structured information on an object. maxLength: 255 example: { "city": "NY", "unit": "245" } CustomerDeleteResponse: type: object description: Customer required: - customer_id - deleted properties: customer_id: type: string description: The identifier for the customer object. If not provided the customer ID will be autogenerated. maxLength: 255 example: cus_y3oqhf46pyzuxjbcn2giaqnb44 deleted: type: boolean description: Indicates the deletion status of the customer object. example: true UpdateCustomerRequest: type: object description: The customer attached to the instrument properties: email: description: The email address of the customer type: string example: JohnTest@test.com name: description: The name of the customer type: string example: John Test default: description: The instrument ID for this customer’s default instrument type: string example: src_imu3wifxfvlebpqqq5usjrze6y phone: type: object description: The customer's phone number example: "9999999999" address: type: object description: The address for the customer $ref: "#/components/schemas/Address" metadata: type: object description: Allows you to store additional information about a customer. You can include a maximum of 10 key-value pairs. Each key and value can be up to 100 characters long. example: coupon_code: "NY2018" partner_id: 123989 PaymentsCreateRequest: type: object required: - amount - currency properties: amount: type: integer description: | The payment amount. Amount for the payment in lowest denomination of the currency. (i.e) in cents for USD denomination, in paisa for INR denomination etc., minimum: 100 example: 6540 currency: type: string description: | The three-letter ISO currency code example: USD maxLength: 3 minLength: 3 payment_id: type: string description: | Unique Identifier for the Payment. It is always recommended to provide this ID while creating a payment. If the identifiers in not provided in the Payment Request, this filed shall be auto generated and provide in the API response. It is suggested to keep the payment_id length as a maximum of 30 alphanumeric characters irrespective of payment methods and gateways. Sequential and only numeric characters are not recommended. maxLength: 30 minLength: 30 example: "pay_mbabizu24mvu3mela5njyhpit4" confirm: type: boolean description: Whether to confirm the payment (if applicable) default: false example: true capture_method: type: string description: "This is the instruction for capture/ debit the money from the users' card. On the other hand authorization refers to blocking the amount on the users' payment method. Capture request may happen in three types: (1) AUTOMATIC: Post the payment authorization, the capture will be executed on the full amount immediately, (2) MANUAL: The capture will happen only if the merchant triggers a Capture API request, (3) SCHEDULED: The capture can be scheduled to automatically get triggered at a specific date & time" enum: - automatic - manual - scheduled default: automatic example: automatic capture_on: description: | A timestamp (ISO 8601 code) that determines when the payment should be captured. Providing this field will automatically set `capture` to true allOf: - $ref: "#/components/schemas/Timestamp" amount_to_capture: type: integer description: | The Amount to be captured/ debited from the users payment method. It shall be in lowest denomination of the currency. (i.e) in cents for USD denomination, in paisa for INR denomination etc., If not provided, the default amount_to_capture will be the payment amount. minimum: 100 example: 6540 customer_id: type: string description: The identifier for the customer object. If not provided the customer ID will be autogenerated. maxLength: 255 example: cus_y3oqhf46pyzuxjbcn2giaqnb44 description: type: string description: A description of the payment maxLength: 255 example: "Its my first payment request" email: type: string format: email description: The customer's email address maxLength: 255 example: JohnTest@test.com name: type: string description: The customer's name maxLength: 255 example: John Test phone: type: string description: The customer's phone number maxLength: 255 example: 9999999999 phone_country_code: type: string description: The country code for the customer phone number maxLength: 255 example: "+65" return_url: type: string description: The URL to redirect after the completion of the operation maxLength: 255 example: "https://juspay.io/" setup_future_usage: type: string description: "Indicates that you intend to make future payments with this Payment’s payment method. Providing this parameter will attach the payment method to the Customer, if present, after the Payment is confirmed and any required actions from the user are complete." enum: - on_session - off_session example: off_session off_session: type: boolean description: "Set to true to indicate that the customer is not in your checkout flow during this payment, and therefore is unable to authenticate. This parameter is intended for scenarios where you collect card details and charge them later. This parameter can only be used with confirm=true." example: true mandate_data: type: object description: This hash contains details about the Mandate to create. This parameter can only be used with confirm=true. properties: customer_acceptance: type: object description: Details about the customer’s acceptance. $ref: "#/components/schemas/CustomerAcceptance" mandate_id: type: string description: ID of the mandate to be used for this payment. This parameter can only be used with confirm = true. This parameter should be passed for Merchant Initiated Transaction scenarios where the user has already registered for a mandate and raw payment method details are not available. example: "mandate_iwer89rnjef349dni3" authentication_type: type: string description: "The transaction authentication can be set to undergo payer authentication. Possible values are: (i) THREE_DS: If the card is enrolled for 3DS authentication, the 3DS based authentication will be activated. The liability of chargeback shift to the issuer, (ii) NO_THREE_DS: 3DS based authentication will not be activated. The liability of chargeback stays with the merchant. By default, the authentication will be marked as NO_THREE_DS" enum: - three_ds - three_ds_2 - no_three_ds default: no_three_ds example: no_three_ds payment_method: type: string description: "The payment method" enum: - card - bank_transfer - netbanking - upi - open_banking - consumer_finance - wallet example: card payment_method_data: type: object description: The payment method information properties: card: type: object description: payment card oneOf: - $ref: "#/components/schemas/CardData" # save_payment_method: # type: boolean # description: Enable this flag as true, if the user has consented for saving the payment method information # default: false # example: true billing: type: object description: The billing address for the payment $ref: "#/components/schemas/Address" shipping: type: object description: The shipping address for the payment $ref: "#/components/schemas/Address" statement_descriptor_name: type: string description: For non-card charges, you can use this value as the complete description that appears on your customers’ statements. Must contain at least one letter, maximum 22 characters. maxLength: 255 example: "Juspay Router" statement_descriptor_suffix: type: string description: Provides information about a card payment that customers see on their statements. Concatenated with the prefix (shortened descriptor) or statement descriptor that’s set on the account to form the complete statement descriptor. Maximum 22 characters for the concatenated descriptor. maxLength: 255 example: "Payment for shoes purchase" metadata: type: object description: You can specify up to 50 keys, with key names up to 40 characters long and values up to 500 characters long. Metadata is useful for storing additional, structured information on an object. maxLength: 255 example: { "city": "NY", "unit": "245" } PaymentsConfirmRequest: type: object properties: return_url: type: string description: The URL to redirect after the completion of the operation maxLength: 255 example: "www.example.com/success" setup_future_usage: type: string description: "Indicates that you intend to make future payments with this Payment’s payment method. Possible values are: (i) REQUIRED: The payment will be processed only with payment methods eligible for recurring payments (ii) OPTIONAL: The payment may/ may not be processed with payment methods eligible for recurring payments" enum: - required - optional example: required authentication_type: type: string description: "The transaction authentication can be set to undergo payer authentication. Possible values are: (i) THREE_DS: If the card is enrolled for 3DS authentication, the 3DS based authentication will be activated. The liability of chargeback shift to the issuer, (ii) NO_THREE_DS: 3DS based authentication will not be activated. The liability of chargeback stays with the merchant. By default, the authentication will be marked as NO_THREE_DS" enum: - three_ds - no_three_ds default: no_three_ds payment_method: type: string description: "The payment method" enum: - card - bank_transfer - netbanking - upi - open_banking - consumer_finance - wallet default: three_ds example: automatic payment_method_data: type: object description: The payment method information oneOf: - $ref: "#/components/schemas/CardData" save_payment_method: type: boolean description: Enable this flag as true, if the user has consented for saving the payment method information default: false example: true billing: type: object description: The billing address for the payment $ref: "#/components/schemas/Address" shipping: type: object description: The shipping address for the payment $ref: "#/components/schemas/Address" PaymentsUpdateRequest: type: object properties: amount: type: integer description: | The payment amount. Amount for the payment in lowest denomination of the currency. (i.e) in cents for USD denomination, in paisa for INR denomination etc., minimum: 100 example: 6540 currency: type: string description: | The three-letter ISO currency code example: USD maxLength: 3 minLength: 3 capture_method: type: string description: "This is the instruction for capture/ debit the money from the users' card. On the other hand authorization refers to blocking the amount on the users' payment method. Capture request may happen in three types: (1) AUTOMATIC: Post the payment authorization, the capture will be executed on the full amount immediately, (2) MANUAL: The capture will happen only if the merchant triggers a Capture API request, (3) SCHEDULED: The capture can be scheduled to automatically get triggered at a specific date & time" enum: - automatic - manual - scheduled default: automatic example: automatic capture_on: description: | A timestamp (ISO 8601 code) that determines when the payment should be captured. Providing this field will automatically set `capture` to true allOf: - $ref: "#/components/schemas/Timestamp" amount_to_capture: type: integer description: | The Amount to be captured/ debited from the users payment method. It shall be in lowest denomination of the currency. (i.e) in cents for USD denomination, in paisa for INR denomination etc., If not provided, the default amount_to_capture will be the payment amount. minimum: 100 example: 6540 customer_id: type: string description: The identifier for the customer object. If not provided the customer ID will be autogenerated. maxLength: 255 example: cus_y3oqhf46pyzuxjbcn2giaqnb44 description: type: string description: A description of the payment maxLength: 255 example: "Its my first payment request" email: type: string format: email description: The customer's email address maxLength: 255 example: JohnTest@test.com name: type: string description: The customer's name maxLength: 255 example: John Test phone: type: string description: The customer's phone number maxLength: 255 example: 9999999999 phone_country_code: type: string description: The country code for the customer phone number maxLength: 255 example: "+65" setup_future_usage: type: string description: "Indicates that you intend to make future payments with this Payment’s payment method. Possible values are: (i) REQUIRED: The payment will be processed only with payment methods eligible for recurring payments (ii) OPTIONAL: The payment may/ may not be processed with payment methods eligible for recurring payments" enum: - required - optional example: required authentication_type: type: string description: "The transaction authentication can be set to undergo payer authentication. Possible values are: (i) THREE_DS: If the card is enrolled for 3DS authentication, the 3DS based authentication will be activated. The liability of chargeback shift to the issuer, (ii) NO_THREE_DS: 3DS based authentication will not be activated. The liability of chargeback stays with the merchant. By default, the authentication will be marked as NO_THREE_DS" enum: - three_ds - no_three_ds default: no_three_ds payment_method: type: string description: The payment method enum: - card - bank_transfer - netbanking - upi - open_banking - consumer_finance - wallet default: three_ds example: automatic payment_method_data: type: object description: The payment method information oneOf: - $ref: "#/components/schemas/CardData" save_payment_method: type: boolean description: Enable this flag as true, if the user has consented for saving the payment method information default: false example: true billing: type: object description: The billing address for the payment $ref: "#/components/schemas/Address" shipping: type: object description: The shipping address for the payment $ref: "#/components/schemas/Address" statement_descriptor_name: type: string description: For non-card charges, you can use this value as the complete description that appears on your customers’ statements. Must contain at least one letter, maximum 22 characters. maxLength: 255 example: "Juspay Router" statement_descriptor_suffix: type: string description: Provides information about a card payment that customers see on their statements. Concatenated with the prefix (shortened descriptor) or statement descriptor that’s set on the account to form the complete statement descriptor. Maximum 22 characters for the concatenated descriptor. maxLength: 255 example: "Payment for shoes purchase" metadata: type: object description: You can specify up to 50 keys, with key names up to 40 characters long and values up to 500 characters long. Metadata is useful for storing additional, structured information on an object. maxLength: 255 example: { "city": "NY", "unit": "245" } PaymentsCaptureRequest: type: object properties: amount_to_capture: type: integer description: | The Amount to be captured/ debited from the users payment method. It shall be in lowest denomination of the currency. (i.e) in cents for USD denomination, in paisa for INR denomination etc., If not provided, the default amount_to_capture will be the payment amount. minimum: 100 example: 6540 statement_descriptor_name: type: string description: For non-card charges, you can use this value as the complete description that appears on your customers’ statements. Must contain at least one letter, maximum 22 characters. maxLength: 255 example: "Juspay Router" statement_descriptor_suffix: type: string description: Provides information about a card payment that customers see on their statements. Concatenated with the prefix (shortened descriptor) or statement descriptor that’s set on the account to form the complete statement descriptor. Maximum 22 characters for the concatenated descriptor. maxLength: 255 example: "Payment for shoes purchase" PaymentsCancelRequest: type: object properties: cancellation_reason: type: string description: Provides information on the reason for cancellation maxLength: 255 example: "Timeout for payment completion" PaymentsCreateResponse: type: object required: - payment_id - status - amount - currency - mandate_id description: Payment Response properties: payment_id: type: string description: | Unique Identifier for the Payment. It is always recommended to provide this ID while creating a payment. If the identifiers in not provided in the Payment Request, this filed shall be auto generated and provide in the API response. It is suggested to keep the payment_id length as a maximum of 30 alphanumeric characters irrespective of payment methods and gateways. Sequential and only numeric characters are not recommended. maxLength: 30 example: "pay_mbabizu24mvu3mela5njyhpit4" status: type: string description: The status of the payment enum: - succeeded - failed - processing - requires_customer_action - requires_payment_method - requires_confirmation - required_capture example: succeeded amount: type: integer description: | The payment amount. Amount for the payment in lowest denomination of the currency. (i.e) in cents for USD denomination, in paisa for INR denomination etc., minimum: 100 example: 6540 currency: type: string description: | The three-letter ISO currency code example: USD maxLength: 3 minLength: 3 cancellation_reason: type: string description: The reason for cancelling the payment maxLength: 255 example: "Payment attempt expired" nullable: true capture_method: type: string description: "This is the instruction for capture/ debit the money from the users' card. On the other hand authorization refers to blocking the amount on the users' payment method. Capture request may happen in three types: (1) AUTOMATIC: Post the payment authorization, the capture will be executed on the full amount immediately, (2) MANUAL: The capture will happen only if the merchant triggers a Capture API request, (3) SCHEDULED: The capture can be scheduled to automatically get triggered at a specific date & time" enum: - automatic - manual - scheduled default: automatic example: automatic capture_on: description: | A timestamp (ISO 8601 code) that determines when the payment should be captured. Providing this field will automatically set `capture` to true allOf: - $ref: "#/components/schemas/Timestamp" amount_to_capture: type: integer description: | The Amount to be captured/ debited from the users payment method. It shall be in lowest denomination of the currency. (i.e) in cents for USD denomination, in paisa for INR denomination etc., If not provided, the default amount_to_capture will be the payment amount. minimum: 100 example: 6540 nullable: true amount_capturable: type: integer description: The maximum amount that could be captured from the payment minimum: 100 example: 6540 nullable: true amount_received: type: integer description: The amount which is already captured from the payment minimum: 100 example: 6540 nullable: true customer_id: type: string description: The identifier for the customer object. If not provided the customer ID will be autogenerated. maxLength: 255 example: cus_y3oqhf46pyzuxjbcn2giaqnb44 nullable: true email: type: string format: email description: The customer's email address maxLength: 255 example: JohnTest@test.com nullable: true name: type: string description: The customer's name maxLength: 255 example: John Test nullable: true phone: type: string description: The customer's phone number maxLength: 255 example: 9999999999 nullable: true phone_country_code: type: string description: The country code for the customer phone number maxLength: 255 example: "+65" nullable: true client_secret: type: string description: This is a 15 minute expiry token which shall be used from the client to authenticate and perform sessions from the SDK example: "secret_k2uj3he2893ein2d" maxLength: 30 minLength: 30 nullable: true description: type: string description: A description of the payment maxLength: 255 example: "Its my first payment request" nullable: true setup_future_usage: type: string description: "Indicates that you intend to make future payments with this Payment’s payment method. Providing this parameter will attach the payment method to the Customer, if present, after the Payment is confirmed and any required actions from the user are complete." enum: - on_session - off_session example: off_session off_session: type: boolean description: "Set to true to indicate that the customer is not in your checkout flow during this payment, and therefore is unable to authenticate. This parameter is intended for scenarios where you collect card details and charge them later. This parameter can only be used with confirm=true." example: true mandate_id: type: string description: ID of the mandate used for this payment. This parameter can only be used with confirm = true. This parameter should be passed for Merchant Initiated Transaction scenarios where the user has already registered for a mandate and raw payment method details are not passed example: "mandate_iwer89rnjef349dni3" mandate_data: type: object description: This hash contains details about the Mandate to create. This parameter can only be used with confirm=true. properties: customer_acceptance: type: object description: Details about the customer’s acceptance. $ref: "#/components/schemas/CustomerAcceptance" authentication_type: type: string description: "The transaction authentication can be set to undergo payer authentication. Possible values are: (i) THREE_DS: If the card is enrolled for 3DS authentication, the 3DS based authentication will be activated. The liability of chargeback shift to the issuer, (ii) NO_THREE_DS: 3DS based authentication will not be activated. The liability of chargeback stays with the merchant. By default, the authentication will be marked as NO_THREE_DS" enum: - three_ds - no_three_ds default: no_three_ds example: no_three_ds billing: type: object description: The billing address for the payment $ref: "#/components/schemas/Address" nullable: true shipping: type: object description: The shipping address for the payment $ref: "#/components/schemas/Address" nullable: true statement_descriptor_name: type: string description: For non-card charges, you can use this value as the complete description that appears on your customers’ statements. Must contain at least one letter, maximum 22 characters. maxLength: 255 example: "Juspay Router" nullable: true statement_descriptor_suffix: type: string description: Provides information about a card payment that customers see on their statements. Concatenated with the prefix (shortened descriptor) or statement descriptor that’s set on the account to form the complete statement descriptor. Maximum 22 characters for the concatenated descriptor. maxLength: 255 example: "Payment for shoes purchase" nullable: true next_action: type: object description: Provides information about the user action required to complete the payment. $ref: "#/components/schemas/NextAction" metadata: type: object description: You can specify up to 50 keys, with key names up to 40 characters long and values up to 500 characters long. Metadata is useful for storing additional, structured information on an object. maxLength: 255 example: { "city": "NY", "unit": "245" } nullable: true MandateListResponse: type: object description: Mandate Payment Create Response required: - mandate_id - status - payment_method_id properties: mandate_id: type: string description: | The unique id corresponding to the mandate. example: "mandate_end38934n12s923d0" status: type: string description: The status of the mandate, which indicates whether it can be used to initiate a payment. enum: - active - inactive - pending - revoked example: "active" type: type: string description: The type of the mandate. (i) single_use refers to one-time mandates and (ii) multi-user refers to multiple payments. enum: - multi_use - single_use default: "multi_use" example: "multi_use" payment_method_id: type: string description: The id corresponding to the payment method. example: "pm_end38934n12s923d0" payment_method: type: string description: | The type of payment method use for the payment. enum: - card - payment_container - bank_transfer - bank_debit - pay_later - upi - netbanking example: card card: description: The card identifier information to be displayed on the user interface $ref: "#/components/schemas/CardPaymentMethodResponse" customer_acceptance: description: The card identifier information to be displayed on the user interface $ref: "#/components/schemas/CustomerAcceptance" CustomerAcceptance: type: object description: Details about the customer’s acceptance of the mandate. properties: accepted_at: description: A timestamp (ISO 8601 code) that determines when the refund was created. $ref: "#/components/schemas/Timestamp" online: type: object description: If this is a Mandate accepted online, this hash contains details about the online acceptance. $ref: "#/components/schemas/CustomerAcceptanceOnline" acceptance_type: type: string description: The type of customer acceptance information included with the Mandate. One of online or offline. enum: - online - offline example: "online" CustomerAcceptanceOnline: type: object description: If this is a Mandate accepted online, this hash contains details about the online acceptance. properties: ip_address: type: string description: The IP address from which the Mandate was accepted by the customer. example: "127.0.0.1" user_agent: type: string description: The user agent of the browser from which the Mandate was accepted by the customer. example: "device" PaymentMethodsCreateRequest: type: object required: - payment_method properties: payment_method: type: string description: | The type of payment method use for the payment. enum: - card - payment_container - bank_transfer - bank_debit - pay_later - upi - netbanking example: card payment_method_type: type: string description: | This is a sub-category of payment method. enum: - credit_card - debit_card - upi_intent - upi_collect - credit_card_installments - pay_later_installments example: credit_card payment_method_issuer: type: string description: | The name of the bank/ provider issuing the payment method to the end user example: Citibank payment_method_issuer_code: type: string description: | A standard code representing the issuer of payment method example: JP_APPLEPAY card: type: object $ref: "#/components/schemas/CardPaymentMethodRequest" customer_id: type: string description: | The unique identifier of the Customer. example: "cus_mnewerunwiuwiwqw" metadata: type: object description: You can specify up to 50 keys, with key names up to 40 characters long and values up to 500 characters long. Metadata is useful for storing additional, structured information on an object. example: { "city": "NY", "unit": "245" } PaymentMethodsUpdateRequest: type: object properties: card: type: object $ref: "#/components/schemas/CardPaymentMethodRequest" billing: type: object $ref: "#/components/schemas/Address" metadata: type: object description: You can specify up to 50 keys, with key names up to 40 characters long and values up to 500 characters long. Metadata is useful for storing additional, structured information on an object. example: { "city": "NY", "unit": "245" } PaymentMethodsResponseObject: type: object required: - payment_method_id - payment_method - recurring_enabled - installment_enabled - payment_experience properties: payment_method_id: type: string description: The identifier for the payment method object. maxLength: 30 example: pm_y3oqhf46pyzuxjbcn2giaqnb44 payment_method: type: string description: | The type of payment method use for the payment. enum: - card - payment_container - bank_transfer - bank_debit - pay_later - upi - netbanking example: card payment_method_type: type: string description: | This is a sub-category of payment method. enum: - credit_card - debit_card - upi_intent - upi_collect - credit_card_installments - pay_later_installments example: credit_card payment_method_issuer: type: string description: | The name of the bank/ provider issuing the payment method to the end user example: Citibank payment_method_issuer_code: type: string description: | A standard code representing the issuer of payment method example: PM_APPLEPAY card: type: object $ref: "#/components/schemas/CardPaymentMethodResponse" payment_scheme: type: array items: type: string description: | The network scheme to which the payment method belongs example: [MASTER, VISA] accepted_country: type: array items: type: string description: | The two-letter ISO currency code example: [US, UK, IN] maxLength: 2 minLength: 2 accepted_currency: type: array items: type: string description: | The three-letter ISO currency code example: [USD, EUR] minimum_amount: type: integer description: | The minimum amount accepted for processing by the particular payment method. example: 100 maximum_amount: type: integer description: | The minimum amount accepted for processing by the particular payment method. example: 10000000 recurring_payment_enabled: type: boolean description: Indicates whether the payment method is eligible for recurring payments example: true installment_payment_enabled: type: boolean description: Indicates whether the payment method is eligible for installment payments example: true payment_experience: type: array items: type: string description: "This indicates type of action that is required in order to complete the payment with inputs from the user. This may involve actions such as redirecting the user to a URL, displaying a QR code, invoking the SDK client" enum: - redirect_to_url - display_qr_code - invoke_sdk_client example: ["redirect_to_url", "display_qr_code"] PaymentMethodDeleteResponse: type: object description: Payment Method deletion confirmation required: - payment_method_id - deleted properties: payment_method_id: type: string description: The identifier for the payment method object. maxLength: 30 example: pm_y3oqhf46pyzuxjbcn2giaqnb44 deleted: type: boolean description: Indicates the deletion status of the payment method object. example: true RefundsCreateRequest: type: object required: - payment_id properties: amount: type: integer description: | Total amount for which the refund is to be initiated. Amount for the payment in lowest denomination of the currency. (i.e) in cents for USD denomination, in paisa for INR denomination etc., If not provided, this will default to the full payment amount minimum: 100 example: 6540 refund_id: type: string description: | Unique Identifier for the Refund. This is to ensure idempotency for multiple partial refund initiated against the same payment. If the identifiers is not defined by the merchant, this filed shall be auto generated and provide in the API response. It is recommended to generate uuid(v4) as the refund_id. maxLength: 30 minLength: 30 example: "ref_mbabizu24mvu3mela5njyhpit4" payment_id: type: string description: | Unique Identifier for the Payment. It is always recommended to provide this ID while creating a payment. If the identifiers in not provided in the Payment Request, this filed shall be auto generated and provide in the API response. It is suggested to keep the payment_id length as a maximum of 30 alphanumeric characters irrespective of payment methods and gateways. Sequential and only numeric characters are not recommended. maxLength: 30 minLength: 30 example: "pay_mbabizu24mvu3mela5njyhpit4" currency: type: string description: | The three-letter ISO currency code example: USD maxLength: 3 minLength: 3 reason: type: string description: An arbitrary string attached to the object. Often useful for displaying to users and your customer support executive maxLength: 255 example: "Customer returned the product" created_at: description: | A timestamp (ISO 8601 code) that determines when the refund was created. allOf: - $ref: "#/components/schemas/Timestamp" metadata: type: object description: You can specify up to 50 keys, with key names up to 40 characters long and values up to 500 characters long. Metadata is useful for storing additional, structured information on an object. maxLength: 255 example: { "city": "NY", "unit": "245" } RefundsUpdateRequest: type: object required: - metadata properties: reason: type: string description: An arbitrary string attached to the object. Often useful for displaying to users and your customer support executive maxLength: 255 example: "Customer returned the product" metadata: type: object description: You can specify up to 50 keys, with key names up to 40 characters long and values up to 500 characters long. Metadata is useful for storing additional, structured information on an object. maxLength: 255 example: { "city": "NY", "unit": "245" } RefundsObject: type: object required: - amount - refund_id - payment_id - currency - status properties: amount: type: integer description: | The refund amount, which should be less than or equal to the total payment amount. Amount for the payment in lowest denomination of the currency. (i.e) in cents for USD denomination, in paisa for INR denomination etc., minimum: 1 example: 6540 refund_id: type: string description: | Unique Identifier for the Refund. This is to ensure idempotency for multiple partial refund initiated against the same payment. If the identifiers is not defined by the merchant, this filed shall be auto generated and provide in the API response. It is recommended to generate uuid(v4) as the refund_id. maxLength: 30 minLength: 30 example: "ref_mbabizu24mvu3mela5njyhpit4" payment_id: type: string description: | Unique Identifier for the Payment. It is always recommended to provide this ID while creating a payment. If the identifiers in not provided in the Payment Request, this filed shall be auto generated and provide in the API response. It is suggested to keep the payment_id length as a maximum of 30 alphanumeric characters irrespective of payment methods and gateways. Sequential and only numeric characters are not recommended. maxLength: 30 example: "pay_mbabizu24mvu3mela5njyhpit4" currency: type: string description: | The three-letter ISO currency code example: USD maxLength: 3 minLength: 3 reason: type: string description: An arbitrary string attached to the object. Often useful for displaying to users and your customer support executive maxLength: 255 example: "Customer returned the product" metadata: type: object description: You can specify up to 50 keys, with key names up to 40 characters long and values up to 500 characters long. Metadata is useful for storing additional, structured information on an object. maxLength: 255 example: { "city": "NY", "unit": "245" } RefundResponse: type: array items: type: object properties: amount: type: integer description: | The refund amount, which should be less than or equal to the total payment amount. Amount for the payment in lowest denomination of the currency. (i.e) in cents for USD denomination, in paisa for INR denomination etc., minimum: 1 example: 6540 refund_id: type: string description: | Unique Identifier for the Refund. This is to ensure idempotency for multiple partial refund initiated against the same payment. If the identifiers is not defined by the merchant, this filed shall be auto generated and provide in the API response. It is recommended to generate uuid(v4) as the refund_id. maxLength: 30 minLength: 30 example: "ref_mbabizu24mvu3mela5njyhpit4" payment_id: type: string description: | Unique Identifier for the Payment. It is always recommended to provide this ID while creating a payment. If the identifiers in not provided in the Payment Request, this filed shall be auto generated and provide in the API response. It is suggested to keep the payment_id length as a maximum of 30 alphanumeric characters irrespective of payment methods and gateways. Sequential and only numeric characters are not recommended. maxLength: 30 minLength: 30 example: "pay_mbabizu24mvu3mela5njyhpit4" currency: type: string description: | The three-letter ISO currency code example: USD maxLength: 3 minLength: 3 reason: type: string description: An arbitrary string attached to the object. Often useful for displaying to users and your customer support executive maxLength: 255 example: "Customer returned the product" metadata: type: object description: You can specify up to 50 keys, with key names up to 40 characters long and values up to 500 characters long. Metadata is useful for storing additional, structured information on an object. maxLength: 255 example: { "city": "NY", "unit": "245" } CardData: type: object description: Card Data properties: card_number: type: string description: The card number maxLength: 30 minLength: 30 example: "4242424242424242" card_exp_month: type: string description: The expiry month for the card maxLength: 2 minLength: 2 example: "10" card_exp_year: type: string description: Expiry year for the card maxLength: 2 minLength: 2 example: "25" card_holder_name: type: string description: The name of card holder maxLength: 255 minLength: 1 example: "John Doe" card_cvc: type: string description: The cvc number maxLength: 4 minLength: 3 example: "123" card_token: type: string description: The token provided against a user's saved card. The token would be valid for 15 minutes. minLength: 30 maxLength: 30 example: "tkn_78892490hfh3r834rd" CardPaymentMethodRequest: type: object description: Card Payment Method Information properties: card_number: type: string description: The card number maxLength: 30 minLength: 30 example: "4242424242424242" card_exp_month: type: string description: The expiry month for the card maxLength: 2 minLength: 2 example: "10" card_exp_year: type: string description: Expiry year for the card maxLength: 2 minLength: 2 example: "25" card_holder_name: type: string description: The name of card holder maxLength: 255 minLength: 1 example: "John Doe" CardPaymentMethodResponse: type: object description: Card Payment Method object properties: last4_digits: type: string description: The last four digits of the case which could be displayed to the end user for identification. example: "xxxxxxxxxxxx4242" card_exp_month: type: string description: The expiry month for the card maxLength: 2 minLength: 2 example: "10" card_exp_year: type: string description: Expiry year for the card maxLength: 2 minLength: 2 example: "25" card_holder_name: type: string description: The name of card holder maxLength: 255 example: "John Doe" card_token: type: string description: The token provided against a user's saved card. The token would be valid for 15 minutes. minLength: 30 maxLength: 30 example: "tkn_78892490hfh3r834rd" scheme: type: string description: The card scheme network for the particular card example: "MASTER" issuer_country: type: string description: The country code in in which the card was issued minLength: 2 maxLength: 2 example: "US" card_fingerprint: type: string description: A unique identifier alias to identify a particular card. minLength: 30 maxLength: 30 example: "fpt_78892490hfh3r834rd" MerchantAccountCreateRequest: type: object description: The Merchant Account details required: - merchant_id properties: merchant_id: type: string description: The identifier for the Merchant Account. maxLength: 255 example: y3oqhf46pyzuxjbcn2giaqnb44 # create request may not have the api_key as it is the first time the API services are invoked # api_key: # type: string # description: The public security key for accessing the APIs # maxLength: 255 # example: xkkdf909012sdjki2dkh5sdf merchant_name: type: string description: Name of the merchant example: NewAge Retailer merchant_details: type: object description: Details about the merchant including contact person, email, address, website, business description etc $ref: "#/components/schemas/MerchantDetails" return_url: type: string description: The URL to redirect after the completion of the operation maxLength: 255 example: "www.example.com/success" webhook_details: type: object description: The features for Webhook $ref: "#/components/schemas/WebhookDetails" routing_algorithm: type: string description: The routing algorithm to be used to process the incoming request from merchant to outgoing payment processor or payment method. The default is CUSTOM if enum: - round_robin - max_conversion - min_cost - custom maxLength: 255 example: custom custom_routing_rules: type: array description: An array of custom routing rules $ref: "#/components/schemas/ArrayOfRoutingRules" sub_merchants_enabled: type: boolean description: A boolean value to indicate if the merchant is a sub-merchant under a master or a parent merchant. By default, its value is false. maxLength: 255 example: false parent_merchant_id: type: string description: Refers to the Parent Merchant ID if the merchant being created is a sub-merchant maxLength: 255 example: "xkkdf909012sdjki2dkh5sdf" metadata: type: object description: You can specify up to 50 keys, with key names up to 40 characters long and values up to 500 characters long. Metadata is useful for storing additional, structured information on an object. maxLength: 255 example: { "city": "NY", "unit": "245" } MerchantAccountUpdateRequest: type: object description: The Merchant Account details to be updated required: - merchant_id properties: merchant_id: type: string description: The identifier for the Merchant Account. maxLength: 255 example: y3oqhf46pyzuxjbcn2giaqnb44 # api_key: # type: string # description: The public security key for accessing the APIs # maxLength: 255 # example: xkkdf909012sdjki2dkh5sdf merchant_name: type: string description: Name of the merchant example: NewAge Retailer merchant_details: type: object description: Details about the merchant including contact person, email, address, website, business description etc $ref: "#/components/schemas/MerchantDetails" return_url: type: string description: The URL to redirect after the completion of the operation maxLength: 255 example: "www.example.com/success" webhook_details: type: object description: The features for Webhook $ref: "#/components/schemas/WebhookDetails" routing_algorithm: type: string description: The routing algorithm to be used to process the incoming request from merchant to outgoing payment processor or payment method. The default is CUSTOM if enum: - round_robin - max_conversion - min_cost - custom maxLength: 255 example: custom custom_routing_rules: type: array description: An array of custom routing rules $ref: "#/components/schemas/ArrayOfRoutingRules" sub_merchants_enabled: type: boolean description: A boolean value to indicate if the merchant is a sub-merchant under a master or a parent merchant. By default, its value is false. maxLength: 255 example: false parent_merchant_id: type: string description: Refers to the Parent Merchant ID if the merchant being created is a sub-merchant maxLength: 255 example: "xkkdf909012sdjki2dkh5sdf" metadata: type: object description: You can specify up to 50 keys, with key names up to 40 characters long and values up to 500 characters long. Metadata is useful for storing additional, structured information on an object. maxLength: 255 example: { "city": "NY", "unit": "245" } #Standard Response for all API requests MerchantAccountResponse: type: object description: Merchant Account required: - merchant_id properties: merchant_id: type: string description: The identifier for the Merchant Account. maxLength: 255 example: y3oqhf46pyzuxjbcn2giaqnb44 api_key: type: string description: The public security key for accessing the APIs maxLength: 255 example: xkkdf909012sdjki2dkh5sdf merchant_name: type: string description: Name of the merchant example: NewAge Retailer merchant_details: type: object description: Details about the merchant including contact person, email, address, website, business description etc $ref: "#/components/schemas/MerchantDetails" webhook_details: type: object description: The features for Webhook $ref: "#/components/schemas/WebhookDetails" routing_algorithm: type: string description: The routing algorithm to be used to process the incoming request from merchant to outgoing payment processor or payment method. The default is CUSTOM if enum: - round_robin - max_conversion - min_cost - custom maxLength: 255 example: custom custom_routing_rules: type: array description: An array of custom routing rules $ref: "#/components/schemas/ArrayOfRoutingRules" sub_merchants_enabled: type: boolean description: A boolean value to indicate if the merchant is a sub-merchant under a master or a parent merchant. By default, its value is false. maxLength: 255 example: false parent_merchant_id: type: string description: Refers to the Parent Merchant ID if the merchant being created is a sub-merchant maxLength: 255 example: "xkkdf909012sdjki2dkh5sdf" metadata: type: object description: You can specify up to 50 keys, with key names up to 40 characters long and values up to 500 characters long. Metadata is useful for storing additional, structured information on an object. maxLength: 255 example: { "city": "NY", "unit": "245" } MerchantAccountDeleteResponse: type: object description: Merchant Account required: - merchant_id - deleted properties: merchant_id: type: string description: The identifier for the MerchantAccount object. maxLength: 255 example: y3oqhf46pyzuxjbcn2giaqnb44 deleted: type: boolean description: Indicates the deletion status of the Merchant Account object. example: true PaymentConnectorCreateRequest: type: object description: The Payment Connector details required: - merchant_id - connector_type - connector_name properties: merchant_id: type: string description: The identifier for the Merchant Account. maxLength: 255 example: y3oqhf46pyzuxjbcn2giaqnb44 connector_type: type: string description: Type of the Connector for the financial use case. Could range from Payments to Accounting to Banking. $ref: "#/components/schemas/ConnectorType" connector_name: type: string description: Name of the Connector $ref: "#/components/schemas/PaymentConnector" # connector_id: # type: integer # description: Unique ID of the connector. It is returned in the Response. connector_account_details: type: object description: Account details of the Connector. You can specify up to 50 keys, with key names up to 40 characters long and values up to 500 characters long. Useful for storing additional, structured information on an object. example: { "api_key": "Basic MyVerySecretApiKey" } # $ref: "#/components/schemas/ConnectorAccountDetails" test_mode: type: boolean description: A boolean value to indicate if the connector is in Test mode. By default, its value is false. example: false disabled: type: boolean description: A boolean value to indicate if the connector is disabled. By default, its value is false. example: false payment_methods_enabled: type: array description: Refers to the Parent Merchant ID if the merchant being created is a sub-merchant $ref: "#/components/schemas/PaymentMethodsEnabled" metadata: type: object description: You can specify up to 50 keys, with key names up to 40 characters long and values up to 500 characters long. Metadata is useful for storing additional, structured information on an object. maxLength: 255 example: { "city": "NY", "unit": "245" } PaymentConnectorUpdateRequest: type: object description: The Payment Connector Update Request required: - merchant_id - connector_type - connector_name - connector_id properties: merchant_id: type: string description: The identifier for the Merchant Account. maxLength: 255 example: y3oqhf46pyzuxjbcn2giaqnb44 connector_type: type: string description: Type of the Connector for the financial use case. Could range from Payments to Accounting to Banking. $ref: "#/components/schemas/ConnectorType" connector_name: type: string description: Name of the Connector $ref: "#/components/schemas/PaymentConnector" connector_id: type: integer description: Unique ID of the connector connector_account_details: type: object description: Account details of the Connector. You can specify up to 50 keys, with key names up to 40 characters long and values up to 500 characters long. Useful for storing additional, structured information on an object. example: { "processing_fee": "2.0%", "billing_currency": "USD" } # $ref: "#/components/schemas/ConnectorAccountDetails" test_mode: type: boolean description: A boolean value to indicate if the connector is in Test mode. By default, its value is false. example: false disabled: type: boolean description: A boolean value to indicate if the connector is disabled. By default, its value is false. example: false payment_methods: type: array description: Refers to the Parent Merchant ID if the merchant being created is a sub-merchant $ref: "#/components/schemas/PaymentMethodsEnabled" metadata: type: object description: You can specify up to 50 keys, with key names up to 40 characters long and values up to 500 characters long. Metadata is useful for storing additional, structured information on an object. maxLength: 255 example: { "city": "NY", "unit": "245" } PaymentConnectorResponse: type: object description: The Payment Connector Response details required: - merchant_id - connector_type - connector_name - connector_id properties: merchant_id: type: string description: The identifier for the Merchant Account. maxLength: 255 example: y3oqhf46pyzuxjbcn2giaqnb44 connector_type: type: string description: Type of the Connector for the financial use case. Could range from Payments to Accounting to Banking. $ref: "#/components/schemas/ConnectorType" connector_name: type: string description: Name of the Connector $ref: "#/components/schemas/PaymentConnector" connector_id: type: integer description: Unique ID of the connector example: 12 connector_account_details: type: object description: Account details of the Connector. You can specify up to 50 keys, with key names up to 40 characters long and values up to 500 characters long. Useful for storing additional, structured information on an object. example: { "processing_fee": "2.0%", "billing_currency": "USD" } # $ref: "#/components/schemas/ConnectorAccountDetails" test_mode: type: boolean description: A boolean value to indicate if the connector is in Test mode. By default, its value is false. example: false disabled: type: boolean description: A boolean value to indicate if the connector is disabled. By default, its value is false. example: false payment_methods: type: array description: Refers to the Parent Merchant ID if the merchant being created is a sub-merchant $ref: "#/components/schemas/PaymentMethodsEnabled" metadata: type: object description: You can specify up to 50 keys, with key names up to 40 characters long and values up to 500 characters long. Metadata is useful for storing additional, structured information on an object. maxLength: 255 example: { "city": "NY", "unit": "245" } PaymentConnectorDeleteResponse: type: object description: Payment Connector Delete Response required: - merchant_id - connector_id - deleted properties: merchant_id: type: string description: The identifier for the Merchant Account maxLength: 255 example: y3oqhf46pyzuxjbcn2giaqnb44 connector_id: type: integer description: The identifier for the Payment Connector example: 10 deleted: type: boolean description: Indicates the deletion status of the Merchant Account object. example: true ConnectorType: type: string description: Type of the connector enum: - payment_processor #PayFacs, Acquirers, Gateways, BNPL etc - payment_vas #Fraud, Currency Conversion, Crypto etc - fin_operations #Accounting, Billing, Invoicing, Tax etc - fiz_operations #Inventory, ERP, CRM, KYC etc - networks #Payment Networks like Visa, MasterCard etc - banking_entities #All types of banks including corporate / commercial / personal / neo banks - non_banking_finance #All types of non-banking financial institutions including Insurance, Credit / Lending etc #INCOMPLETE. NEEDS MORE THINKING! #QUESTION: Should we bring all elements of costs / conversion rates / supported payment methods etc in this object? # ConnectorAccountDetails: # type: object # description: Account details of the Connector # properties: # processing_cost: # type: string # description: Description on the processing cost # example: "2.0% of processed amount" # conversion_rates: # type: string # description: Description on the Conversion Rates # example: "85% Conversion Rates" PaymentMethodsEnabled: type: array description: Details of all the payment methods enabled for the connector for the given merchant account items: properties: payment_method: type: string $ref: "#/components/schemas/PaymentMethod" example: card payment_method_types: type: array items: $ref: "#/components/schemas/PaymentMethodType" example: [CREDIT] payment_method_issuers: type: array description: List of payment method issuers to be enabled for this payment method items: type: string example: ["HDFC"] payment_schemes: type: array description: List of payment schemes accepted or has the processing capabilities of the processor items: $ref: "#/components/schemas/PaymentSchemes" example: [MASTER, VISA, DINERS] accepted_currencies: type: array description: List of currencies accepted or has the processing capabilities of the processor items: $ref: "#/components/schemas/CurrencyISO" example: [USD, EUR, AED] accepted_countries: type: array description: List of Countries accepted or has the processing capabilities of the processor items: $ref: "#/components/schemas/CountryISO" example: [US, IN] minimum_amount: type: integer description: Minimum amount supported by the processor. To be represented in the lowest denomination of the target currency (For example, for USD it should be in cents) example: 1 maximum_amount: type: integer description: Maximum amount supported by the processor. To be represented in the lowest denomination of the target currency (For example, for USD it should be in cents) example: null recurring_enabled: type: boolean description: Boolean to enable recurring payments / mandates. Default is true. example: true installment_payment_enabled: type: boolean description: Boolean to enable installment / EMI / BNPL payments. Default is true. example: true payment_experience: type: array description: Type of payment experience enabled with the connector items: $ref: "#/components/schemas/NextAction" example: ["redirect_to_url"] PaymentSchemes: type: string description: Represent the payment schemes and networks enum: - VISA - MasterCard - Discover - AMEX MerchantDetails: type: object properties: primary_contact_person: type: string description: The merchant's primary contact name maxLength: 255 example: John Test primary_email: type: string format: email description: The merchant's primary email address maxLength: 255 example: JohnTest@test.com primary_phone: type: string description: The merchant's primary phone number maxLength: 255 example: 9999999999 secondary_contact_person: type: string description: The merchant's secondary contact name maxLength: 255 example: John Test2 secondary_email: type: string format: email description: The merchant's secondary email address maxLength: 255 example: JohnTest2@test.com secondary_phone: type: string description: The merchant's secondary phone number maxLength: 255 example: 9999999998 website: type: string description: The business website of the merchant maxLength: 255 example: "www.example.com" about_business: type: string description: A brief description about merchant's business maxLength: 255 example: Online Retail with a wide selection of organic products for North America address: type: object description: The address for the merchant $ref: "#/components/schemas/Address" WebhookDetails: type: object properties: webhook_version: type: string description: The version for Webhook maxLength: 255 example: "1.0.1" webhook_username: type: string description: The user name for Webhook login maxLength: 255 example: "ekart_retail" webhook_password: type: string description: The password for Webhook login maxLength: 255 example: "password_ekart@123" payment_created_enabled: type: boolean description: If this property is true, a webhook message is posted whenever a new payment is created example: true payment_succeeded_enabled: type: boolean description: If this property is true, a webhook message is posted whenever a payment is successful example: true payment_failed_enabled: type: boolean description: If this property is true, a webhook message is posted whenever a payment fails example: true ArrayOfRoutingRules: type: array items: properties: payment_methods_incl: type: array description: The List of payment methods to include for this routing rule items: $ref: "#/components/schemas/PaymentMethod" example: [card, upi] payment_methods_excl: type: array description: The List of payment methods to exclude for this routing rule. If there is conflict between include and exclude lists, include list overrides the exclude list. items: $ref: "#/components/schemas/PaymentMethod" example: [card, upi] payment_method_types_incl: type: array description: The List of payment method types to include for this routing rule items: $ref: "#/components/schemas/PaymentMethodType" example: [credit_card, debit_card] payment_method_types_excl: type: array description: The List of payment method types to exclude for this routing rule. If there is conflict between include and exclude lists, include list overrides the exclude list. items: $ref: "#/components/schemas/PaymentMethodType" example: [credit_card, debit_card] payment_method_issuers_incl: type: array description: The List of payment method issuers to include for this routing rule items: type: string example: ["Citibank", "JPMorgan"] payment_method_issuers_excl: type: array description: The List of payment method issuers to exclude for this routing rule. If there is conflict between include and exclude lists, include list overrides the exclude list. items: type: string example: ["Citibank", "JPMorgan"] countries_incl: type: array description: The List of countries to include for this routing rule items: $ref: "#/components/schemas/CountryISO" example: [US, UK, IN] countries_excl: type: array description: The List of countries to exclude for this routing rule. If there is conflict between include and exclude lists, include list overrides the exclude list. items: $ref: "#/components/schemas/CountryISO" example: [US, UK, IN] currencies_incl: type: array description: The List of currencies to include for this routing rule items: $ref: "#/components/schemas/CurrencyISO" example: [USD, EUR] currencies_excl: type: array description: The List of currencies to exclude for this routing rule. If there is conflict between include and exclude lists, include list overrides the exclude list. items: $ref: "#/components/schemas/CurrencyISO" example: [AED, SGD] metadata_filters_keys: type: array description: List of Metadata Filters to apply for the Routing Rule. The filters are presented as 2 arrays of keys and value. This property contains all the keys. items: type: string example: ["payments.udf1", "payments.udf2"] metadata_filters_values: type: array description: List of Metadata Filters to apply for the Routing Rule. The filters are presented as 2 arrays of keys and value. This property contains all the keys. items: type: string example: ["android", "Category_Electronics"] connectors_pecking_order: type: array description: The pecking order of payment connectors (or processors) to be used for routing. The first connector in the array will be attempted for routing. If it fails, the second connector will be used till the list is exhausted. items: $ref: "#/components/schemas/PaymentConnector" example: ["stripe", "adyen", "brain_tree"] connectors_traffic_weightage_key: type: array description: An Array of Connectors (as Keys) with the associated percentage of traffic to be routed through the given connector (Expressed as an array of values) items: $ref: "#/components/schemas/PaymentConnector" example: ["stripe", "adyen", "brain_tree"] connectors_traffic_weightage_value: type: array description: An Array of Weightage (expressed in percentage) that needs to be associated with the respective connectors (Expressed as an array of keys) items: $ref: "#/components/schemas/TrafficWeightage" example: [50, 30, 20] example: [ { payment_method_types_incl: [credit_card], connectors_pecking_order: ["stripe", "adyen", "brain_tree"], }, { payment_method_types_incl: [debit_card], connectors_traffic_weightage_key: ["stripe", "adyen", "brain_tree"], connectors_traffic_weightage_value: [50, 30, 20], }, ] PaymentMethod: type: string enum: - card # Credit Card, Debit Card, Prepaid, Gift card, Travel card etc - wallet # Wallets & payment containers like Apple Pay, G Pay, PayPal, Grab Pay # - real_time_payment # UPI, PayNow, FedNow etc //TODO Application changes needed # - pay_later # BNPL like Klarna, Affirm, AfterPay, Zip, SplitIt etc //TODO Application changes needed - bank_debit # Pull payments from bank - ACH direct debit (DD), BACS DD, SEPA DD, BECS Debt - bank_redirect # Redirected to online banking portal - Netbanking/India, sofort/Europe, giropay/Germany, BanContact/Belgium, Blik/Poland, EPS/Austria, FPX/Malaysia - bank_transfer # Push payments to an account - ACH transfer, SEPA bank transfer, Multibanco example: card PaymentMethodType: type: string enum: - credit_card - debit_card - upi_intent - upi_collect # - credit_card_installments # - pay_later_installments example: credit_card # PaymentMethod: # type: string # enum: # - card # - payment_container # - bank_transfer # - bank_debit # - pay_later # - upi # - netbanking # example: card # PaymentMethodType: # type: string # enum: # - credit_card # - debit_card # - upi_intent # - upi_collect # - credit_card_installments # - pay_later_installments # example: credit_card CountryISO: type: string description: The two-letter ISO currency code maxLength: 2 minLength: 2 example: US CurrencyISO: type: string description: The three-letter ISO currency code maxLength: 3 minLength: 3 example: USD PaymentConnector: type: string description: Unique name used for identifying the Connector enum: - stripe - adyen - brain_tree - dlocal - cyber_source example: stripe TrafficWeightage: type: integer minimum: 0 maximum: 100 example: 50 NextAction: type: object description: States the next action to complete the payment properties: # type: # type: string # description: "This indicates type of action that is required in order to complete the payment with inputs from the user. This may involve actions such as redirecting the user to a URL, displaying a QR code, invoking the SDK client" # enum: # - redirect_to_url # - display_qr_code # - invoke_sdk_client # - invoke_payment_app # - trigger_api # example: "redirect_to_url" redirect_to_url: type: string description: The URL to which the customer needs to be redirected for completing the payment. example: "https://pg-redirect-page.com" display_qr_code: type: string description: The QR code data to be displayed to the customer. example: "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAADUAAAA1AQAAAADJnZ7dAAABs0lEQVR4nAGoAVf+AgFqqzCrHAACfO2eCXLx8ALIuWcFE2AgAgDMJY+7KAACAMP1N48IAAI4wJ9v8kDgAoT27OLpdxAC/g8wHJSz+ALG5FSP+HnIAt7Si9v6m+AC+hZxUPoJWAKN7C4q3rTAAi/TeN30+6ACMYHnWkM8uALzviwJR9UIAs36kzcuuqACxsgBlqjsSAJrqdLoS4QAAimoq+YS7zgCM3EsnwNXeALqzAWMrDxgAnp3ZKuU/qACbmkC+I8riALKwNCjMUMoAs3w0GTalKgCdysPb" invoke_payment_app: type: object description: Contains the data for invoking the sdk client for completing the payment. example: intent_uri: "upi://pay?pa=hhferf@abc&pn=merchant%20com&mc=5815&tid=pnf20200807108614390166&tr=20200807108614390166&tn=Transaction_Note&am=1&cu=INR" invoke_sdk_client: type: object description: Contains the data for invoking the sdk client for completing the payment. example: sdk_name: "gpay" sdk_params: { param1: "value", param2: "value" } intent_uri: "upi://pay?pa=hhferf@abc&pn=merchant%20com&mc=5815&tid=pnf20200807108614390166&tr=20200807108614390166&tn=Transaction_Note&am=1&cu=INR" trigger_api: type: object description: Provides the instructions on the next API to be triggered to complete the payment. This is applicable in cases wherein the merchant has to display a UI to the user for collecting information such as OTP, 2factor authentication details. example: api_name: "submit_otp" doc: "https://router.juspay.io/api-reference/submit_otp" PhoneNumber: type: string description: Phone number Timestamp: type: string description: ISO 8601 timestamp format: date-time ApiAuthenticationError: type: object properties: code: type: string description: The error code maxLength: 200 example: invalid_api_request message: type: string description: Description of the error, with rectification steps/ reference links to docs maxLength: 255 example: Access forbidden, invalid api-key was used type: type: string description: The category to which the error belongs maxLength: 200 example: invalid_request_error ObjectNotFoundError: type: object properties: code: type: string description: The error code maxLength: 200 example: object_not_found message: type: string description: Description of the error, with rectification steps/ reference links to docs maxLength: 255 example: Customer does not exist in records type: type: string description: The category to which the error belongs maxLength: 200 example: object_not_found BadRequestError: type: object properties: code: type: string description: The error code maxLength: 255 example: parameter_missing message: type: string description: "Missing required param: " maxLength: 255 example: "Missing required param: amount" type: type: string description: The category to which the error belongs maxLength: 255 example: invalid_request_error Error: type: object properties: code: type: string description: The error code maxLength: 255 example: parameter_missing message: type: string description: "Missing required param: " maxLength: 255 example: "Missing required param: amount" type: type: string description: The category to which the error belongs maxLength: 255 example: invalid_request_error # headers: # Cko-Request-Id: # description: The unique identifier of the request # schema: # type: string # Cko-Version: # description: The version of the API # schema: # type: string parameters: hash: name: hash in: path description: The token identifier string schema: type: string required: true mediaType: name: Accept in: header schema: type: string enum: - application/json default: application/json description: The response media type systemEventType: name: eventType in: path description: The event type schema: type: string required: true securitySchemes: ApiSecretKey: description: > Unless explicitly stated, all endpoints require authentication using your secret key. You may generate your API keys from the Juspay Dashboard. #### Format - Sandbox `sk_xxxxxxxxxxxxxxxxxxxxxxxxxx` - Production `pk_xxxxxxxxxxxxxxxxxxxxxxxxxx` name: api-key type: apiKey in: header x-cko-type: api-key AdminSecretKey: description: > Admin Key for managing Merchant Accounts and Payment Connectors In the OSS version - Developers can directly update the AdminSecretKey in the DB and start using the admin APIs to configure a new accounts and connectors In the Hosted version - The key can be obtained from the Dashboard or the Support team name: admin-api-key type: apiKey in: header x-cko-type: admin-api-key