rust/hyperswitch
1
0
Fork 0
mirror of https://github.com/juspay/hyperswitch.git synced 2025-10-29 00:49:42 +08:00
Code Issues Packages Projects Releases Wiki Activity
Files
hyperswitch/openapi/open_api_spec.yaml
Sampras Lopes d21fcc7bfc fix(config): fix docker compose local setup (#1372) 
Co-authored-by: Sanchith Hegde <22217505+SanchithHegde@users.noreply.github.com>
2023-06-07 09:45:52 +00:00

4621 lines
174 KiB
YAML
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

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</a>.
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 | <https://sandbox.hyperswitch.io> |
| Production | <https://router.juspay.io> |
# 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: <expected_data_type>"
"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: <expected_data_type>"
"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: <expected_data_type>"
# "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: <parameter_name>"
"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: <expected_data_type>"
"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: <expected_data_type>"
"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: <expected_data_type>"
"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: <expected_data_type>"
"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: <parameter_name>"
/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: <expected_data_type>"
"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: <expected_data_type>"
"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: <expected_data_type>"
"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: <expected_data_type>"
"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: <parameter_name>"
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: <parameter_name>"
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
Reference in New Issue View Git Blame Copy Permalink