This section extends the Direct API Integration documentation by describing how to send additional customization parameters to Paysafe through the API.

Overview

You can include optional Paysafe-specific parameters in the options.paysafe_redirect.params field of the authorization request. These parameters are forwarded as-is to Paysafe and can affect the redirect behavior or transaction processing.

For up-to-date details on the usage and meaning of individual parameters, refer to the official Paysafe integration documentation provided by your Paysafe account representative.

Payload Structure

The parameters are passed as an array of key-value objects under the options.paysafe_redirect.params field:

"options": {
  "paysafe_redirect": {
    "params": [
      {
        "key": "recipient_description",
        "value": "Your Value"
      },
      {
        "key": "psp_id",
        "value": "Your Value"
      },
      {
        "key": "country",
        "value": "DEU"
      }
    ]
  }
}

Supported Keys

The following parameter keys are currently supported:

• recipient_description
• psp_id
• country (ISO 3166-1 alpha-3 code, e.g., DEU for Germany)
• return_url_target - Specifies the target window/frame for the return URL after successful payment. Accepts numeric values:
  • 1 = _top (default) - Loads in the full browser window
  • 2 = _parent - Loads in the parent frame
  • 3 = _self - Loads in the same frame
  • 4 = _blank - Opens in a new window/tab

These parameters are optional. If not provided, default settings from your Paysafe configuration will apply.

Full Example

{
  "reference": "REF123456789",
  "terminal_id": "TEST_TERMINAL",
  "description": "TEST_TERMINAL",
  "currency": "EUR",
  "amount": 100,
  "transaction_type": "PURCHASE",
  "payment_method": {
    "type": "paysafe-redirect-ali",
    "data": {
      "email": "user@example.com",
      "first_name": "FirstName",
      "last_name": "LastName"
    }
  },
  "metadata": {
    "order_id": "ORDER-XXXXXX"
  },
  "return_url": "https://google.com",
  "options": {
    "paysafe_redirect": {
      "params": [
        {
          "key": "recipient_description",
          "value": "Business Name"
        },
        {
          "key": "psp_id",
          "value": "PSPID-XXXXXX"
        },
        {
          "key": "country",
          "value": "DEU"
        },
        {
          "key": "return_url_target",
          "value": "1"
        }
      ]
    }
  }
}

Tip: Ensure any values you include are validated and coordinated with Paysafe support to guarantee expected behavior.