PaySwitch
PaySwitch API Reference

Payment Methods

Server

Create and manage payment methods of customers


PaymentMethods - Create

POST
https://paysw-wiki.lab.next-on.pro/dev-router
/payment_methods
api-key (header)

Creates and stores a payment method against a customer. In case of cards, this API should be used only by PCI compliant merchants.

PaymentMethods - Create › Request Body

payment_method
​PaymentMethod · enum · required

Indicates the type of payment method. Eg: 'card', 'wallet', etc.

Enum values:
card
card_redirect
pay_later
wallet
bank_redirect
bank_transfer
crypto
bank_debit
payment_method_type
​string · enum

Indicates the sub type of payment method. Eg: 'google_pay' & 'apple_pay' for wallets.

Enum values:
ach
affirm
afterpay_clearpay
alfamart
ali_pay
ali_pay_hk
alma
amazon_pay
payment_method_issuer
​string | null

The name of the bank/ provider issuing the payment method to the end user

Example: Citibank
payment_method_issuer_code
​string · enum
Enum values:
jp_hdfc
jp_icici
jp_googlepay
jp_applepay
jp_phonepay
jp_wechat
jp_sofort
jp_giropay
​object
metadata
​object | null

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.

customer_id
​string | null · minLength: 1 · maxLength: 64

The unique identifier of the customer.

Example: cus_y3oqhf46pyzuxjbcn2giaqnb44
card_network
​string | null

The card network

Example: Visa
​
​
client_secret
​string | null

For Client based calls, SDK will use the client_secret in order to call /payment_methods Client secret will be generated whenever a new payment method is created

​
​object

PaymentMethods - Create › Responses

Payment Method Created

merchant_id
​string · required

Unique identifier for a merchant

Example: merchant_1671528864
payment_method_id
​string · required

The unique identifier of the Payment method

Example: card_rGK4Vi5iSW70MY7J2mIg
payment_method
​PaymentMethod · enum · required

Indicates the type of payment method. Eg: 'card', 'wallet', etc.

Enum values:
card
card_redirect
pay_later
wallet
bank_redirect
bank_transfer
crypto
bank_debit
customer_id
​string | null · minLength: 1 · maxLength: 64

The unique identifier of the customer.

Example: cus_y3oqhf46pyzuxjbcn2giaqnb44
payment_method_type
​string · enum

Indicates the sub type of payment method. Eg: 'google_pay' & 'apple_pay' for wallets.

Enum values:
ach
affirm
afterpay_clearpay
alfamart
ali_pay
ali_pay_hk
alma
amazon_pay
​object
recurring_enabled
​boolean | null

Indicates whether the payment method supports recurring payments. Optional.

Example: true
installment_payment_enabled
​boolean | null

Indicates whether the payment method is eligible for installment payments (e.g., EMI, BNPL). Optional.

Example: true
payment_experience
​array | null

Type of payment experience enabled with the connector

Enum values:
redirect_to_url
invoke_sdk_client
display_qr_code
one_click
link_wallet
invoke_payment_app
display_wait_screen
collect_otp
Example: ["redirect_to_url"]
metadata
​object | null

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.

created
​string | null · date-time

A timestamp (ISO 8601 code) that determines when the payment method was created

Example: 2023-01-18T11:04:09.922Z
​
last_used_at
​string | null · date-time
client_secret
​string | null

For Client based calls


List payment methods for a Merchant

GET
https://paysw-wiki.lab.next-on.pro/dev-router
/account/payment_methods
api-key (header)
or
api-key (header)

Lists the applicable payment methods for a particular Merchant ID. Use the client secret and publishable key authorization to list all relevant payment methods of the merchant for the payment corresponding to the client secret.

List payment methods for a Merchant › query Parameters

client_secret
​string | null

This is a token which expires after 15 minutes, used from the client to authenticate and create sessions from the SDK

accepted_countries
​array | null

The two-letter ISO currency code

accepted_currencies
​array | null

The three-letter ISO currency code

amount
​integer | null · int64

The amount accepted for processing by the particular payment method.

recurring_enabled
​boolean | null

Indicates whether the payment method is eligible for recurring payments

installment_payment_enabled
​boolean | null

Indicates whether the payment method is eligible for installment payments

limit
​integer | null · int64

Indicates the limit of last used payment methods

card_networks
​array | null

Indicates whether the payment method is eligible for card netwotks

List payment methods for a Merchant › Responses

Payment Methods retrieved

currency
​Currency · enum · required

The three-letter ISO 4217 currency code (e.g., "USD", "EUR") for the payment amount. This field is mandatory for creating a payment.

Enum values:
AED
AFN
ALL
AMD
ANG
AOA
ARS
AUD
​ResponsePaymentMethodsEnabled[] · required

Information about the payment method

​MandateType · required
show_surcharge_breakup_screen
​boolean · required

flag to indicate if surcharge and tax breakup screen should be shown or not

