πŸ”—Payout links

Low-code solution to accept payouts

Introducing Payout Links - Make sending out money to beneficiaries, simple and easy. Improve customer / vendor / partner's experience by making instant payouts in their preferred mode of transaction with preferred processor.

  • Corporates - Pay marketing affiliates and reimburse employees.

  • BFSI (Banking, Financial Services, and Insurance) - Settling insurance claims and paying DSA (Direct Selling Agents) incentives.

  • Healthcare - Pay field agents, handle reimbursements, and issue refunds.

  • Travel and Hospitality - Pay commissions to vendors, handle reimbursements and do refunds.

  • Rental Business - Process Security Deposit Refunds for all rental business like car, housing, furniture and appliances.

  • Online gaming - Distribute prize money to players.

  • NGOs & Political Organisations - Reimburse field agents and volunteers.

Prerequisites

  • Create a Hyperswitch account via the dashboard and create a profile (read more)

  • Add a payout processor to your account

Note: Domain name might vary based on the testing and production environment.

Info: Payout links are secure by nature and should only be opened within an iframe of whitelisted domains in production. For ease of access, these links can be used in a test mode (for non production env) which removes the necessity of configuring whitelisted domains and loading these links within an iframe.

There are a couple of ways for using payout links.

  • Creating default links

  • Customizing UI of individual links

  • Serving links from a custom domain

  • [TEST MODE] Opening non-iframed links

"payout_link_config": {
  // (optional) Custom theme color for your payout link.
  // Can be any html color hex code.
  "theme": "#143F1E",

  // (optional) Custom logo for your company.
  // Can be any hosted image URL.
  "logo": "https://hyperswitch.io/favicon.ico",

  // (optional) Name of your company.
  "merchant_name": "HyperSwitch",

  // (required in production) A list of domain glob patterns.
  // This is used as validation when payout link render request is received, and also helps block XSS on client.
  "allowed_domains": ["http://localhost:8080"],

  // (only available in sandbox) Controls access to payout link.
  // This is used to control whether or not to validate the access to payout link.
  "payout_test_mode": false
}

Note: It is recommended to set payout_test_mode to true for quickly testing the payout links. Alternatively, test_mode can be sent in the individual payout link's create request.

This creates a default payout link using the payout link config that was configured for the profile. In case payout config is not configured and not passed during create request, a default set of UI config is used.

  • Set payout_link to true

curl --location 'https://sandbox.hyperswitch.io/payouts/create' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'api-key: YOUR_API_KEY' \
--data '{
    "amount": 100,
    "currency": "EUR",
    "customer_id": "cus_123",
    "name": "John Doe",
    "phone": "999999999",
    "email": "payout_customer@example.com",
    "phone_country_code": "+65",
    "description": "Its my first payout request",
    "billing": {
        "address": {
            "line1": "1467",
            "line2": "Harrison Street",
            "line3": "Harrison Street",
            "city": "San Fransico",
            "state": "CA",
            "zip": "94122",
            "country": "US",
            "first_name": "John",
            "last_name": "Doe"
        },
        "phone": {
            "number": "9000000001",
            "country_code": "+91"
        }
    },
    "payout_link" : true,
    "confirm": false,
    "session_expiry":2592000
}'

Each payout link can be configured inidividually during payout creation, by including the payout_link_config object. UI config and access control (test_mode) can be specified during creation. However, domain_name is always configured at a profile level.

curl --location 'https://sandbox.hyperswitch.io/payouts/create' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'api-key: YOUR_API_KEY' \
--data '{
    "amount": 1130,
    "currency": "USD",
    "confirm": false,
    "customer_id": "cus_123",
    "return_url": "https://hyperswitch.io",
    "description": "Cashback from RetroRecords",
    "payout_link": true,
    "billing": {
        "address": {
            "line1": "1467",
            "line2": "Harrison Street",
            "line3": "Harrison Street",
            "city": "San Fransico",
            "state": "CA",
            "zip": "94122",
            "country": "US",
            "first_name": "John",
            "last_name": "Doe"
        },
        "phone": {
            "number": "9000000001",
            "country_code": "+91"
        }
    },
    "session_expiry": 2592000,
    "payout_link_config": {
        "logo": "https://img.freepik.com/premium-vector/music-vector-logo-illustration-design-template_593008-640.jpg?w=1480",
        "theme": "#92817A",
        "merchant_name": "Retro Records"
    }
}'

Note: This feature is available only in non-production environment. This essentially bypasses the server side and client side validations which are in place for making sure links are only opened within an iframe of a whitelisted domain.

Note: This can be achieved by either setting this behaviour at the business profile level, or can be set in individual link create requests.

Setting at business profile level

"payout_link_config": {
  "payout_test_mode": true
}
  • Any new payout links created for this business profile will be accessible through browser's new tab.

Creating test links on demand

  • Set test_mode during payout link creation

curl --location 'https://sandbox.hyperswitch.io/payouts/create' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'api-key: YOUR_API_KEY' \
--data '{
    "amount": 1130,
    "currency": "USD",
    "confirm": false,
    "customer_id": "cus_123",
    "return_url": "https://hyperswitch.io",
    "description": "Rewards from HyperSwitch",
    "payout_link": true,
    "billing": {
        "address": {
            "line1": "1467",
            "line2": "Harrison Street",
            "line3": "Harrison Street",
            "city": "San Fransico",
            "state": "CA",
            "zip": "94122",
            "country": "US",
            "first_name": "John",
            "last_name": "Doe"
        },
        "phone": {
            "number": "9000000001",
            "country_code": "+91"
        }
    },
    "session_expiry": 2592000,
    "payout_link_config": {
        "test_mode": true
    }
}'

FAQ

Last updated