rust/hyperswitch
1
0
Fork 0
mirror of https://github.com/juspay/hyperswitch.git synced 2025-10-29 17:19:15 +08:00
Code Issues Packages Projects Releases Wiki Activity

docs: Improving API Reference (#8194)

Browse Source 
Co-authored-by: hyperswitch-bot[bot] <148525504+hyperswitch-bot[bot]@users.noreply.github.com>
This commit is contained in:
GORAKHNATH YADAV
2025-06-11 15:24:45 +05:30
committed by GitHub
parent ff5b2e8e95
commit 5ce2ab2d05
9 changed files with 1399 additions and 673 deletions
Download Patch File Download Diff File Expand all files Collapse all files

34
api-reference-v2/openapi_spec.json
View File

@ -3990,7 +3990,7 @@
"properties": {
"city": {
"type": "string",
"description": "The address city",
"description": "The city, district, suburb, town, or village of the address.",
"example": "New York",
"nullable": true,
"maxLength": 50
@ -4005,21 +4005,21 @@
},
"line1": {
"type": "string",
"description": "The first line of the address",
"description": "The first line of the street address or P.O. Box.",
"example": "123, King Street",
"nullable": true,
"maxLength": 200
},
"line2": {
"type": "string",
"description": "The second line of the address",
"description": "The second line of the street address or P.O. Box (e.g., apartment, suite, unit, or building).",
"example": "Powelson Avenue",
"nullable": true,
"maxLength": 50
},
"line3": {
"type": "string",
"description": "The third line of the address",
"description": "The third line of the street address, if applicable.",
"example": "Bridgewater",
"nullable": true,
"maxLength": 50
@ -4899,7 +4899,7 @@
},
"AuthenticationType": {
"type": "string",
"description": "Pass this parameter to force 3DS or non 3DS auth for this payment. Some connectors will still force 3DS auth even in case of passing 'no_three_ds' here and vice versa. Default value is 'no_three_ds' if not set",
"description": "Specifies the type of cardholder authentication to be applied for a payment.\n\n- `ThreeDs`: Requests 3D Secure (3DS) authentication. If the card is enrolled, 3DS authentication will be activated, potentially shifting chargeback liability to the issuer.\n- `NoThreeDs`: Indicates that 3D Secure authentication should not be performed. The liability for chargebacks typically remains with the merchant. This is often the default if not specified.\n\nNote: The actual authentication behavior can also be influenced by merchant configuration and specific connector defaults. Some connectors might still enforce 3DS or bypass it regardless of this parameter.",
"enum": [
"three_ds",
"no_three_ds"
@ -7081,7 +7081,7 @@
},
"CaptureMethod": {
"type": "string",
"description": "Default value if not passed is set to 'automatic' which results in Auth and Capture in one single API request. Pass 'manual' or 'manual_multiple' in case you want do a separate Auth and Capture by first authorizing and placing a hold on your customer's funds so that you can use the Payments/Capture endpoint later to capture the authorized amount. Pass 'manual' if you want to only capture the amount later once or 'manual_multiple' if you want to capture the funds multiple times later. Both 'manual' and 'manual_multiple' are only supported by a specific list of processors",
"description": "Specifies how the payment is captured.\n- `automatic`: Funds are captured immediately after successful authorization. This is the default behavior if the field is omitted.\n- `manual`: Funds are authorized but not captured. A separate request to the `/payments/{payment_id}/capture` endpoint is required to capture the funds.",
"enum": [
"automatic",
"manual",
@ -7103,7 +7103,7 @@
"properties": {
"capture_id": {
"type": "string",
"description": "Unique identifier for the capture"
"description": "A unique identifier for this specific capture operation."
},
"status": {
"$ref": "#/components/schemas/CaptureStatus"
@ -7124,11 +7124,11 @@
},
"connector": {
"type": "string",
"description": "The connector used for the payment"
"description": "The name of the payment connector that processed this capture."
},
"authorized_attempt_id": {
"type": "string",
"description": "Unique identifier for the parent attempt on which this capture is made"
"description": "The ID of the payment attempt that was successfully authorized and subsequently captured by this operation."
},
"connector_capture_id": {
"type": "string",
@ -7142,22 +7142,22 @@
},
"error_message": {
"type": "string",
"description": "If there was an error while calling the connector the error message is received here",
"description": "A human-readable message from the connector explaining why this capture operation failed, if applicable.",
"nullable": true
},
"error_code": {
"type": "string",
"description": "If there was an error while calling the connectors the code is received here",
"description": "The error code returned by the connector if this capture operation failed. This code is connector-specific.",
"nullable": true
},
"error_reason": {
"type": "string",
"description": "If there was an error while calling the connectors the reason is received here",
"description": "A more detailed reason from the connector explaining the capture failure, if available.",
"nullable": true
},
"reference_id": {
"type": "string",
"description": "Reference to the capture at connector side",
"description": "The connector's own reference or transaction ID for this specific capture operation. Useful for reconciliation.",
"nullable": true
}
}
@ -9148,7 +9148,7 @@
},
"Currency": {
"type": "string",
"description": "The three letter ISO currency code in uppercase. Eg: 'USD' for the United States Dollar.",
"description": "The three-letter ISO 4217 currency code (e.g., \"USD\", \"EUR\") for the payment amount. This field is mandatory for creating a payment.",
"enum": [
"AED",
"AFN",
@ -11308,7 +11308,7 @@
},
"FutureUsage": {
"type": "string",
"description": "Indicates that you intend to make future payments with the payment methods used for this Payment. 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.\n- On_session - Payment method saved only at hyperswitch when consent is provided by the user. CVV will asked during the returning user payment\n- Off_session - Payment method saved at both hyperswitch and Processor when consent is provided by the user. No input is required during the returning user payment.",
"description": "Specifies how the payment method can be used for future payments.\n- `off_session`: The payment method can be used for future payments when the customer is not present.\n- `on_session`: The payment method is intended for use only when the customer is present during checkout.\nIf omitted, defaults to `on_session`.",
"enum": [
"off_session",
"on_session"
@ -12364,7 +12364,7 @@
},
"IntentStatus": {
"type": "string",
"description": "The status of the current payment that was made",
"description": "Represents the overall status of a payment intent.\nThe status transitions through various states depending on the payment method, confirmation, capture method, and any subsequent actions (like customer authentication or manual capture).",
"enum": [
"succeeded",
"failed",
@ -17959,7 +17959,6 @@
},
"payment_token": {
"type": "string",
"description": "Provide a reference to a stored payment method",
"example": "187282ab-40ef-47a9-9206-5099ba31e432",
"nullable": true
}
@ -24028,6 +24027,7 @@
},
"ThreeDsCompletionIndicator": {
"type": "string",
"description": "Indicates if 3DS method data was successfully completed or not",
"enum": [
"Y",
"N",

256
api-reference/api-reference/payments/payment--flows.mdx Normal file
View File

@ -0,0 +1,256 @@
---
tags: [Payments]
sidebarTitle: "Payment Flows"
icon: "arrows-retweet"
iconType: "solid"
---
Hyperswitch provides flexible payment processing with multiple flow patterns to accommodate different business needs. The system supports one-time payments, saved payment methods, and recurring billing through a comprehensive API design.
```mermaid
graph TD
A["Payment Request"] --> B{"Payment Type"}
B -->|One-time| C["One-time Payment Flows"]
B -->|Save for Future| D["Payment Method Storage"]
B -->|Recurring| E["Recurring Payment Flows"]
C --> C1["Instant Payment"]
C --> C2["Manual Capture"]
C --> C3["Decoupled Flow"]
C --> C4["3DS Authentication"]
D --> D1["Save During Payment"]
D --> D2["List Saved Methods"]
E --> E1["Setup (CIT)"]
E --> E2["Execute (MIT)"]
```
## One-Time Payment Patterns
### 1. Instant Payment (Automatic Capture)
**Use Case:** Simple, immediate payment processing
**Endpoint:**
`POST /payments`
```mermaid
sequenceDiagram
participant Client
participant Hyperswitch
participant Processor
Client->>Hyperswitch: POST /payments<br/>{confirm: true, capture_method: "automatic"}
Hyperswitch->>Processor: Authorize + Capture
Processor-->>Hyperswitch: Payment Complete
Hyperswitch-->>Client: Status: succeeded
```
**Required Fields:**
- `confirm: true`
- `capture_method: "automatic"`
- `payment_method`
**Final Status:** `succeeded`
### 2. Two-Step Manual Capture
**Use Case:** Deferred settlement (e.g., ship before charging)
```mermaid
sequenceDiagram
participant Client
participant Hyperswitch
participant Processor
Client->>Hyperswitch: POST /payments<br/>{confirm: true, capture_method: "manual"}
Hyperswitch->>Processor: Authorize Only
Processor-->>Hyperswitch: Authorization Hold
Hyperswitch-->>Client: Status: requires_capture
Note over Client: Ship goods, then capture
Client->>Hyperswitch: POST /payments/{id}/capture
Hyperswitch->>Processor: Capture Funds
Processor-->>Hyperswitch: Capture Complete
Hyperswitch-->>Client: Status: succeeded
```
**Flow:**
1. **Authorize:** `POST /payments` with `capture_method: "manual"`
2. **Status:** `requires_capture`
3. **Capture:** `POST /payments/{payment_id}/capture`
4. **Final Status:** `succeeded`
### 3. Fully Decoupled Flow
**Use Case:** Complex checkout journeys with multiple modification steps. Useful in headless checkout or B2B portals where data is filled progressively.
```mermaid
sequenceDiagram
participant Client
participant Hyperswitch
Client->>Hyperswitch: POST /payments<br/>(Create Intent)
Hyperswitch-->>Client: payment_id + client_secret
Client->>Hyperswitch: POST /payments/{id}<br/>(Update: customer, amount, etc.)
Hyperswitch-->>Client: Updated Intent
Client->>Hyperswitch: POST /payments/{id}/confirm<br/>(Final Confirmation)
Hyperswitch-->>Client: Status: succeeded/requires_capture
opt Manual Capture
Client->>Hyperswitch: POST /payments/{id}/capture
Hyperswitch-->>Client: Status: succeeded
end
```
**Endpoints:**
- **Create:**
`POST /payments`
- **Update:**
`POST /payments/{payment_id}`
- **Confirm:**
`POST /payments/{payment_id}/confirm`
- **Capture:**
`POST /payments/{payment_id}/capture` (if manual)
### 4. 3D Secure Authentication Flow
**Use Case:** Enhanced security with customer authentication
```mermaid
sequenceDiagram
participant Client
participant Hyperswitch
participant Customer
participant Bank
Client->>Hyperswitch: POST /payments<br/>{authentication_type: "three_ds"}
Hyperswitch-->>Client: Status: requires_customer_action<br/>+ redirect_url
Client->>Customer: Redirect to 3DS page
Customer->>Bank: Complete 3DS Challenge
Bank-->>Hyperswitch: Authentication Result
Hyperswitch->>Hyperswitch: Resume Payment Processing
Hyperswitch-->>Client: Status: succeeded
```
**Additional Fields:**
- `authentication_type: "three_ds"`
**Status Progression:** `processing` → `requires_customer_action` → `succeeded`
## Payment Method Management
### 1. Saving Payment Methods
```mermaid
graph LR
A["Payment Request"] --> B["Add setup_future_usage"]
B --> C{"Usage Type"}
C -->|"off_session"| D["For Recurring/MIT"]
C -->|"on_session"| E["For Customer-Present"]
D --> F["payment_method_id Returned"]
E --> F
```
**During Payment Creation:**
- Add `setup_future_usage: "off_session"` or `"on_session"`
- Include `customer_id`
- **Result:** `payment_method_id` returned on success
**Understanding `setup_future_usage`:**
- **`on_session`**: Use when the customer is actively present during the transaction. This is typical for scenarios like saving card details for faster checkouts in subsequent sessions where the customer will still be present to initiate the payment (e.g., card vaulting for e-commerce sites).
- **`off_session`**: Use when you intend to charge the customer later without their active involvement at the time of charge. This is suitable for subscriptions, recurring billing, or merchant-initiated transactions (MITs) where the customer has pre-authorized future charges.
### 2. Using Saved Payment Methods
```mermaid
sequenceDiagram
participant Client
participant Hyperswitch
Client->>Hyperswitch: POST /payments/create<br/>{customer_id}
Hyperswitch-->>Client: client_secret
Client->>Hyperswitch: GET /customers/payment_methods<br/>{client_secret, publishable_key}
Hyperswitch-->>Client: List of payment_tokens
Client->>Hyperswitch: POST /payments/{id}/confirm<br/>{payment_token}
Hyperswitch-->>Client: Payment Result
```
**Steps:**
1. **Initiate:** Create payment with `customer_id`
2. **List:** Get saved cards via `GET /customers/payment_methods`
3. **Confirm:** Use selected `payment_token` in confirm call
### PCI Compliance and `payment_method_id`
Storing `payment_method_id` (which is a token representing the actual payment instrument, which could be a payment token, network token, or payment processor token) significantly reduces your PCI DSS scope. Hyperswitch securely stores the sensitive card details and provides you with this token. While you still need to ensure your systems handle `payment_method_id` and related customer data securely, you avoid the complexities of storing raw card numbers. Always consult with a PCI QSA to understand your specific compliance obligations.
## Recurring Payment Flows
### 3. Customer-Initiated Transaction (CIT) Setup
```mermaid
graph TD
A["CIT Setup"] --> B{"Setup Type"}
B -->|"With Charge"| C["Amount > 0<br/>setup_future_usage: off_session"]
B -->|"Zero Dollar Auth"| D["Amount: 0<br/>payment_type: setup_mandate"]
C --> E["payment_method_id"]
D --> E
```
**Option 1 - Setup with Charge:**
- `setup_future_usage: "off_session"`
- `amount > 0`
**Option 2 - Zero Dollar Authorization:**
- `setup_future_usage: "off_session"`
- `amount: 0`
- `payment_type: "setup_mandate"`
### 4. Merchant-Initiated Transaction (MIT) Execution
```mermaid
sequenceDiagram
participant Merchant
participant Hyperswitch
participant Processor
Note over Merchant: Subscription billing trigger
Merchant->>Hyperswitch: POST /payments<br/>{off_session: true, recurring_details}
Hyperswitch->>Processor: Process with saved payment_method_id
Processor-->>Hyperswitch: Payment Result
Hyperswitch-->>Merchant: Status: succeeded
```
**Required Fields:**
- `off_session: true`
- `recurring_details: { payment_method_id: "<from_setup>" }`
**Use Case:** Subscription charges, scheduled billing without customer interaction
## Status Flow Summary
```mermaid
stateDiagram-v2
[*] --> RequiresConfirmation
RequiresConfirmation --> Processing: confirm=true
Processing --> RequiresCustomerAction: 3DS needed
RequiresCustomerAction --> Processing: 3DS complete
Processing --> RequiresCapture: manual capture
Processing --> Succeeded: automatic capture
RequiresCapture --> Succeeded: capture API call
RequiresCapture --> PartiallyCaptured: partial capture
PartiallyCaptured --> [*]
Succeeded --> [*]
Processing --> Failed: payment failed
Failed --> [*]
```
## Notes
- **Terminal States:** `succeeded`, `failed`, `cancelled`, `partially_captured` are terminal states requiring no further action
- **Capture Methods:** System supports `automatic` (funds captured immediately), `manual` (funds captured in a separate step), `manual_multiple` (funds captured in multiple partial amounts via separate steps), and `scheduled` (funds captured automatically at a future predefined time) capture methods.
- **Authentication:** 3DS authentication automatically resumes payment processing after customer completion
- **MIT Compliance:** Off-session recurring payments follow industry standards for merchant-initiated transactions

7
api-reference/api-reference/payments/Introduction--to--payments.mdx → api-reference/api-reference/payments/setup--instructions.mdx
View File

@ -1,11 +1,9 @@
---
tags: [Payments]
sidebarTitle: "Getting Started with Payments"
icon: "circle-play"
sidebarTitle: "Setup Instructions"
icon: "flag"
iconType: "solid"
color: "Green"
---
The **Hyperswitch Payments API** enables businesses to **accept, process, and manage payments seamlessly**. It supports the entire **payment lifecycle**—from creation to capture, refunds, and disputes—allowing smooth integration of **various payment methods** into any application with minimal complexity.
### How to try your first payment through hyperswitch?
@ -57,4 +55,3 @@ Each option has specific nuances, we have mentioned the differences in the below
Test the use cases you are interested in and in case of difficulty, feel free to contact us on our [slack channel](https://join.slack.com/t/hyperswitch-io/shared_invite/zt-2jqxmpsbm-WXUENx022HjNEy~Ark7Orw)
</Step>
</Steps>
---

377
api-reference/docs.json Normal file
View File

@ -0,0 +1,377 @@
{
"$schema": "https://mintlify.com/docs.json",
"theme": "mint",
"name": "Hyperswitch",
"colors": {
"primary": "#4F8EFF",
"light": "#6BA3FF",
"dark": "#2563EB"
},
"favicon": "/favicon.png",
"navigation": {
"tabs": [
{
"tab": "Documentation",
"groups": [
{
"group": "Get Started",
"pages": [
"introduction"
]
},
{
"group": "Essentials",
"pages": [
"essentials/error_codes",
"essentials/rate_limit",
"essentials/go-live"
]
},
{
"group": "Payments Core APIs",
"pages": [
"api-reference/payments/setup--instructions",
"api-reference/payments/payment--flows",
{
"group": "Payments",
"pages": [
"api-reference/payments/payments--create",
"api-reference/payments/payments--update",
"api-reference/payments/payments--confirm",
"api-reference/payments/payments--retrieve",
"api-reference/payments/payments--cancel",
"api-reference/payments/payments--capture",
"api-reference/payments/payments--incremental-authorization",
"api-reference/payments/payments--session-token",
"api-reference/payments/payments-link--retrieve",
"api-reference/payments/payments--list",
"api-reference/payments/payments--external-3ds-authentication",
"api-reference/payments/payments--complete-authorize",
"api-reference/payments/payments--update-metadata"
]
},
{
"group": "Payment Methods",
"pages": [
"api-reference/payment-methods/paymentmethods--create",
"api-reference/payment-methods/payment-method--retrieve",
"api-reference/payment-methods/payment-method--update",
"api-reference/payment-methods/payment-method--delete",
"api-reference/payment-methods/payment-method--set-default-payment-method-for-customer",
"api-reference/payment-methods/list-payment-methods-for-a-merchant",
"api-reference/payment-methods/list-customer-saved-payment-methods-for-a-payment",
"api-reference/payment-methods/list-payment-methods-for-a-customer",
"api-reference/customer-set-default-payment-method/customers--set-default-payment-method"
]
},
{
"group": "Customers",
"pages": [
"api-reference/customers/customers--create",
"api-reference/customers/customers--retrieve",
"api-reference/customers/customers--update",
"api-reference/customers/customers--delete",
"api-reference/customers/customers--list"
]
},
{
"group": "Mandates",
"pages": [
"api-reference/mandates/mandates--revoke-mandate",
"api-reference/mandates/mandates--retrieve-mandate",
"api-reference/mandates/mandates--customer-mandates-list"
]
},
{
"group": "Refunds",
"pages": [
"api-reference/refunds/refunds--create",
"api-reference/refunds/refunds--update",
"api-reference/refunds/refunds--retrieve",
"api-reference/refunds/refunds--list"
]
},
{
"group": "Disputes",
"pages": [
"api-reference/disputes/disputes--retrieve",
"api-reference/disputes/disputes--list"
]
},
{
"group": "Payouts",
"pages": [
"api-reference/payouts/payouts--create",
"api-reference/payouts/payouts--update",
"api-reference/payouts/payouts--cancel",
"api-reference/payouts/payouts--fulfill",
"api-reference/payouts/payouts--confirm",
"api-reference/payouts/payouts--retrieve",
"api-reference/payouts/payouts--list",
"api-reference/payouts/payouts--list-filters",
"api-reference/payouts/payouts--filter"
]
}
]
},
{
"group": "Account management APIs",
"pages": [
{
"group": "Organization",
"pages": [
"api-reference/organization/organization--create",
"api-reference/organization/organization--retrieve",
"api-reference/organization/organization--update"
]
},
{
"group": "Merchant Account",
"pages": [
"api-reference/merchant-account/merchant-account--create",
"api-reference/merchant-account/merchant-account--retrieve",
"api-reference/merchant-account/merchant-account--update",
"api-reference/merchant-account/merchant-account--delete",
"api-reference/merchant-account/merchant-account--kv-status"
]
},
{
"group": "Business Profile",
"pages": [
"api-reference/business-profile/business-profile--create",
"api-reference/business-profile/business-profile--update",
"api-reference/business-profile/business-profile--retrieve",
"api-reference/business-profile/business-profile--delete",
"api-reference/business-profile/business-profile--list"
]
},
{
"group": "API Key",
"pages": [
"api-reference/api-key/api-key--create",
"api-reference/api-key/api-key--retrieve",
"api-reference/api-key/api-key--update",
"api-reference/api-key/api-key--revoke",
"api-reference/api-key/api-key--list"
]
},
{
"group": "Merchant Connector Account",
"pages": [
"api-reference/merchant-connector-account/merchant-connector--create",
"api-reference/merchant-connector-account/merchant-connector--retrieve",
"api-reference/merchant-connector-account/merchant-connector--update",
"api-reference/merchant-connector-account/merchant-connector--delete",
"api-reference/merchant-connector-account/merchant-connector--list"
]
},
{
"group": "GSM (Global Status Mapping)",
"pages": [
"api-reference/gsm/gsm--create",
"api-reference/gsm/gsm--get",
"api-reference/gsm/gsm--update",
"api-reference/gsm/gsm--delete"
]
}
]
},
{
"group": "Other APIs",
"pages": [
{
"group": "Event",
"pages": [
"api-reference/event/events--list",
"api-reference/event/events--delivery-attempt-list",
"api-reference/event/events--manual-retry"
]
},
{
"group": "Poll",
"pages": [
"api-reference/poll/poll--retrieve-poll-status"
]
},
{
"group": "Blocklist",
"pages": [
"api-reference/blocklist/get-blocklist",
"api-reference/blocklist/post-blocklist",
"api-reference/blocklist/delete-blocklist",
"api-reference/blocklist/post-blocklisttoggle"
]
},
{
"group": "Routing",
"pages": [
"api-reference/routing/routing--list",
"api-reference/routing/routing--create",
"api-reference/routing/routing--retrieve-config",
"api-reference/routing/routing--deactivate",
"api-reference/routing/routing--retrieve-default-config",
"api-reference/routing/routing--update-default-config",
"api-reference/routing/routing--retrieve-default-for-profile",
"api-reference/routing/routing--update-default-for-profile",
"api-reference/routing/routing--retrieve",
"api-reference/routing/routing--activate-config"
]
},
{
"group": "Relay",
"pages": [
"api-reference/relay/relay",
"api-reference/relay/relay--retrieve"
]
},
{
"group": "Schemas",
"pages": [
"api-reference/schemas/outgoing--webhook"
]
}
]
}
]
},
{
"tab": "Locker API Reference",
"groups": [
{
"group": "Hyperswitch Card Vault",
"pages": [
"locker-api-reference/overview"
]
},
{
"group": "API Reference",
"pages": [
{
"group": "Locker - Health",
"pages": [
"locker-api-reference/locker-health/get-health"
]
},
{
"group": "Locker - Key Custodian",
"pages": [
"locker-api-reference/key-custodian/provide-key-1",
"locker-api-reference/key-custodian/provide-key-2",
"locker-api-reference/key-custodian/unlock-the-locker"
]
},
{
"group": "Locker - Cards",
"pages": [
"locker-api-reference/cards/add-data-in-locker",
"locker-api-reference/cards/delete-data-from-locker",
"locker-api-reference/cards/retrieve-data-from-locker",
"locker-api-reference/cards/get-or-insert-the-card-fingerprint"
]
}
]
}
]
},
{
"tab": "Intelligent Router API Reference",
"groups": [
{
"group": "Hyperswitch Intelligent Router",
"pages": [
"intelligent-router-api-reference/overview"
]
},
{
"group": "API Reference",
"pages": [
{
"group": "Success Rate",
"pages": [
"intelligent-router-api-reference/success-rate/fetch-success-rate-for-an-entity",
"intelligent-router-api-reference/success-rate/update-success-rate-window",
"intelligent-router-api-reference/success-rate/invalidate-windows",
"intelligent-router-api-reference/success-rate/fetch-entity-and-global-success-rates"
]
},
{
"group": "Elimination",
"pages": [
"intelligent-router-api-reference/elimination/fetch-eliminated-processor-list",
"intelligent-router-api-reference/elimination/update-elimination-bucket",
"intelligent-router-api-reference/elimination/invalidate-elimination-bucket"
]
},
{
"group": "Contract Routing",
"pages": [
"intelligent-router-api-reference/contract-routing/fetch-contract-scores-for-an-entity",
"intelligent-router-api-reference/contract-routing/update-contract-information-for-an-entity",
"intelligent-router-api-reference/contract-routing/invalidate-contract-information-for-an-entity"
]
},
{
"group": "Static Routing",
"pages": [
"intelligent-router-api-reference/static-routing/create-a-routing-rule",
"intelligent-router-api-reference/static-routing/evaluate-routing-rule"
]
}
]
}
]
}
]
},
"logo": {
"light": "/logo/light.svg",
"dark": "/logo/dark.svg"
},
"api": {
"openapi": [
"openapi_spec.json",
"rust_locker_open_api_spec.yml"
]
},
"background": {
"color": {
"light": "#FAFBFC",
"dark": "#1d1d1d"
}
},
"navbar": {
"links": [
{
"label": "Contact Us",
"href": "https://inviter.co/hyperswitch-slack"
}
],
"primary": {
"type": "button",
"label": "Self-Deploy",
"href": "https://docs.hyperswitch.io/hyperswitch-open-source/overview"
}
},
"footer": {
"socials": {
"github": "https://github.com/juspay/hyperswitch",
"linkedin": "https://www.linkedin.com/company/hyperswitch"
}
},
"integrations": {
"gtm": {
"tagId": "GTM-PLBNKQFQ"
},
"mixpanel": {
"projectToken": "b00355f29d9548d1333608df71d5d53d"
}
},
"contextual": {
"options": [
"copy",
"claude",
"chatgpt",
"view"
]
}
}

366
api-reference/mint.json
View File

@ -1,366 +0,0 @@
{
"$schema": "https://mintlify.com/schema.json",
"name": "Hyperswitch",
"logo": {
"dark": "/logo/dark.svg",
"light": "/logo/light.svg"
},
"topbarLinks": [
{
"name": "Contact Us",
"url": "https://join.slack.com/t/hyperswitch-io/shared_invite/zt-2jqxmpsbm-WXUENx022HjNEy~Ark7Orw"
}
],
"topbarCtaButton": {
"type": "link",
"url": "https://docs.hyperswitch.io/hyperswitch-open-source/overview",
"name": "Self-Deploy"
},
"favicon": "/favicon.png",
"colors": {
"primary": "#006DF9",
"light": "#006DF9",
"dark": "#006DF9",
"background": {
"dark": "#242F48"
}
},
"sidebar": {
"items": "card"
},
"tabs": [
{
"name": "Locker API Reference",
"url": "locker-api-reference"
},
{
"name": "Intelligent Router API Reference",
"url": "intelligent-router-api-reference"
}
],
"navigation": [
{
"group": "Get Started",
"pages": [
"introduction"
]
},
{
"group": "Essentials",
"pages": [
"essentials/error_codes",
"essentials/rate_limit",
"essentials/go-live"
]
},
{
"group": "API Reference",
"pages": [
{
"group": "Payments",
"pages": [
"api-reference/payments/Introduction--to--payments",
"api-reference/payments/payments--create",
"api-reference/payments/payments--update",
"api-reference/payments/payments--confirm",
"api-reference/payments/payments--retrieve",
"api-reference/payments/payments--cancel",
"api-reference/payments/payments--capture",
"api-reference/payments/payments--incremental-authorization",
"api-reference/payments/payments--session-token",
"api-reference/payments/payments-link--retrieve",
"api-reference/payments/payments--list",
"api-reference/payments/payments--external-3ds-authentication",
"api-reference/payments/payments--complete-authorize",
"api-reference/payments/payments--update-metadata"
]
},
{
"group": "Payment Methods",
"pages": [
"api-reference/payment-methods/paymentmethods--create",
"api-reference/payment-methods/payment-method--retrieve",
"api-reference/payment-methods/payment-method--update",
"api-reference/payment-methods/payment-method--delete",
"api-reference/payment-methods/payment-method--set-default-payment-method-for-customer",
"api-reference/payment-methods/list-payment-methods-for-a-merchant",
"api-reference/payment-methods/list-customer-saved-payment-methods-for-a-payment",
"api-reference/payment-methods/list-payment-methods-for-a-customer",
"api-reference/customer-set-default-payment-method/customers--set-default-payment-method"
]
},
{
"group": "Customers",
"pages": [
"api-reference/customers/customers--create",
"api-reference/customers/customers--retrieve",
"api-reference/customers/customers--update",
"api-reference/customers/customers--delete",
"api-reference/customers/customers--list"
]
},
{
"group": "Mandates",
"pages": [
"api-reference/mandates/mandates--revoke-mandate",
"api-reference/mandates/mandates--retrieve-mandate",
"api-reference/mandates/mandates--customer-mandates-list"
]
},
{
"group": "Refunds",
"pages": [
"api-reference/refunds/refunds--create",
"api-reference/refunds/refunds--update",
"api-reference/refunds/refunds--retrieve",
"api-reference/refunds/refunds--list"
]
},
{
"group": "Disputes",
"pages": [
"api-reference/disputes/disputes--retrieve",
"api-reference/disputes/disputes--list"
]
},
{
"group": "Payouts",
"pages": [
"api-reference/payouts/payouts--create",
"api-reference/payouts/payouts--update",
"api-reference/payouts/payouts--cancel",
"api-reference/payouts/payouts--fulfill",
"api-reference/payouts/payouts--confirm",
"api-reference/payouts/payouts--retrieve",
"api-reference/payouts/payouts--list",
"api-reference/payouts/payouts--list-filters",
"api-reference/payouts/payouts--filter"
]
},
{
"group": "Event",
"pages": [
"api-reference/event/events--list",
"api-reference/event/events--delivery-attempt-list",
"api-reference/event/events--manual-retry"
]
},
{
"group": "Poll",
"pages": [
"api-reference/poll/poll--retrieve-poll-status"
]
},
{
"group": "Blocklist",
"pages": [
"api-reference/blocklist/get-blocklist",
"api-reference/blocklist/post-blocklist",
"api-reference/blocklist/delete-blocklist",
"api-reference/blocklist/post-blocklisttoggle"
]
},
{
"group": "Routing",
"pages": [
"api-reference/routing/routing--list",
"api-reference/routing/routing--create",
"api-reference/routing/routing--retrieve-config",
"api-reference/routing/routing--deactivate",
"api-reference/routing/routing--retrieve-default-config",
"api-reference/routing/routing--update-default-config",
"api-reference/routing/routing--retrieve-default-for-profile",
"api-reference/routing/routing--update-default-for-profile",
"api-reference/routing/routing--retrieve",
"api-reference/routing/routing--activate-config"
]
},
{
"group": "Relay",
"pages": [
"api-reference/relay/relay",
"api-reference/relay/relay--retrieve"
]
},
{
"group": "3DS Decision",
"pages": [
"api-reference/3ds-decision-rule/execute-a-3ds-decision-rule-based-on-the-provided-input"
]
},
{
"group": "Schemas",
"pages": [
"api-reference/schemas/outgoing--webhook"
]
}
]
},
{
"group": "Admin API based",
"pages": [
{
"group": "Organization",
"pages": [
"api-reference/organization/organization--create",
"api-reference/organization/organization--retrieve",
"api-reference/organization/organization--update"
]
},
{
"group": "Merchant Account",
"pages": [
"api-reference/merchant-account/merchant-account--create",
"api-reference/merchant-account/merchant-account--retrieve",
"api-reference/merchant-account/merchant-account--update",
"api-reference/merchant-account/merchant-account--delete",
"api-reference/merchant-account/merchant-account--kv-status"
]
},
{
"group": "Business Profile",
"pages": [
"api-reference/business-profile/business-profile--create",
"api-reference/business-profile/business-profile--update",
"api-reference/business-profile/business-profile--retrieve",
"api-reference/business-profile/business-profile--delete",
"api-reference/business-profile/business-profile--list"
]
},
{
"group": "API Key",
"pages": [
"api-reference/api-key/api-key--create",
"api-reference/api-key/api-key--retrieve",
"api-reference/api-key/api-key--update",
"api-reference/api-key/api-key--revoke",
"api-reference/api-key/api-key--list"
]
},
{
"group": "Merchant Connector Account",
"pages": [
"api-reference/merchant-connector-account/merchant-connector--create",
"api-reference/merchant-connector-account/merchant-connector--retrieve",
"api-reference/merchant-connector-account/merchant-connector--update",
"api-reference/merchant-connector-account/merchant-connector--delete",
"api-reference/merchant-connector-account/merchant-connector--list"
]
},
{
"group": "GSM (Global Status Mapping)",
"pages": [
"api-reference/gsm/gsm--create",
"api-reference/gsm/gsm--get",
"api-reference/gsm/gsm--update",
"api-reference/gsm/gsm--delete"
]
},
{
"group": "Event",
"pages": [
"api-reference/event/events--list",
"api-reference/event/events--delivery-attempt-list",
"api-reference/event/events--manual-retry"
]
}
]
},
{
"group": "Hyperswitch Card Vault",
"pages": [
"locker-api-reference/overview"
]
},
{
"group": "API Reference",
"pages": [
{
"group": "Locker - Health",
"pages": [
"locker-api-reference/locker-health/get-health"
]
},
{
"group": "Locker - Key Custodian",
"pages": [
"locker-api-reference/key-custodian/provide-key-1",
"locker-api-reference/key-custodian/provide-key-2",
"locker-api-reference/key-custodian/unlock-the-locker"
]
},
{
"group": "Locker - Cards",
"pages": [
"locker-api-reference/cards/add-data-in-locker",
"locker-api-reference/cards/delete-data-from-locker",
"locker-api-reference/cards/retrieve-data-from-locker",
"locker-api-reference/cards/get-or-insert-the-card-fingerprint"
]
}
]
},
{
"group": "Hyperswitch Intelligent Router",
"pages": [
"intelligent-router-api-reference/overview"
]
},
{
"group": "API Reference",
"pages": [
{
"group": "Success Rate",
"pages": [
"intelligent-router-api-reference/success-rate/fetch-success-rate-for-an-entity",
"intelligent-router-api-reference/success-rate/update-success-rate-window",
"intelligent-router-api-reference/success-rate/invalidate-windows",
"intelligent-router-api-reference/success-rate/fetch-entity-and-global-success-rates"
]
},
{
"group": "Elimination",
"pages": [
"intelligent-router-api-reference/elimination/fetch-eliminated-processor-list",
"intelligent-router-api-reference/elimination/update-elimination-bucket",
"intelligent-router-api-reference/elimination/invalidate-elimination-bucket"
]
},
{
"group": "Contract Routing",
"pages": [
"intelligent-router-api-reference/contract-routing/fetch-contract-scores-for-an-entity",
"intelligent-router-api-reference/contract-routing/update-contract-information-for-an-entity",
"intelligent-router-api-reference/contract-routing/invalidate-contract-information-for-an-entity"
]
},
{
"group": "Static Routing",
"pages": [
"intelligent-router-api-reference/static-routing/create-a-routing-rule",
"intelligent-router-api-reference/static-routing/evaluate-routing-rule"
]
}
]
}
],
"footerSocials": {
"github": "https://github.com/juspay/hyperswitch",
"linkedin": "https://www.linkedin.com/company/hyperswitch"
},
"openapi": [
"openapi_spec.json",
"rust_locker_open_api_spec.yml"
],
"api": {
"maintainOrder": true
},
"analytics": {
"gtm": {
"tagId": "GTM-PLBNKQFQ"
},
"mixpanel": {
"projectToken": "b00355f29d9548d1333608df71d5d53d"
}
}
}

603
api-reference/openapi_spec.json
View File

File diff suppressed because it is too large Load Diff

120
crates/api_models/src/payments.rs
View File

@ -73,7 +73,6 @@ pub struct ConnectorCode {
pub connector: api_enums::Connector,
pub code: String,
}
#[derive(Debug, Clone, serde::Serialize, serde::Deserialize, ToSchema, PartialEq, Eq)]
pub struct BankCodeResponse {
#[schema(value_type = Vec<BankNames>)]
@ -852,23 +851,23 @@ impl AmountDetailsUpdate {
#[generate_schemas(PaymentsCreateRequest, PaymentsUpdateRequest, PaymentsConfirmRequest)]
#[serde(deny_unknown_fields)]
pub struct PaymentsRequest {
/// The payment amount. Amount for the payment in the lowest denomination of the currency, (i.e) in cents for USD denomination, in yen for JPY denomination etc. E.g., Pass 100 to charge $1.00 and 1 for 1¥ since ¥ is a zero-decimal currency. Read more about [the Decimal and Non-Decimal Currencies](https://github.com/juspay/hyperswitch/wiki/Decimal-and-Non%E2%80%90Decimal-Currencies)
/// The primary amount for the payment, provided in the lowest denomination of the specified currency (e.g., 6540 for $65.40 USD). This field is mandatory for creating a payment.
#[schema(value_type = Option<u64>, example = 6540)]
#[serde(default, deserialize_with = "amount::deserialize_option")]
#[mandatory_in(PaymentsCreateRequest = u64)]
// Makes the field mandatory in PaymentsCreateRequest
pub amount: Option<Amount>,
/// Total tax amount applicable to the order
/// Total tax amount applicable to the order, in the lowest denomination of the currency.
#[schema(value_type = Option<i64>, example = 6540)]
pub order_tax_amount: Option<MinorUnit>,
/// The three letter ISO currency code in uppercase. Eg: 'USD' to charge US Dollars
/// The three-letter ISO 4217 currency code (e.g., "USD", "EUR") for the payment amount. This field is mandatory for creating a payment.
#[schema(example = "USD", value_type = Option<Currency>)]
#[mandatory_in(PaymentsCreateRequest = Currency)]
pub currency: Option<api_enums::Currency>,
/// 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. Also, it must be less than or equal to the original payment account.
/// The amount to be captured from the user's payment method, in the lowest denomination. If not provided, and `capture_method` is `automatic`, the full payment `amount` will be captured. If `capture_method` is `manual`, this can be specified in the `/capture` call. Must be less than or equal to the authorized amount.
#[schema(value_type = Option<i64>, example = 6540)]
pub amount_to_capture: Option<MinorUnit>,
@ -876,8 +875,7 @@ pub struct PaymentsRequest {
#[schema(value_type = Option<i64>, example = 6540)]
pub shipping_cost: Option<MinorUnit>,
/// Unique identifier for the payment. This ensures idempotency for multiple payments
/// that have been done by a single merchant. The value for this field can be specified in the request, it will be auto generated otherwise and returned in the API response.
/// Optional. A merchant-provided unique identifier for the payment, contains 30 characters long (e.g., "pay_mbabizu24mvu3mela5njyhpit4"). If provided, it ensures idempotency for the payment creation request. If omitted, Hyperswitch generates a unique ID for the payment.
#[schema(
value_type = Option<String>,
min_length = 30,
@ -920,7 +918,7 @@ pub struct PaymentsRequest {
#[remove_in(PaymentsUpdateRequest, PaymentsCreateRequest, PaymentsConfirmRequest)]
pub capture_on: Option<PrimitiveDateTime>,
/// Whether to confirm the payment (if applicable). It can be used to completely process a payment by attaching a payment method, setting `confirm=true` and `capture_method = automatic` in the *Payments/Create API* request itself.
/// If set to `true`, Hyperswitch attempts to confirm and authorize the payment immediately after creation, provided sufficient payment method details are included. If `false` or omitted (default is `false`), the payment is created with a status such as `requires_payment_method` or `requires_confirmation`, and a separate `POST /payments/{payment_id}/confirm` call is necessary to proceed with authorization.
#[schema(default = false, example = true)]
pub confirm: Option<bool>,
@ -959,11 +957,11 @@ pub struct PaymentsRequest {
#[schema(example = true)]
pub off_session: Option<bool>,
/// A description for the payment
/// An arbitrary string attached to the payment. Often useful for displaying to users or for your own internal record-keeping.
#[schema(example = "It's my first payment request")]
pub description: Option<String>,
/// The URL to which you want the user to be redirected after the completion of the payment operation
/// The URL to redirect the customer to after they complete the payment process or authentication. This is crucial for flows that involve off-site redirection (e.g., 3DS, some bank redirects, wallet payments).
#[schema(value_type = Option<String>, example = "https://hyperswitch.io", max_length = 2048)]
pub return_url: Option<Url>,
@ -1136,9 +1134,7 @@ pub struct PaymentsRequest {
#[schema(value_type = Option<bool>, default = false)]
pub request_extended_authorization: Option<RequestExtendedAuthorizationBool>,
/// Merchant's identifier for the payment/invoice. This will be sent to the connector
/// if the connector provides support to accept multiple reference ids.
/// In case the connector supports only one reference id, Hyperswitch's Payment ID will be sent as reference.
/// Your unique identifier for this payment or order. This ID helps you reconcile payments on your system. If provided, it is passed to the connector if supported.
#[schema(
value_type = Option<String>,
max_length = 255,
@ -1472,7 +1468,7 @@ impl RequestSurchargeDetails {
#[cfg(feature = "v1")]
#[derive(Debug, serde::Serialize, Clone, PartialEq, ToSchema, router_derive::PolymorphicSchema)]
pub struct PaymentAttemptResponse {
/// Unique identifier for the attempt
/// A unique identifier for this specific payment attempt.
pub attempt_id: String,
/// The status of the attempt
#[schema(value_type = AttemptStatus, example = "charged")]
@ -1486,9 +1482,9 @@ pub struct PaymentAttemptResponse {
/// The currency of the amount of the payment attempt
#[schema(value_type = Option<Currency>, example = "USD")]
pub currency: Option<enums::Currency>,
/// The connector used for the payment
/// The name of the payment connector (e.g., 'stripe', 'adyen') used for this attempt.
pub connector: Option<String>,
/// If there was an error while calling the connector, the error message is received here
/// A human-readable message from the connector explaining the error, if one occurred during this payment attempt.
pub error_message: Option<String>,
/// The payment method that is to be used
#[schema(value_type = Option<PaymentMethod>, example = "bank_transfer")]
@ -1511,11 +1507,11 @@ pub struct PaymentAttemptResponse {
pub modified_at: PrimitiveDateTime,
/// If the payment was cancelled the reason will be provided here
pub cancellation_reason: Option<String>,
/// A unique identifier to link the payment to a mandate, can be use instead of payment_method_data
/// If this payment attempt is associated with a mandate (e.g., for a recurring or subsequent payment), this field will contain the ID of that mandate.
pub mandate_id: Option<String>,
/// If there was an error while calling the connectors the error code is received here
/// The error code returned by the connector if this payment attempt failed. This code is specific to the connector.
pub error_code: Option<String>,
/// Provide a reference to a stored payment method
/// If a tokenized (saved) payment method was used for this attempt, this field contains the payment token representing that payment method.
pub payment_token: Option<String>,
/// Additional data related to some connectors
pub connector_metadata: Option<serde_json::Value>,
@ -1525,7 +1521,7 @@ pub struct PaymentAttemptResponse {
/// Payment Method Type
#[schema(value_type = Option<PaymentMethodType>, example = "google_pay")]
pub payment_method_type: Option<enums::PaymentMethodType>,
/// Reference to the payment at connector side
/// The connector's own reference or transaction ID for this specific payment attempt. Useful for reconciliation with the connector.
#[schema(value_type = Option<String>, example = "993672945374576J")]
pub reference_id: Option<String>,
/// (This field is not live yet)Error code unified across the connectors is received here if there was an error while calling connector
@ -1647,7 +1643,7 @@ pub struct PaymentAttemptRevenueRecoveryData {
Default, Debug, serde::Serialize, Clone, PartialEq, ToSchema, router_derive::PolymorphicSchema,
)]
pub struct CaptureResponse {
/// Unique identifier for the capture
/// A unique identifier for this specific capture operation.
pub capture_id: String,
/// The status of the capture
#[schema(value_type = CaptureStatus, example = "charged")]
@ -1658,21 +1654,21 @@ pub struct CaptureResponse {
/// The currency of the amount of the capture
#[schema(value_type = Option<Currency>, example = "USD")]
pub currency: Option<enums::Currency>,
/// The connector used for the payment
/// The name of the payment connector that processed this capture.
pub connector: String,
/// Unique identifier for the parent attempt on which this capture is made
/// The ID of the payment attempt that was successfully authorized and subsequently captured by this operation.
pub authorized_attempt_id: String,
/// A unique identifier for this capture provided by the connector
pub connector_capture_id: Option<String>,
/// Sequence number of this capture, in the series of captures made for the parent attempt
pub capture_sequence: i16,
/// If there was an error while calling the connector the error message is received here
/// A human-readable message from the connector explaining why this capture operation failed, if applicable.
pub error_message: Option<String>,
/// If there was an error while calling the connectors the code is received here
/// The error code returned by the connector if this capture operation failed. This code is connector-specific.
pub error_code: Option<String>,
/// If there was an error while calling the connectors the reason is received here
/// A more detailed reason from the connector explaining the capture failure, if available.
pub error_reason: Option<String>,
/// Reference to the capture at connector side
/// The connector's own reference or transaction ID for this specific capture operation. Useful for reconciliation.
pub reference_id: Option<String>,
}
@ -4314,23 +4310,23 @@ impl Address {
#[derive(Clone, Default, Debug, Eq, serde::Deserialize, serde::Serialize, PartialEq, ToSchema)]
#[serde(deny_unknown_fields)]
pub struct AddressDetails {
/// The address city
/// The city, district, suburb, town, or village of the address.
#[schema(max_length = 50, example = "New York")]
pub city: Option<String>,
/// The two-letter ISO country code for the address
/// The two-letter ISO 3166-1 alpha-2 country code (e.g., US, GB).
#[schema(value_type = Option<CountryAlpha2>, example = "US")]
pub country: Option<api_enums::CountryAlpha2>,
/// The first line of the address
/// The first line of the street address or P.O. Box.
#[schema(value_type = Option<String>, max_length = 200, example = "123, King Street")]
pub line1: Option<Secret<String>>,
/// The second line of the address
/// The second line of the street address or P.O. Box (e.g., apartment, suite, unit, or building).
#[schema(value_type = Option<String>, max_length = 50, example = "Powelson Avenue")]
pub line2: Option<Secret<String>>,
/// The third line of the address
/// The third line of the street address, if applicable.
#[schema(value_type = Option<String>, max_length = 50, example = "Bridgewater")]
pub line3: Option<Secret<String>>,
@ -4424,22 +4420,22 @@ pub struct PhoneDetails {
#[cfg(feature = "v1")]
#[derive(Debug, Clone, Default, Eq, PartialEq, serde::Deserialize, serde::Serialize, ToSchema)]
pub struct PaymentsCaptureRequest {
/// The unique identifier for the payment
/// The unique identifier for the payment being captured. This is taken from the path parameter.
#[serde(skip_deserializing)]
pub payment_id: id_type::PaymentId,
/// The unique identifier for the merchant
/// The unique identifier for the merchant. This is usually inferred from the API key.
#[schema(value_type = Option<String>)]
pub merchant_id: Option<id_type::MerchantId>,
/// The Amount to be captured/ debited from the user's payment method. If not passed the full amount will be captured.
#[schema(value_type = i64, example = 6540)]
/// The amount to capture, in the lowest denomination of the currency. If omitted, the entire `amount_capturable` of the payment will be captured. Must be less than or equal to the current `amount_capturable`.
#[schema(value_type = Option<i64>, example = 6540)]
pub amount_to_capture: Option<MinorUnit>,
/// Decider to refund the uncaptured amount
/// Decider to refund the uncaptured amount. (Currently not fully supported or behavior may vary by connector).
pub refund_uncaptured_amount: Option<bool>,
/// Provides information about a card payment that customers see on their statements.
/// A dynamic suffix that appears on your customer's credit card statement. This is concatenated with the (shortened) descriptor prefix set on your account to form the complete statement descriptor. The combined length should not exceed connector-specific limits (typically 22 characters).
pub statement_descriptor_suffix: Option<String>,
/// Concatenated with the statement descriptor suffix that’s set on the account to form the complete statement descriptor.
/// An optional prefix for the statement descriptor that appears on your customer's credit card statement. This can override the default prefix set on your merchant account. The combined length of prefix and suffix should not exceed connector-specific limits (typically 22 characters).
pub statement_descriptor_prefix: Option<String>,
/// Merchant connector details used to make payments.
/// Merchant connector details used to make payments. (Deprecated)
#[schema(value_type = Option<MerchantConnectorDetailsWrap>, deprecated)]
pub merchant_connector_details: Option<admin::MerchantConnectorDetailsWrap>,
}
@ -4824,28 +4820,28 @@ pub struct PaymentsResponse {
#[schema(value_type = Option<i64>, example = 6540)]
pub shipping_cost: Option<MinorUnit>,
/// The maximum amount that could be captured from the payment
/// The amount (in minor units) that can still be captured for this payment. This is relevant when `capture_method` is `manual`. Once fully captured, or if `capture_method` is `automatic` and payment succeeded, this will be 0.
#[schema(value_type = i64, minimum = 100, example = 6540)]
pub amount_capturable: MinorUnit,
/// The amount which is already captured from the payment, this helps in the cases where merchants can't capture all capturable amount at once.
/// The total amount (in minor units) that has been captured for this payment. For `fauxpay` sandbox connector, this might reflect the authorized amount if `status` is `succeeded` even if `capture_method` was `manual`.
#[schema(value_type = Option<i64>, example = 6540)]
pub amount_received: Option<MinorUnit>,
/// The connector used for the payment
/// The name of the payment connector (e.g., 'stripe', 'adyen') that processed or is processing this payment.
#[schema(example = "stripe")]
pub connector: Option<String>,
/// It's a token used for client side verification.
/// A secret token unique to this payment intent. It is primarily used by client-side applications (e.g., Hyperswitch SDKs) to authenticate actions like confirming the payment or handling next actions. This secret should be handled carefully and not exposed publicly beyond its intended client-side use.
#[schema(value_type = Option<String>, example = "pay_U42c409qyHwOkWo3vK60_secret_el9ksDkiB8hi6j9N78yo")]
pub client_secret: Option<Secret<String>>,
/// Time when the payment was created
/// Timestamp indicating when this payment intent was created, in ISO 8601 format.
#[schema(example = "2022-09-10T10:11:12Z")]
#[serde(with = "common_utils::custom_serde::iso8601::option")]
pub created: Option<PrimitiveDateTime>,
/// The currency of the amount of the payment
/// Three-letter ISO currency code (e.g., USD, EUR) for the payment amount.
#[schema(value_type = Currency, example = "USD")]
pub currency: String,
@ -4862,11 +4858,11 @@ pub struct PaymentsResponse {
pub customer: Option<CustomerDetailsResponse>,
/// A description of the payment
/// An arbitrary string providing a description for the payment, often useful for display or internal record-keeping.
#[schema(example = "It's my first payment request")]
pub description: Option<String>,
/// List of refunds that happened on this intent, as same payment intent can have multiple refund requests depending on the nature of order
/// An array of refund objects associated with this payment. Empty or null if no refunds have been processed.
#[schema(value_type = Option<Vec<RefundResponse>>)]
pub refunds: Option<Vec<refunds::RefundResponse>>,
@ -4968,17 +4964,17 @@ pub struct PaymentsResponse {
#[schema(max_length = 255, example = "Payment for shoes purchase")]
pub statement_descriptor_suffix: Option<String>,
/// Additional information required for redirection
/// If the payment requires further action from the customer (e.g., 3DS authentication, redirect to a bank page), this object will contain the necessary information for the client to proceed. Null if no further action is needed from the customer at this stage.
pub next_action: Option<NextActionData>,
/// If the payment was cancelled the reason will be provided here
/// If the payment intent was cancelled, this field provides a textual reason for the cancellation (e.g., "requested_by_customer", "abandoned").
pub cancellation_reason: Option<String>,
/// If there was an error while calling the connectors the code is received here
/// The connector-specific error code from the last failed payment attempt associated with this payment intent.
#[schema(example = "E0001")]
pub error_code: Option<String>,
/// If there was an error while calling the connector the error message is received here
/// A human-readable error message from the last failed payment attempt associated with this payment intent.
#[schema(example = "Failed while verifying the card")]
pub error_message: Option<String>,
@ -4990,26 +4986,26 @@ pub struct PaymentsResponse {
#[remove_in(PaymentsCreateResponseOpenApi)]
pub unified_message: Option<String>,
/// Payment Experience for the current payment
/// Describes the type of payment flow experienced by the customer (e.g., 'redirect_to_url', 'invoke_sdk', 'display_qr_code').
#[schema(value_type = Option<PaymentExperience>, example = "redirect_to_url")]
pub payment_experience: Option<api_enums::PaymentExperience>,
/// Can be used to specify the Payment Method Type
/// The specific payment method subtype used for this payment (e.g., 'credit_card', 'klarna', 'gpay'). This provides more granularity than the 'payment_method' field.
#[schema(value_type = Option<PaymentMethodType>, example = "gpay")]
pub payment_method_type: Option<api_enums::PaymentMethodType>,
/// The connector used for this payment along with the country and business details
/// A label identifying the specific merchant connector account (MCA) used for this payment. This often combines the connector name, business country, and a custom label (e.g., "stripe_US_primary").
#[schema(example = "stripe_US_food")]
pub connector_label: Option<String>,
/// The business country of merchant for this payment
/// The two-letter ISO country code (e.g., US, GB) of the business unit or profile under which this payment was processed.
#[schema(value_type = Option<CountryAlpha2>, example = "US")]
pub business_country: Option<api_enums::CountryAlpha2>,
/// The business label of merchant for this payment
/// The label identifying the specific business unit or profile under which this payment was processed by the merchant.
pub business_label: Option<String>,
/// The business_sub_label for this payment
/// An optional sub-label for further categorization of the business unit or profile used for this payment.
pub business_sub_label: Option<String>,
/// Allowed Payment Method Types for a given PaymentIntent
@ -5092,7 +5088,7 @@ pub struct PaymentsResponse {
/// The browser information used for this payment
pub browser_info: Option<serde_json::Value>,
/// Identifier for Payment Method used for the payment
/// A unique identifier for the payment method used in this payment. If the payment method was saved or tokenized, this ID can be used to reference it for future transactions or recurring payments.
pub payment_method_id: Option<String>,
/// Payment Method Status, refers to the status of the payment method used for this payment.
@ -5330,7 +5326,6 @@ pub struct PaymentsConfirmIntentRequest {
#[schema(value_type = Option<String>)]
pub payment_method_id: Option<id_type::GlobalPaymentMethodId>,
/// Provide a reference to a stored payment method
#[schema(example = "187282ab-40ef-47a9-9206-5099ba31e432")]
pub payment_token: Option<String>,
}
@ -6414,9 +6409,9 @@ pub struct PaymentsRetrieveRequest {
pub merchant_id: Option<id_type::MerchantId>,
/// Decider to enable or disable the connector call for retrieve request
pub force_sync: bool,
/// The parameters passed to a retrieve request
/// Optional query parameters that might be specific to a connector or flow, passed through during the retrieve operation. Use with caution and refer to specific connector documentation if applicable.
pub param: Option<String>,
/// The name of the connector
/// Optionally specifies the connector to be used for a 'force_sync' retrieve operation. If provided, Hyperswitch will attempt to sync the payment status from this specific connector.
pub connector: Option<String>,
/// Merchant connector details used to make payments.
#[schema(value_type = Option<MerchantConnectorDetailsWrap>)]
@ -7563,6 +7558,7 @@ pub struct PaymentsManualUpdateResponse {
}
#[derive(Debug, serde::Serialize, serde::Deserialize, Clone, ToSchema)]
/// Indicates if 3DS method data was successfully completed or not
pub enum ThreeDsCompletionIndicator {
/// 3DS method successfully completed
#[serde(rename = "Y")]

33
crates/common_enums/src/enums.rs
View File

@ -241,7 +241,12 @@ pub enum RevenueRecoveryAlgorithmType {
Cascading,
}
/// Pass this parameter to force 3DS or non 3DS auth for this payment. Some connectors will still force 3DS auth even in case of passing 'no_three_ds' here and vice versa. Default value is 'no_three_ds' if not set
/// Specifies the type of cardholder authentication to be applied for a payment.
///
/// - `ThreeDs`: Requests 3D Secure (3DS) authentication. If the card is enrolled, 3DS authentication will be activated, potentially shifting chargeback liability to the issuer.
/// - `NoThreeDs`: Indicates that 3D Secure authentication should not be performed. The liability for chargebacks typically remains with the merchant. This is often the default if not specified.
///
/// Note: The actual authentication behavior can also be influenced by merchant configuration and specific connector defaults. Some connectors might still enforce 3DS or bypass it regardless of this parameter.
#[derive(
Clone,
Copy,
@ -395,7 +400,9 @@ pub enum BlocklistDataKind {
ExtendedCardBin,
}
/// Default value if not passed is set to 'automatic' which results in Auth and Capture in one single API request. Pass 'manual' or 'manual_multiple' in case you want do a separate Auth and Capture by first authorizing and placing a hold on your customer's funds so that you can use the Payments/Capture endpoint later to capture the authorized amount. Pass 'manual' if you want to only capture the amount later once or 'manual_multiple' if you want to capture the funds multiple times later. Both 'manual' and 'manual_multiple' are only supported by a specific list of processors
/// Specifies how the payment is captured.
/// - `automatic`: Funds are captured immediately after successful authorization. This is the default behavior if the field is omitted.
/// - `manual`: Funds are authorized but not captured. A separate request to the `/payments/{payment_id}/capture` endpoint is required to capture the funds.
#[derive(
Clone,
Copy,
@ -416,16 +423,16 @@ pub enum BlocklistDataKind {
#[serde(rename_all = "snake_case")]
#[strum(serialize_all = "snake_case")]
pub enum CaptureMethod {
/// Post the payment authorization, the capture will be executed on the full amount immediately
/// Post the payment authorization, the capture will be executed on the full amount immediately.
#[default]
Automatic,
/// The capture will happen only if the merchant triggers a Capture API request
/// The capture will happen only if the merchant triggers a Capture API request. Allows for a single capture of the authorized amount.
Manual,
/// The capture will happen only if the merchant triggers a Capture API request
/// The capture will happen only if the merchant triggers a Capture API request. Allows for multiple partial captures up to the authorized amount.
ManualMultiple,
/// The capture can be scheduled to automatically get triggered at a specific date & time
/// The capture can be scheduled to automatically get triggered at a specific date & time.
Scheduled,
/// Handles separate auth and capture sequentially; same as `Automatic` for most connectors.
/// Handles separate auth and capture sequentially; effectively the same as `Automatic` for most connectors.
SequentialAutomatic,
}
@ -494,7 +501,7 @@ pub enum CallConnectorAction {
HandleResponse(Vec<u8>),
}
/// The three letter ISO currency code in uppercase. Eg: 'USD' for the United States Dollar.
/// The three-letter ISO 4217 currency code (e.g., "USD", "EUR") for the payment amount. This field is mandatory for creating a payment.
#[allow(clippy::upper_case_acronyms)]
#[derive(
Clone,
@ -1555,7 +1562,8 @@ pub enum MerchantStorageScheme {
RedisKv,
}
/// The status of the current payment that was made
/// Represents the overall status of a payment intent.
/// The status transitions through various states depending on the payment method, confirmation, capture method, and any subsequent actions (like customer authentication or manual capture).
#[derive(
Clone,
Copy,
@ -1642,9 +1650,10 @@ impl IntentStatus {
}
}
/// Indicates that you intend to make future payments with the payment methods used for this Payment. 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.
/// - On_session - Payment method saved only at hyperswitch when consent is provided by the user. CVV will asked during the returning user payment
/// - Off_session - Payment method saved at both hyperswitch and Processor when consent is provided by the user. No input is required during the returning user payment.
/// Specifies how the payment method can be used for future payments.
/// - `off_session`: The payment method can be used for future payments when the customer is not present.
/// - `on_session`: The payment method is intended for use only when the customer is present during checkout.
/// If omitted, defaults to `on_session`.
#[derive(
Clone,
Copy,

276
crates/openapi/src/routes/payments.rs
View File

@ -1,24 +1,8 @@
/// Payments - Create
///
/// **Creates a payment object when amount and currency are passed.**
/// Creates a payment resource, which represents a customer's intent to pay.
/// This endpoint is the starting point for various payment flows:
///
/// This API is also used to create a mandate by passing the `mandate_object`.
///
/// Depending on the user journey you wish to achieve, you may opt to complete all the steps in a single request **by attaching a payment method, setting `confirm=true` and `capture_method = automatic`** in the *Payments/Create API* request.
///
/// Otherwise, To completely process a payment you will have to **create a payment, attach a payment method, confirm and capture funds**. For that you could use the following sequence of API requests -
///
/// 1. Payments - Create
///
/// 2. Payments - Update
///
/// 3. Payments - Confirm
///
/// 4. Payments - Capture.
///
/// You will require the 'API - Key' from the Hyperswitch dashboard to make the first call, and use the 'client secret' returned in this API along with your 'publishable key' to make subsequent API calls from your client.
///
/// This page lists the various combinations in which the Payments - Create API can be used and the details about the various fields in the requests and responses.
#[utoipa::path(
post,
path = "/payments",
@ -26,12 +10,12 @@
content = PaymentsCreateRequest,
examples(
(
"Create a payment with minimal fields" = (
"1. Create a payment with minimal fields" = (
value = json!({"amount": 6540,"currency": "USD"})
)
),
(
"Create a payment with customer details and metadata" = (
"2. Create a payment with customer details and metadata" = (
value = json!({
"amount": 6540,
"currency": "USD",
@ -53,7 +37,7 @@
)
),
(
"Create a 3DS payment" = (
"3. Create a 3DS payment" = (
value = json!({
"amount": 6540,
"currency": "USD",
@ -62,7 +46,7 @@
)
),
(
"Create a manual capture payment" = (
"4. Create a manual capture payment (basic)" = (
value = json!({
"amount": 6540,
"currency": "USD",
@ -71,7 +55,7 @@
)
),
(
"Create a setup mandate payment" = (
"5. Create a setup mandate payment" = (
value = json!({
"amount": 6540,
"currency": "USD",
@ -117,7 +101,7 @@
)
),
(
"Create a recurring payment with mandate_id" = (
"6. Create a recurring payment with mandate_id" = (
value = json!({
"amount": 6540,
"currency": "USD",
@ -130,7 +114,7 @@
)
),
(
"Create a payment and save the card" = (
"7. Create a payment and save the card" = (
value = json!({
"amount": 6540,
"currency": "USD",
@ -160,7 +144,7 @@
)
),
(
"Create a payment using an already saved card's token" = (
"8. Create a payment using an already saved card's token" = (
value = json!({
"amount": 6540,
"currency": "USD",
@ -173,7 +157,7 @@
)
),
(
"Create a manual capture payment" = (
"9. Create a payment with billing details" = (
value = json!({
"amount": 6540,
"currency": "USD",
@ -203,7 +187,222 @@
),
),
responses(
(status = 200, description = "Payment created", body = PaymentsCreateResponseOpenApi),
(status = 200, description = "Payment created", body = PaymentsCreateResponseOpenApi,
examples(
("1. Response for minimal payment creation (requires payment method)" = (
value = json!({
"payment_id": "pay_syxxxxxxxxxxxx",
"merchant_id": "merchant_myyyyyyyyyyyy",
"status": "requires_payment_method",
"amount": 6540,
"currency": "USD",
"client_secret": "pay_syxxxxxxxxxxxx_secret_szzzzzzzzzzz",
"created": "2023-10-26T10:00:00Z",
"amount_capturable": 6540,
"profile_id": "pro_pzzzzzzzzzzz",
"attempt_count": 1,
"expires_on": "2023-10-26T10:15:00Z"
})
)),
("2. Response for payment with customer details (requires payment method)" = (
value = json!({
"payment_id": "pay_custmeta_xxxxxxxxxxxx",
"merchant_id": "merchant_myyyyyyyyyyyy",
"status": "requires_payment_method",
"amount": 6540,
"currency": "USD",
"customer_id": "cus_abcdefgh",
"customer": {
"id": "cus_abcdefgh",
"name": "John Dough",
"email": "john@example.com",
"phone": "9123456789"
},
"description": "Its my first payment request",
"statement_descriptor_name": "joseph",
"statement_descriptor_suffix": "JS",
"metadata": {
"udf1": "some-value",
"udf2": "some-value"
},
"client_secret": "pay_custmeta_xxxxxxxxxxxx_secret_szzzzzzzzzzz",
"created": "2023-10-26T10:05:00Z",
"ephemeral_key": {
"customer_id": "cus_abcdefgh",
"secret": "epk_ephemeralxxxxxxxxxxxx"
},
"profile_id": "pro_pzzzzzzzzzzz",
"attempt_count": 1,
"expires_on": "2023-10-26T10:20:00Z"
})
)),
("3. Response for 3DS payment creation (requires payment method)" = (
value = json!({
"payment_id": "pay_3ds_xxxxxxxxxxxx",
"merchant_id": "merchant_myyyyyyyyyyyy",
"status": "requires_payment_method",
"amount": 6540,
"currency": "USD",
"authentication_type": "three_ds",
"client_secret": "pay_3ds_xxxxxxxxxxxx_secret_szzzzzzzzzzz",
"created": "2023-10-26T10:10:00Z",
"profile_id": "pro_pzzzzzzzzzzz",
"attempt_count": 1,
"expires_on": "2023-10-26T10:25:00Z"
})
)),
("4. Response for basic manual capture payment (requires payment method)" = (
value = json!({
"payment_id": "pay_manualcap_xxxxxxxxxxxx",
"merchant_id": "merchant_myyyyyyyyyyyy",
"status": "requires_payment_method",
"amount": 6540,
"currency": "USD",
"capture_method": "manual",
"client_secret": "pay_manualcap_xxxxxxxxxxxx_secret_szzzzzzzzzzz",
"created": "2023-10-26T10:15:00Z",
"profile_id": "pro_pzzzzzzzzzzz",
"attempt_count": 1,
"expires_on": "2023-10-26T10:30:00Z"
})
)),
("5. Response for successful setup mandate payment" = (
value = json!({
"payment_id": "pay_mandatesetup_xxxxxxxxxxxx",
"merchant_id": "merchant_myyyyyyyyyyyy",
"status": "succeeded",
"amount": 6540,
"currency": "USD",
"amount_capturable": 0,
"amount_received": 6540,
"connector": "fauxpay",
"customer_id": "StripeCustomer123",
"mandate_id": "man_xxxxxxxxxxxx",
"mandate_data": {
"customer_acceptance": {
"acceptance_type": "online",
"accepted_at": "1963-05-03T04:07:52.723Z",
"online": { "ip_address": "127.0.0.1", "user_agent": "amet irure esse" }
},
"mandate_type": { "single_use": { "amount": 6540, "currency": "USD" } }
},
"setup_future_usage": "on_session",
"payment_method": "card",
"payment_method_data": {
"card": { "last4": "4242", "card_exp_month": "10", "card_exp_year": "25", "card_holder_name": "joseph Doe" }
},
"authentication_type": "no_three_ds",
"client_secret": "pay_mandatesetup_xxxxxxxxxxxx_secret_szzzzzzzzzzz",
"created": "2023-10-26T10:20:00Z",
"ephemeral_key": { "customer_id": "StripeCustomer123", "secret": "epk_ephemeralxxxxxxxxxxxx" },
"profile_id": "pro_pzzzzzzzzzzz",
"attempt_count": 1,
"merchant_connector_id": "mca_mcaconnectorxxxx",
"connector_transaction_id": "txn_connectortransidxxxx"
})
)),
("6. Response for successful recurring payment with mandate_id" = (
value = json!({
"payment_id": "pay_recurring_xxxxxxxxxxxx",
"merchant_id": "merchant_myyyyyyyyyyyy",
"status": "succeeded",
"amount": 6540,
"currency": "USD",
"amount_capturable": 0,
"amount_received": 6540,
"connector": "fauxpay",
"customer_id": "StripeCustomer",
"mandate_id": "{{mandate_id}}",
"off_session": true,
"payment_method": "card",
"authentication_type": "no_three_ds",
"client_secret": "pay_recurring_xxxxxxxxxxxx_secret_szzzzzzzzzzz",
"created": "2023-10-26T10:22:00Z",
"profile_id": "pro_pzzzzzzzzzzz",
"attempt_count": 1,
"merchant_connector_id": "mca_mcaconnectorxxxx",
"connector_transaction_id": "txn_connectortransidxxxx"
})
)),
("7. Response for successful payment with card saved" = (
value = json!({
"payment_id": "pay_savecard_xxxxxxxxxxxx",
"merchant_id": "merchant_myyyyyyyyyyyy",
"status": "succeeded",
"amount": 6540,
"currency": "USD",
"amount_capturable": 0,
"amount_received": 6540,
"connector": "fauxpay",
"customer_id": "StripeCustomer123",
"setup_future_usage": "on_session",
"payment_method": "card",
"payment_method_data": {
"card": { "last4": "4242", "card_exp_month": "10", "card_exp_year": "25", "card_holder_name": "joseph Doe" }
},
"authentication_type": "no_three_ds",
"client_secret": "pay_savecard_xxxxxxxxxxxx_secret_szzzzzzzzzzz",
"created": "2023-10-26T10:25:00Z",
"ephemeral_key": { "customer_id": "StripeCustomer123", "secret": "epk_ephemeralxxxxxxxxxxxx" },
"profile_id": "pro_pzzzzzzzzzzz",
"attempt_count": 1,
"merchant_connector_id": "mca_mcaconnectorxxxx",
"connector_transaction_id": "txn_connectortransidxxxx",
"payment_token": null // Assuming payment_token is for subsequent use, not in this response.
})
)),
("8. Response for successful payment using saved card token" = (
value = json!({
"payment_id": "pay_token_xxxxxxxxxxxx",
"merchant_id": "merchant_myyyyyyyyyyyy",
"status": "succeeded",
"amount": 6540,
"currency": "USD",
"amount_capturable": 0,
"amount_received": 6540,
"connector": "fauxpay",
"payment_method": "card",
"payment_token": "{{payment_token}}",
"client_secret": "pay_token_xxxxxxxxxxxx_secret_szzzzzzzzzzz",
"created": "2023-10-26T10:27:00Z",
"profile_id": "pro_pzzzzzzzzzzz",
"attempt_count": 1,
"merchant_connector_id": "mca_mcaconnectorxxxx",
"connector_transaction_id": "txn_connectortransidxxxx"
})
)),
("9. Response for payment with billing details (requires payment method)" = (
value = json!({
"payment_id": "pay_manualbill_xxxxxxxxxxxx",
"merchant_id": "merchant_myyyyyyyyyyyy",
"status": "requires_payment_method",
"amount": 6540,
"currency": "USD",
"customer_id": "cus_abcdefgh",
"customer": {
"id": "cus_abcdefgh",
"name": "John Dough",
"email": "john@example.com",
"phone": "9123456789"
},
"billing": {
"address": {
"line1": "1467", "line2": "Harrison Street", "city": "San Fransico",
"state": "California", "zip": "94122", "country": "US",
"first_name": "joseph", "last_name": "Doe"
},
"phone": { "number": "9123456789", "country_code": "+91" }
},
"client_secret": "pay_manualbill_xxxxxxxxxxxx_secret_szzzzzzzzzzz",
"created": "2023-10-26T10:30:00Z",
"ephemeral_key": { "customer_id": "cus_abcdefgh", "secret": "epk_ephemeralxxxxxxxxxxxx" },
"profile_id": "pro_pzzzzzzzzzzz",
"attempt_count": 1,
"expires_on": "2023-10-26T10:45:00Z"
})
))
)
),
(status = 400, description = "Missing Mandatory fields")
),
tag = "Payments",
@ -294,15 +493,12 @@ pub fn payments_update() {}
/// Payments - Confirm
///
/// **Use this API to confirm the payment and forward the payment to the payment processor.**
/// Confirms a payment intent that was previously created with `confirm: false`. This action attempts to authorize the payment with the payment processor.
///
/// Alternatively you can confirm the payment within the *Payments/Create* API by setting `confirm=true`. After confirmation, the payment could either:
///
/// 1. fail with `failed` status or
///
/// 2. transition to a `requires_customer_action` status with a `next_action` block or
///
/// 3. succeed with either `succeeded` in case of automatic capture or `requires_capture` in case of manual capture
/// Expected status transitions after confirmation:
/// - `succeeded`: If authorization is successful and `capture_method` is `automatic`.
/// - `requires_capture`: If authorization is successful and `capture_method` is `manual`.
/// - `failed`: If authorization fails.
#[utoipa::path(
post,
path = "/payments/{payment_id}/confirm",
@ -352,7 +548,13 @@ pub fn payments_confirm() {}
/// Payments - Capture
///
/// To capture the funds for an uncaptured payment
/// Captures the funds for a previously authorized payment intent where `capture_method` was set to `manual` and the payment is in a `requires_capture` state.
///
/// Upon successful capture, the payment status usually transitions to `succeeded`.
/// The `amount_to_capture` can be specified in the request body; it must be less than or equal to the payment's `amount_capturable`. If omitted, the full capturable amount is captured.
///
/// A payment must be in a capturable state (e.g., `requires_capture`). Attempting to capture an already `succeeded` (and fully captured) payment or one in an invalid state will lead to an error.
///
#[utoipa::path(
post,
path = "/payments/{payment_id}/capture",