request_external_three_ds_authentication
​boolean · required

flag to indicate whether to perform external 3ds authentication

Example: true
is_tax_calculation_enabled
​boolean · required

flag that indicates whether to calculate tax on the order amount

​SdkNextAction · required
is_guest_customer
​boolean · required

indicates whether this is a guest customer flow

redirect_url
​string | null

Redirect URL of the merchant

Example: https://www.google.com
merchant_name
​string | null
payment_type
​string · enum

The type of the payment that differentiates between normal and various types of mandate payments. Use 'setup_mandate' in case of zero auth flow.

Enum values:
normal
new_mandate
setup_mandate
recurring_mandate
installment
collect_shipping_details_from_wallets
​boolean | null

flag that indicates whether to collect shipping details from wallets or from the customer

collect_billing_details_from_wallets
​boolean | null

flag that indicates whether to collect billing details from wallets or from the customer

​object

Intent-only payment details returned as part of the Payment Method List response

show_logo
​boolean | null

Whether to show logo

logo_url
​string | null

The logo URL


List payment methods for a Customer

GET
https://paysw-wiki.lab.next-on.pro/dev-router
/customers/{customer_id}/payment_methods
api-key (header)

Lists all the applicable payment methods for a particular Customer ID.

List payment methods for a Customer › path Parameters

customer_id
​string · required

The unique identifier for the customer account

List payment methods for a Customer › query Parameters

client_secret
​string | null

This is a token which expires after 15 minutes, used from the client to authenticate and create sessions from the SDK

accepted_countries
​array | null

The two-letter ISO currency code

accepted_currencies
​array | null

The three-letter ISO currency code

amount
​integer | null · int64

The amount accepted for processing by the particular payment method.

recurring_enabled
​boolean | null

Indicates whether the payment method is eligible for recurring payments

installment_payment_enabled
​boolean | null

Indicates whether the payment method is eligible for installment payments

limit
​integer | null · int64

Indicates the limit of last used payment methods

card_networks
​array | null

Indicates whether the payment method is eligible for card netwotks

List payment methods for a Customer › Responses

Payment Methods retrieved

​CustomerPaymentMethod[] · required

List of payment methods for customer

is_guest_customer
​boolean | null

Returns whether a customer id is not tied to a payment intent (only when the request is made against a client secret)


List customer saved payment methods for a Payment

GET
https://paysw-wiki.lab.next-on.pro/dev-router
/customers/payment_methods
api-key (header)

Lists all the applicable payment methods for a particular payment tied to the client_secret.

List customer saved payment methods for a Payment › query Parameters

client_secret
​string | null

This is a token which expires after 15 minutes, used from the client to authenticate and create sessions from the SDK

accepted_countries
​array | null

The two-letter ISO currency code

accepted_currencies
​array | null

The three-letter ISO currency code

amount
​integer | null · int64

The amount accepted for processing by the particular payment method.

recurring_enabled
​boolean | null

Indicates whether the payment method is eligible for recurring payments

installment_payment_enabled
​boolean | null

Indicates whether the payment method is eligible for installment payments

limit
​integer | null · int64

Indicates the limit of last used payment methods

card_networks
​array | null

Indicates whether the payment method is eligible for card netwotks

List customer saved payment methods for a Payment › Responses

Payment Methods retrieved for customer tied to its respective client-secret passed in the param

​CustomerPaymentMethod[] · required

List of payment methods for customer

is_guest_customer
​boolean | null

Returns whether a customer id is not tied to a payment intent (only when the request is made against a client secret)


Payment Method - Set Default Payment Method for Customer

POST
https://paysw-wiki.lab.next-on.pro/dev-router
/{customer_id}/payment_methods/{payment_method_id}/default
api-key (header)

Set the Payment Method as Default for the Customer.

Payment Method - Set Default Payment Method for Customer › path Parameters

customer_id
​string · required

The unique identifier for the Customer

payment_method_id
​string · required

The unique identifier for the Payment Method

Payment Method - Set Default Payment Method for Customer › Responses

Payment Method has been set as default

customer_id
​string · minLength: 1 · maxLength: 64 · required

The unique identifier of the customer.

Example: cus_y3oqhf46pyzuxjbcn2giaqnb44
payment_method
​PaymentMethod · enum · required

Indicates the type of payment method. Eg: 'card', 'wallet', etc.

Enum values:
card
card_redirect
pay_later
wallet
bank_redirect
bank_transfer
crypto
bank_debit
default_payment_method_id
​string | null

The unique identifier of the Payment method

Example: card_rGK4Vi5iSW70MY7J2mIg
payment_method_type
​string · enum

Indicates the sub type of payment method. Eg: 'google_pay' & 'apple_pay' for wallets.

Enum values:
ach
affirm
afterpay_clearpay
alfamart
ali_pay
ali_pay_hk
alma
amazon_pay

Payment Method - Retrieve

