Payments
Payments - Retrieve
Get Started
Essentials
API Reference
- Payments
- Getting Started with Payments
- POSTPayments - Create
- POSTPayments - Update
- POSTPayments - Confirm
- GETPayments - Retrieve
- POSTPayments - Cancel
- POSTPayments - Capture
- POSTPayments - Incremental Authorization
- POSTPayments - Session token
- GETPayments Link - Retrieve
- GETPayments - List
- POSTPayments - External 3DS Authentication
- POSTPayments - Complete Authorize
- POSTPayments - Update Metadata
- Payment Methods
- Customers
- Mandates
- Refunds
- Disputes
- Payouts
- Event
- Poll
- Blocklist
- Routing
- Relay
- Schemas
Admin API based
- Organization
- Merchant Account
- Business Profile
- API Key
- Merchant Connector Account
- GSM (Global Status Mapping)
- Event
Payments
Payments - Retrieve
Retrieves a Payment. This API can also be used to get the status of a previously initiated payment or next action for an ongoing payment
GET
/
payments
/
{payment_id}
curl --request GET \
--url https://sandbox.hyperswitch.io/payments/{payment_id} \
--header 'Content-Type: application/json' \
--header 'api-key: <api-key>' \
--data '{
"merchant_id": "<string>",
"force_sync": true,
"client_secret": "<string>",
"expand_captures": true,
"expand_attempts": true
}'
{
"payment_id": "pay_mbabizu24mvu3mela5njyhpit4",
"merchant_id": "merchant_1668273825",
"status": "succeeded",
"amount": 6540,
"net_amount": 6540,
"shipping_cost": 6540,
"amount_capturable": 6540,
"amount_received": 6540,
"connector": "stripe",
"client_secret": "pay_U42c409qyHwOkWo3vK60_secret_el9ksDkiB8hi6j9N78yo",
"created": "2022-09-10T10:11:12Z",
"currency": "AED",
"customer_id": "cus_y3oqhf46pyzuxjbcn2giaqnb44",
"customer": {
"id": "cus_y3oqhf46pyzuxjbcn2giaqnb44",
"name": "John Doe",
"email": "johntest@test.com",
"phone": "9123456789",
"phone_country_code": "+1"
},
"description": "It's my first payment request",
"refunds": [
{
"refund_id": "<string>",
"payment_id": "<string>",
"amount": 6540,
"currency": "<string>",
"status": "succeeded",
"reason": "<string>",
"metadata": {},
"error_message": "<string>",
"error_code": "<string>",
"unified_code": "<string>",
"unified_message": "<string>",
"created_at": "2023-11-07T05:31:56Z",
"updated_at": "2023-11-07T05:31:56Z",
"connector": "stripe",
"profile_id": "<string>",
"merchant_connector_id": "<string>",
"split_refunds": {
"stripe_split_refund": {
"revert_platform_fee": true,
"revert_transfer": true
}
},
"issuer_error_code": "<string>",
"issuer_error_message": "<string>"
}
],
"disputes": [
{
"dispute_id": "<string>",
"dispute_stage": "pre_dispute",
"dispute_status": "dispute_opened",
"connector_status": "<string>",
"connector_dispute_id": "<string>",
"connector_reason": "<string>",
"connector_reason_code": "<string>",
"challenge_required_by": "2023-11-07T05:31:56Z",
"connector_created_at": "2023-11-07T05:31:56Z",
"connector_updated_at": "2023-11-07T05:31:56Z",
"created_at": "2023-11-07T05:31:56Z"
}
],
"attempts": [
{
"attempt_id": "<string>",
"status": "started",
"amount": 6540,
"order_tax_amount": 6540,
"currency": "AED",
"connector": "<string>",
"error_message": "<string>",
"payment_method": "card",
"connector_transaction_id": "<string>",
"capture_method": "automatic",
"authentication_type": "three_ds",
"created_at": "2022-09-10T10:11:12Z",
"modified_at": "2022-09-10T10:11:12Z",
"cancellation_reason": "<string>",
"mandate_id": "<string>",
"error_code": "<string>",
"payment_token": "<string>",
"connector_metadata": "<any>",
"payment_experience": "redirect_to_url",
"payment_method_type": "ach",
"reference_id": "993672945374576J",
"unified_code": "<string>",
"unified_message": "<string>",
"client_source": "<string>",
"client_version": "<string>"
}
],
"captures": [
{
"capture_id": "<string>",
"status": "started",
"amount": 6540,
"currency": "AED",
"connector": "<string>",
"authorized_attempt_id": "<string>",
"connector_capture_id": "<string>",
"capture_sequence": 123,
"error_message": "<string>",
"error_code": "<string>",
"error_reason": "<string>",
"reference_id": "<string>"
}
],
"mandate_id": "mandate_iwer89rnjef349dni3",
"mandate_data": {
"update_mandate_id": "<string>",
"customer_acceptance": {
"acceptance_type": "online",
"accepted_at": "2022-09-10T10:11:12Z",
"online": {
"ip_address": "123.32.25.123",
"user_agent": "<string>"
}
},
"mandate_type": {
"single_use": {
"amount": 6540,
"currency": "AED",
"start_date": "2022-09-10T00:00:00Z",
"end_date": "2023-09-10T23:59:59Z",
"metadata": {}
}
}
},
"setup_future_usage": "off_session",
"off_session": true,
"capture_on": "2022-09-10T10:11:12Z",
"capture_method": "automatic",
"payment_method": "card",
"payment_method_data": {
"card": {
"last4": "<string>",
"card_type": "<string>",
"card_network": "Visa",
"card_issuer": "<string>",
"card_issuing_country": "<string>",
"card_isin": "<string>",
"card_extended_bin": "<string>",
"card_exp_month": "<string>",
"card_exp_year": "<string>",
"card_holder_name": "<string>",
"payment_checks": "<any>",
"authentication_data": "<any>"
},
"billing": {
"address": {
"city": "New York",
"country": "AF",
"line1": "123, King Street",
"line2": "Powelson Avenue",
"line3": "Bridgewater",
"zip": "08807",
"state": "New York",
"first_name": "John",
"last_name": "Doe"
},
"phone": {
"number": "9123456789",
"country_code": "+1"
},
"email": "<string>"
}
},
"payment_token": "187282ab-40ef-47a9-9206-5099ba31e432",
"shipping": {
"address": {
"city": "New York",
"country": "AF",
"line1": "123, King Street",
"line2": "Powelson Avenue",
"line3": "Bridgewater",
"zip": "08807",
"state": "New York",
"first_name": "John",
"last_name": "Doe"
},
"phone": {
"number": "9123456789",
"country_code": "+1"
},
"email": "<string>"
},
"billing": {
"address": {
"city": "New York",
"country": "AF",
"line1": "123, King Street",
"line2": "Powelson Avenue",
"line3": "Bridgewater",
"zip": "08807",
"state": "New York",
"first_name": "John",
"last_name": "Doe"
},
"phone": {
"number": "9123456789",
"country_code": "+1"
},
"email": "<string>"
},
"order_details": "[{\n \"product_name\": \"gillete creme\",\n \"quantity\": 15,\n \"amount\" : 900\n }]",
"email": "johntest@test.com",
"name": "John Test",
"phone": "9123456789",
"return_url": "https://hyperswitch.io",
"authentication_type": "three_ds",
"statement_descriptor_name": "Hyperswitch Router",
"statement_descriptor_suffix": "Payment for shoes purchase",
"next_action": {
"redirect_to_url": "<string>",
"type": "redirect_to_url"
},
"cancellation_reason": "<string>",
"error_code": "E0001",
"error_message": "Failed while verifying the card",
"unified_code": "<string>",
"unified_message": "<string>",
"payment_experience": "redirect_to_url",
"payment_method_type": "ach",
"connector_label": "stripe_US_food",
"business_country": "AF",
"business_label": "<string>",
"business_sub_label": "<string>",
"allowed_payment_method_types": [
"ach"
],
"ephemeral_key": {
"customer_id": "cus_y3oqhf46pyzuxjbcn2giaqnb44",
"created_at": 123,
"expires": 123,
"secret": "<string>"
},
"manual_retry_allowed": true,
"connector_transaction_id": "993672945374576J",
"frm_message": {
"frm_name": "<string>",
"frm_transaction_id": "<string>",
"frm_transaction_type": "<string>",
"frm_status": "<string>",
"frm_score": 123,
"frm_reason": "<any>",
"frm_error": "<string>"
},
"metadata": {},
"connector_metadata": {
"apple_pay": {
"session_token_data": {
"payment_processing_certificate": "<string>",
"payment_processing_certificate_key": "<string>",
"payment_processing_details_at": "Hyperswitch",
"certificate": "<string>",
"certificate_keys": "<string>",
"merchant_identifier": "<string>",
"display_name": "<string>",
"initiative": "web",
"initiative_context": "<string>",
"merchant_business_country": "AF"
}
},
"airwallex": {
"payload": "<string>"
},
"noon": {
"order_category": "<string>"
},
"braintree": {
"merchant_account_id": "<string>",
"merchant_config_currency": "<string>"
}
},
"feature_metadata": {
"redirect_response": {
"param": "<string>",
"json_payload": {}
},
"search_tags": [
"<string>"
],
"apple_pay_recurring_details": {
"payment_description": "<string>",
"regular_billing": {
"label": "<string>",
"recurring_payment_start_date": "2023-09-10T23:59:59Z",
"recurring_payment_end_date": "2023-09-10T23:59:59Z",
"recurring_payment_interval_unit": "year",
"recurring_payment_interval_count": 123
},
"billing_agreement": "<string>",
"management_url": "https://hyperswitch.io"
}
},
"reference_id": "993672945374576J",
"payment_link": {
"link": "<string>",
"secure_link": "<string>",
"payment_link_id": "<string>"
},
"profile_id": "<string>",
"surcharge_details": {
"surcharge_amount": 6540,
"tax_amount": 123
},
"attempt_count": 123,
"merchant_decision": "<string>",
"merchant_connector_id": "<string>",
"incremental_authorization_allowed": true,
"authorization_count": 123,
"incremental_authorizations": [
{
"authorization_id": "<string>",
"amount": 6540,
"status": "success",
"error_code": "<string>",
"error_message": "<string>",
"previously_authorized_amount": 123
}
],
"external_authentication_details": {
"authentication_flow": "challenge",
"electronic_commerce_indicator": "<string>",
"status": "started",
"ds_transaction_id": "<string>",
"version": "<string>",
"error_code": "<string>",
"error_message": "<string>"
},
"external_3ds_authentication_attempted": true,
"expires_on": "2022-09-10T10:11:12Z",
"fingerprint": "<string>",
"browser_info": {
"color_depth": 1,
"java_enabled": true,
"java_script_enabled": true,
"language": "<string>",
"screen_height": 1,
"screen_width": 1,
"time_zone": 123,
"ip_address": "<string>",
"accept_header": "text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,image/apng,*/*;q=0.8",
"user_agent": "<string>",
"os_type": "<string>",
"os_version": "<string>",
"device_model": "<string>"
},
"payment_method_id": "<string>",
"payment_method_status": "active",
"updated": "2022-09-10T10:11:12Z",
"split_payments": {
"stripe_split_payment": {
"charge_id": "<string>",
"charge_type": {
"Stripe": "direct"
},
"application_fees": 6540,
"transfer_account_id": "<string>"
}
},
"frm_metadata": {},
"extended_authorization_applied": true,
"capture_before": "2023-11-07T05:31:56Z",
"merchant_order_reference_id": "Custom_Order_id_123",
"order_tax_amount": 123,
"connector_mandate_id": "<string>",
"card_discovery": "manual",
"force_3ds_challenge": true,
"force_3ds_challenge_trigger": true,
"issuer_error_code": "<string>",
"issuer_error_message": "<string>"
}
Authorizations
Use the API key created under your merchant account from the HyperSwitch dashboard. API key is used to authenticate API requests from your merchant server only. Don't expose this key on a website or embed it in a mobile application.
Path Parameters
The identifier for payment
Body
application/json
Response
200
application/json
Gets the payment with final status
The response is of type object
.
curl --request GET \
--url https://sandbox.hyperswitch.io/payments/{payment_id} \
--header 'Content-Type: application/json' \
--header 'api-key: <api-key>' \
--data '{
"merchant_id": "<string>",
"force_sync": true,
"client_secret": "<string>",
"expand_captures": true,
"expand_attempts": true
}'
{
"payment_id": "pay_mbabizu24mvu3mela5njyhpit4",
"merchant_id": "merchant_1668273825",
"status": "succeeded",
"amount": 6540,
"net_amount": 6540,
"shipping_cost": 6540,
"amount_capturable": 6540,
"amount_received": 6540,
"connector": "stripe",
"client_secret": "pay_U42c409qyHwOkWo3vK60_secret_el9ksDkiB8hi6j9N78yo",
"created": "2022-09-10T10:11:12Z",
"currency": "AED",
"customer_id": "cus_y3oqhf46pyzuxjbcn2giaqnb44",
"customer": {
"id": "cus_y3oqhf46pyzuxjbcn2giaqnb44",
"name": "John Doe",
"email": "johntest@test.com",
"phone": "9123456789",
"phone_country_code": "+1"
},
"description": "It's my first payment request",
"refunds": [
{
"refund_id": "<string>",
"payment_id": "<string>",
"amount": 6540,
"currency": "<string>",
"status": "succeeded",
"reason": "<string>",
"metadata": {},
"error_message": "<string>",
"error_code": "<string>",
"unified_code": "<string>",
"unified_message": "<string>",
"created_at": "2023-11-07T05:31:56Z",
"updated_at": "2023-11-07T05:31:56Z",
"connector": "stripe",
"profile_id": "<string>",
"merchant_connector_id": "<string>",
"split_refunds": {
"stripe_split_refund": {
"revert_platform_fee": true,
"revert_transfer": true
}
},
"issuer_error_code": "<string>",
"issuer_error_message": "<string>"
}
],
"disputes": [
{
"dispute_id": "<string>",
"dispute_stage": "pre_dispute",
"dispute_status": "dispute_opened",
"connector_status": "<string>",
"connector_dispute_id": "<string>",
"connector_reason": "<string>",
"connector_reason_code": "<string>",
"challenge_required_by": "2023-11-07T05:31:56Z",
"connector_created_at": "2023-11-07T05:31:56Z",
"connector_updated_at": "2023-11-07T05:31:56Z",
"created_at": "2023-11-07T05:31:56Z"
}
],
"attempts": [
{
"attempt_id": "<string>",
"status": "started",
"amount": 6540,
"order_tax_amount": 6540,
"currency": "AED",
"connector": "<string>",
"error_message": "<string>",
"payment_method": "card",
"connector_transaction_id": "<string>",
"capture_method": "automatic",
"authentication_type": "three_ds",
"created_at": "2022-09-10T10:11:12Z",
"modified_at": "2022-09-10T10:11:12Z",
"cancellation_reason": "<string>",
"mandate_id": "<string>",
"error_code": "<string>",
"payment_token": "<string>",
"connector_metadata": "<any>",
"payment_experience": "redirect_to_url",
"payment_method_type": "ach",
"reference_id": "993672945374576J",
"unified_code": "<string>",
"unified_message": "<string>",
"client_source": "<string>",
"client_version": "<string>"
}
],
"captures": [
{
"capture_id": "<string>",
"status": "started",
"amount": 6540,
"currency": "AED",
"connector": "<string>",
"authorized_attempt_id": "<string>",
"connector_capture_id": "<string>",
"capture_sequence": 123,
"error_message": "<string>",
"error_code": "<string>",
"error_reason": "<string>",
"reference_id": "<string>"
}
],
"mandate_id": "mandate_iwer89rnjef349dni3",
"mandate_data": {
"update_mandate_id": "<string>",
"customer_acceptance": {
"acceptance_type": "online",
"accepted_at": "2022-09-10T10:11:12Z",
"online": {
"ip_address": "123.32.25.123",
"user_agent": "<string>"
}
},
"mandate_type": {
"single_use": {
"amount": 6540,
"currency": "AED",
"start_date": "2022-09-10T00:00:00Z",
"end_date": "2023-09-10T23:59:59Z",
"metadata": {}
}
}
},
"setup_future_usage": "off_session",
"off_session": true,
"capture_on": "2022-09-10T10:11:12Z",
"capture_method": "automatic",
"payment_method": "card",
"payment_method_data": {
"card": {
"last4": "<string>",
"card_type": "<string>",
"card_network": "Visa",
"card_issuer": "<string>",
"card_issuing_country": "<string>",
"card_isin": "<string>",
"card_extended_bin": "<string>",
"card_exp_month": "<string>",
"card_exp_year": "<string>",
"card_holder_name": "<string>",
"payment_checks": "<any>",
"authentication_data": "<any>"
},
"billing": {
"address": {
"city": "New York",
"country": "AF",
"line1": "123, King Street",
"line2": "Powelson Avenue",
"line3": "Bridgewater",
"zip": "08807",
"state": "New York",
"first_name": "John",
"last_name": "Doe"
},
"phone": {
"number": "9123456789",
"country_code": "+1"
},
"email": "<string>"
}
},
"payment_token": "187282ab-40ef-47a9-9206-5099ba31e432",
"shipping": {
"address": {
"city": "New York",
"country": "AF",
"line1": "123, King Street",
"line2": "Powelson Avenue",
"line3": "Bridgewater",
"zip": "08807",
"state": "New York",
"first_name": "John",
"last_name": "Doe"
},
"phone": {
"number": "9123456789",
"country_code": "+1"
},
"email": "<string>"
},
"billing": {
"address": {
"city": "New York",
"country": "AF",
"line1": "123, King Street",
"line2": "Powelson Avenue",
"line3": "Bridgewater",
"zip": "08807",
"state": "New York",
"first_name": "John",
"last_name": "Doe"
},
"phone": {
"number": "9123456789",
"country_code": "+1"
},
"email": "<string>"
},
"order_details": "[{\n \"product_name\": \"gillete creme\",\n \"quantity\": 15,\n \"amount\" : 900\n }]",
"email": "johntest@test.com",
"name": "John Test",
"phone": "9123456789",
"return_url": "https://hyperswitch.io",
"authentication_type": "three_ds",
"statement_descriptor_name": "Hyperswitch Router",
"statement_descriptor_suffix": "Payment for shoes purchase",
"next_action": {
"redirect_to_url": "<string>",
"type": "redirect_to_url"
},
"cancellation_reason": "<string>",
"error_code": "E0001",
"error_message": "Failed while verifying the card",
"unified_code": "<string>",
"unified_message": "<string>",
"payment_experience": "redirect_to_url",
"payment_method_type": "ach",
"connector_label": "stripe_US_food",
"business_country": "AF",
"business_label": "<string>",
"business_sub_label": "<string>",
"allowed_payment_method_types": [
"ach"
],
"ephemeral_key": {
"customer_id": "cus_y3oqhf46pyzuxjbcn2giaqnb44",
"created_at": 123,
"expires": 123,
"secret": "<string>"
},
"manual_retry_allowed": true,
"connector_transaction_id": "993672945374576J",
"frm_message": {
"frm_name": "<string>",
"frm_transaction_id": "<string>",
"frm_transaction_type": "<string>",
"frm_status": "<string>",
"frm_score": 123,
"frm_reason": "<any>",
"frm_error": "<string>"
},
"metadata": {},
"connector_metadata": {
"apple_pay": {
"session_token_data": {
"payment_processing_certificate": "<string>",
"payment_processing_certificate_key": "<string>",
"payment_processing_details_at": "Hyperswitch",
"certificate": "<string>",
"certificate_keys": "<string>",
"merchant_identifier": "<string>",
"display_name": "<string>",
"initiative": "web",
"initiative_context": "<string>",
"merchant_business_country": "AF"
}
},
"airwallex": {
"payload": "<string>"
},
"noon": {
"order_category": "<string>"
},
"braintree": {
"merchant_account_id": "<string>",
"merchant_config_currency": "<string>"
}
},
"feature_metadata": {
"redirect_response": {
"param": "<string>",
"json_payload": {}
},
"search_tags": [
"<string>"
],
"apple_pay_recurring_details": {
"payment_description": "<string>",
"regular_billing": {
"label": "<string>",
"recurring_payment_start_date": "2023-09-10T23:59:59Z",
"recurring_payment_end_date": "2023-09-10T23:59:59Z",
"recurring_payment_interval_unit": "year",
"recurring_payment_interval_count": 123
},
"billing_agreement": "<string>",
"management_url": "https://hyperswitch.io"
}
},
"reference_id": "993672945374576J",
"payment_link": {
"link": "<string>",
"secure_link": "<string>",
"payment_link_id": "<string>"
},
"profile_id": "<string>",
"surcharge_details": {
"surcharge_amount": 6540,
"tax_amount": 123
},
"attempt_count": 123,
"merchant_decision": "<string>",
"merchant_connector_id": "<string>",
"incremental_authorization_allowed": true,
"authorization_count": 123,
"incremental_authorizations": [
{
"authorization_id": "<string>",
"amount": 6540,
"status": "success",
"error_code": "<string>",
"error_message": "<string>",
"previously_authorized_amount": 123
}
],
"external_authentication_details": {
"authentication_flow": "challenge",
"electronic_commerce_indicator": "<string>",
"status": "started",
"ds_transaction_id": "<string>",
"version": "<string>",
"error_code": "<string>",
"error_message": "<string>"
},
"external_3ds_authentication_attempted": true,
"expires_on": "2022-09-10T10:11:12Z",
"fingerprint": "<string>",
"browser_info": {
"color_depth": 1,
"java_enabled": true,
"java_script_enabled": true,
"language": "<string>",
"screen_height": 1,
"screen_width": 1,
"time_zone": 123,
"ip_address": "<string>",
"accept_header": "text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,image/apng,*/*;q=0.8",
"user_agent": "<string>",
"os_type": "<string>",
"os_version": "<string>",
"device_model": "<string>"
},
"payment_method_id": "<string>",
"payment_method_status": "active",
"updated": "2022-09-10T10:11:12Z",
"split_payments": {
"stripe_split_payment": {
"charge_id": "<string>",
"charge_type": {
"Stripe": "direct"
},
"application_fees": 6540,
"transfer_account_id": "<string>"
}
},
"frm_metadata": {},
"extended_authorization_applied": true,
"capture_before": "2023-11-07T05:31:56Z",
"merchant_order_reference_id": "Custom_Order_id_123",
"order_tax_amount": 123,
"connector_mandate_id": "<string>",
"card_discovery": "manual",
"force_3ds_challenge": true,
"force_3ds_challenge_trigger": true,
"issuer_error_code": "<string>",
"issuer_error_message": "<string>"
}