Payout via Payment Page

Description

The Payout via Payment Page feature allows you to initiate payouts without providing all needed details upfront. When required information is missing, the system generates a payment page link where the recipient can securely enter their payout details.

This approach simplifies the integration process by reducing the number of mandatory fields in your initial API request.

Overview

Traditional payout flow requires you to provide all recipient details (card number, bank account, wallet ID, etc.) in the API request. With the Payment Page flow, you can:

• Create a payout request with minimal required fields
• Receive a payment page URL when additional recipient information is needed
• Redirect the recipient to the payment page to complete their details
• The system processes the payout once all information is collected

Prerequisites

Before using this feature, ensure the following configuration is enabled for your merchant account. Contact technical support to enable this setting for your company.

How It Works

Payment Method Determination

The system automatically determines which payment method to use for processing the payout. The selection follows this priority:

1. Payment Settings Alias - If you provide paymentSettingsAlias in the request, the system selects the payment method tied to that alias. The alias must match the other payout parameters you send; otherwise the payout is failed with 1-03-06.
2. Request parameters - The system tries to uniquely identify a single payment method from the parameters in the request (providerCode, acquirerCode, instrumentType, cost.currency, dataEntryMode, and, where applicable, the recipient's transferType or walletType).
3. Routing Rules - If the method is still not uniquely determined and your shop is configured to select the method by routing, the system applies your routing rules. When a rule needs data that has not been provided yet (for example, the recipient's card BIN), the system returns a payoutLink so the recipient can supply it on the payment page before routing runs. If that data is missing and data collection on the payment page is disabled for your shop, the payout is failed with 1-03-13.

If the system cannot determine a suitable payment method, the payout is failed with a status code that identifies the reason — for example 1-03-01 (the request did not identify a method and your shop selects methods by request parameters only) or 1-03-02 (no routing rule matched). For the list of status codes, see Status Codes.

Required Fields

Always Required:

• shopId - Your shop identifier
• payout.payoutNumber - Unique payout identifier from your system
• payout.cost.amount - Payout amount
• payout.cost.currency - Payout currency

When Payment Page is Used

After you create a payout request, the system checks if all required recipient information is provided:

• All required fields provided - The payout is processed immediately. The API response will contain only payoutStatus and payoutNumber. No payoutLink is returned.
• Missing required fields - The API response includes a payoutLink field. You must redirect the recipient to this URL to complete their information.

The system determines required fields based on the selected payment method (card, bank transfer, wallet, etc.). Different payment methods require different recipient details.

Integration Steps

Step 1: Create Payout Request

Call the Create Payout Request endpoint with minimal required fields.

Request Example:

curl -L -X POST 'https://gateway.demo.vertexgateway.com/api/v1/payouts' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Api-Access-Token: YOUR_API_KEY' \
--data-raw '{
  "shopId": 123,
  "payout": {
    "cost": {
      "amount": "100.00",
      "currency": "USD"
    },
    "payoutNumber": "payout_12345"
  },
  "purpose": "Withdrawal request",
  "redirectUrls": {
    "success": "https://yoursite.com/payout/success",
    "failure": "https://yoursite.com/payout/failure",
    "inProgress": "https://yoursite.com/payout/pending"
  }
}'

Response (when payment page is needed):

{
  "data": {
    "payoutStatus": "in_progress",
    "payoutNumber": "payout_12345",
    "payoutLink": "https://payment-page.demo.vertexgateway.com/session/abc123xyz"
  }
}

The payoutLink field is present because the system needs additional recipient information. Redirect the recipient to this URL.

Response (when all required fields are provided):

{
  "data": {
    "payoutStatus": "in_progress",
    "payoutNumber": "payout_12345"
  }
}

Step 2: Check for Payment Page Link

After creating the payout request, check the response for the payoutLink field:

• If payoutLink is present - Redirect the recipient to this URL to complete their payout details.
• If payoutLink is absent - The payout is being processed with the information provided. No further action is needed.

Step 3: Redirect to Payment Page

Redirect the recipient to the payoutLink URL. The payment page will:

• Display pre-filled information (amount, currency, and any provided recipient details) as read-only fields
• Show form fields for missing recipient information
• Process the payout upon successful submission

Step 4: Verify Payout Status

Use the Retrieve Payout Status endpoint to verify the final payout status.

curl -L -X GET 'https://gateway.demo.vertexgateway.com/api/v1/payouts/123/payout_12345' \
-H 'Accept: application/json' \
-H 'Api-Access-Token: YOUR_API_KEY'

Advanced Usage

Using Payment Method Alias

If you want to specify a particular payment method configuration, you can use the paymentSettingsAlias parameter:

curl -L -X POST 'https://gateway.demo.vertexgateway.com/api/v1/payouts' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Api-Access-Token: YOUR_API_KEY' \
--data-raw '{
  "shopId": 123,
  "payout": {
    "cost": {
      "amount": "100.00",
      "currency": "USD"
    },
    "payoutNumber": "payout_12346"
  },
  "paymentSettingsAlias": "my_card_payout_method",
  "purpose": "Withdrawal request",
  "redirectUrls": {
    "success": "https://yoursite.com/payout/success",
    "failure": "https://yoursite.com/payout/failure"
  }
}'

The paymentSettingsAlias value is obtained from the Retrieve Payout Methods endpoint. For more information, see the Alias Documentation.

Providing Partial Recipient Information

You can provide some recipient information in the initial request. Fields provided will be pre-filled and displayed as read-only on the payment page:

curl -L -X POST 'https://gateway.demo.vertexgateway.com/api/v1/payouts' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Api-Access-Token: YOUR_API_KEY' \
--data-raw '{
  "shopId": 123,
  "payout": {
    "cost": {
      "amount": "100.00",
      "currency": "USD"
    },
    "payoutNumber": "payout_12347"
  },
  "purpose": "Withdrawal request",
  "instrumentType": "card",
  "recipient": {
    "personalData": {
      "firstName": "John",
      "lastName": "Doe",
      "email": "john.doe@example.com"
    }
  },
  "redirectUrls": {
    "success": "https://yoursite.com/payout/success",
    "failure": "https://yoursite.com/payout/failure"
  }
}'

In this example, the payment page will display the recipient's name and email as read-only fields, and only request the missing card number.

Error Codes

The following error codes are most commonly seen with the Payout via Payment Page feature. For the complete list and descriptions, see Status Codes.

Error Code	Description	Resolution
1-02-01	Payout order creation via H2H is not configured	Contact technical support to enable payout creation via API for your account
1-03-01	No suitable payment method found for the provided parameters	Check your request parameters (amount, currency, payment method details), or provide explicit payment method parameters
1-03-02	No routing rules found for order parameters	Ensure routing rules are configured for the payout amount and currency, or provide explicit payment method parameters in the request
1-03-13	Required routing parameters are missing and collection on payment page is disabled	The selected routing needs data that was not provided (such as the card BIN). Provide those parameters in the request, or contact support to enable data collection on the payment page
1-02-07	Required sender fields are missing	Provide the required sender information in the sender object. Use the Retrieve Required Payout Fields endpoint to determine which fields are needed
1-07-01	Missing required parameters for the selected payment method	Provide the parameters required by the selected payment method in the request, or have the recipient supply the missing details on the payment page
1-01-03	The payout was cancelled because the recipient did not submit the required data on the payment page before the timeout window expired	Create a new payout request. If recipients often need more time, contact technical support to review the timeout window