GET
https://paysw-wiki.lab.next-on.pro/dev-router
/payment_methods/{method_id}
api-key (header)

Retrieves a payment method of a customer.

Payment Method - Retrieve › path Parameters

method_id
​string · required

The unique identifier for the Payment Method

Payment Method - Retrieve › Responses

Payment Method retrieved

merchant_id
​string · required

Unique identifier for a merchant

Example: merchant_1671528864
payment_method_id
​string · required

The unique identifier of the Payment method

Example: card_rGK4Vi5iSW70MY7J2mIg
payment_method
​PaymentMethod · enum · required

Indicates the type of payment method. Eg: 'card', 'wallet', etc.

Enum values:
card
card_redirect
pay_later
wallet
bank_redirect
bank_transfer
crypto
bank_debit
customer_id
​string | null · minLength: 1 · maxLength: 64

The unique identifier of the customer.

Example: cus_y3oqhf46pyzuxjbcn2giaqnb44
payment_method_type
​string · enum

Indicates the sub type of payment method. Eg: 'google_pay' & 'apple_pay' for wallets.

Enum values:
ach
affirm
afterpay_clearpay
alfamart
ali_pay
ali_pay_hk
alma
amazon_pay
​object
recurring_enabled
​boolean | null

Indicates whether the payment method supports recurring payments. Optional.

Example: true
installment_payment_enabled
​boolean | null

Indicates whether the payment method is eligible for installment payments (e.g., EMI, BNPL). Optional.

Example: true
payment_experience
​array | null

Type of payment experience enabled with the connector

Enum values:
redirect_to_url
invoke_sdk_client
display_qr_code
one_click
link_wallet
invoke_payment_app
display_wait_screen
collect_otp
Example: ["redirect_to_url"]
metadata
​object | null

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.

created
​string | null · date-time

A timestamp (ISO 8601 code) that determines when the payment method was created

Example: 2023-01-18T11:04:09.922Z
​
last_used_at
​string | null · date-time
client_secret
​string | null

For Client based calls


Payment Method - Delete

DELETE
https://paysw-wiki.lab.next-on.pro/dev-router
/payment_methods/{method_id}
api-key (header)

Deletes a payment method of a customer.

Payment Method - Delete › path Parameters

method_id
​string · required

The unique identifier for the Payment Method

Payment Method - Delete › Responses

Payment Method deleted

payment_method_id
​string · required

The unique identifier of the Payment method

Example: card_rGK4Vi5iSW70MY7J2mIg
deleted
​boolean · required

Whether payment method was deleted or not

Example: true

Payment Method - Update

POST
https://paysw-wiki.lab.next-on.pro/dev-router
/payment_methods/{method_id}/update
api-key (header)
or
api-key (header)

Update an existing payment method of a customer. This API is useful for use cases such as updating the card number for expired cards to prevent discontinuity in recurring payments.

Payment Method - Update › path Parameters

method_id
​string · required

The unique identifier for the Payment Method

Payment Method - Update › Request Body

​object
​object
client_secret
​string | null · minLength: 30 · maxLength: 30

This is a 15 minute expiry token which shall be used from the client to authenticate and perform sessions from the SDK

Example: secret_k2uj3he2893eiu2d

Payment Method - Update › Responses

Payment Method updated

merchant_id
​string · required

Unique identifier for a merchant

Example: merchant_1671528864
payment_method_id
​string · required

The unique identifier of the Payment method

Example: card_rGK4Vi5iSW70MY7J2mIg
payment_method
​PaymentMethod · enum · required

Indicates the type of payment method. Eg: 'card', 'wallet', etc.

Enum values:
card
card_redirect
pay_later
wallet
bank_redirect
bank_transfer
crypto
bank_debit
customer_id
​string | null · minLength: 1 · maxLength: 64

The unique identifier of the customer.

Example: cus_y3oqhf46pyzuxjbcn2giaqnb44
payment_method_type
​string · enum

Indicates the sub type of payment method. Eg: 'google_pay' & 'apple_pay' for wallets.

Enum values:
ach
affirm
afterpay_clearpay
alfamart
ali_pay
ali_pay_hk
alma
amazon_pay
​object
recurring_enabled
​boolean | null

Indicates whether the payment method supports recurring payments. Optional.

Example: true
installment_payment_enabled
​boolean | null

Indicates whether the payment method is eligible for installment payments (e.g., EMI, BNPL). Optional.

Example: true
payment_experience
​array | null

Type of payment experience enabled with the connector

Enum values:
redirect_to_url
invoke_sdk_client
display_qr_code
one_click
link_wallet
invoke_payment_app
display_wait_screen
collect_otp
Example: ["redirect_to_url"]
metadata
​object | null

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.

created
​string | null · date-time

A timestamp (ISO 8601 code) that determines when the payment method was created

Example: 2023-01-18T11:04:09.922Z
​
last_used_at
​string | null · date-time
client_secret
​string | null

For Client based calls