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 uses that specific payment method configuration.
2. Amount and Currency Matching - The system attempts to find a suitable payment method based on the payout amount and currency.
3. Routing Rules - If your account is configured with routing rules, the system applies those rules to select the most appropriate payment method based on your criteria (amount, currency, region, etc.).

If the system cannot determine a suitable payment method, you will receive error code 1-03-02.

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.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.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.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.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.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 specific to the Payout via Payment Page feature:

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-02-02	Required payment method fields are missing for order creation	Either provide all required recipient fields in the request, or contact support to enable the payment page feature
1-03-02	No suitable payment method found for the provided parameters	Check your request parameters (amount, currency, payment method details). Ensure routing rules are configured, or provide explicit payment method parameters
1-02-06	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	Declined by provider	The payout was declined by the payment provider. Check the payout details and try again, or contact the recipient to verify their information