Direct API Integration¶
Paysafe Redirect – API Integration¶
This page provides guidance for integrating Paysafe Redirect using the Direct API approach. Unlike the Hosted Payment Page (HPP) flow where the customer selects their payment method during the checkout process, the API flow assumes that the payment method has already been selected on your platform. This allows for a more seamless and controlled user experience.
With API integration, your platform is responsible for:
- Presenting and managing available payment methods
- Capturing the customer's selection
- Initiating the redirect payment request with the correct payment method type and data
- Redirecting the customer directly to Paysafe to complete the transaction
- Handling asynchronous notifications and updating final payment status
🔧 Payment Method Type Format¶
When initiating a payment request, the payment method type must follow this format:
paysafe-redirect-{code}
- All lowercase
- Use a hyphen (
-)
Examples:¶
paysafe-redirect-ali→ for AliPaypaysafe-redirect-psc→ for PaySafeCardpaysafe-redirect-obt→ for Rapid Transfer
Refer to the Supported Payment Methods for the complete list of available codes.
⚠️ Note: This prefix is mandatory. Incorrect or missing prefixes will result in request failures or improper routing.
🧾 Required Payment Method Data¶
In addition to the payment method type, each Paysafe Redirect request must include the following customer details in the payment method data:
emailfirst_namelast_name
These fields are required by Paysafe for regulatory and transactional reasons and must be collected before initiating the redirect.
Payment Gateway API 1.0.0¶
Endpoints¶
POST /api/transactions/authorize¶
Authorize Transaction
Description
Initiate Paysafe Redirect transaction. Requirements Jasmin + 2: - An
Authorization header with a valid Bearer token is required. - Payment
method type prefixed with paysafe-redirect- - Payment method data with
first_name, last_name and email
Input parameters
| Parameter | In | Type | Default | Nullable | Description |
|---|---|---|---|---|---|
bearerAuth |
header | string | N/A | No | JWT Bearer token |
Authorization |
header | string | No | Bearer token (e.g., "Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...") |
Request body
=== "application/json"
```json
{
"reference": "string",
"terminal_id": "string",
"description": "string",
"currency": "EUR",
"amount": 100,
"transaction_type": "PURCHASE",
"payment_method": {
"type": "paysafe-redirect-ali",
"data": {
"email": "derp@meme.org",
"first_name": "John",
"last_name": "Doe"
}
},
"metadata": {},
"return_url": "string",
"error_url": "string",
"cancel_url": "string"
}
```
<span class="small-note">⚠️</span> <em class="small-note warning">This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.</em>
??? hint "Schema of the request body"
```json
{
"type": "object",
"properties": {
"reference": {
"type": "string",
"description": "Unique transaction reference.",
"maxLength": 40,
"minLength": 1
},
"terminal_id": {
"type": "string",
"description": "Terminal identifier.",
"minLength": 5,
"maxLength": 20
},
"description": {
"type": "string",
"description": "Transaction description."
},
"currency": {
"type": "string",
"description": "Currency code (e.g., EUR).",
"example": "EUR",
"minLength": 3,
"maxLength": 3
},
"amount": {
"type": "integer",
"format": "int64",
"example": 100,
"description": "Transaction amount in minor units."
},
"transaction_type": {
"type": "string",
"enum": [
"PURCHASE"
],
"description": "Type of transaction."
},
"payment_method": {
"type": "object",
"properties": {
"type": {
"type": "string",
"enum": [
"paysafe-redirect-ali",
"paysafe-redirect-blt",
"paysafe-redirect-chp",
"paysafe-redirect-gir",
"paysafe-redirect-glu",
"paysafe-redirect-gfc",
"paysafe-redirect-obt",
"paysafe-redirect-npy",
"paysafe-redirect-ntl",
"paysafe-redirect-onb",
"paysafe-redirect-pgf",
"paysafe-redirect-psc",
"paysafe-redirect-pch",
"paysafe-redirect-pwy",
"paysafe-redirect-gch",
"paysafe-redirect-grp",
"paysafe-redirect-cns",
"paysafe-redirect-dna",
"paysafe-redirect-lnj",
"paysafe-redirect-mah",
"paysafe-redirect-spx",
"paysafe-redirect-khp",
"paysafe-redirect-spi",
"paysafe-redirect-sft",
"paysafe-redirect-epd"
],
"description": "Payment method type (e.g., paysafe-redirect-psc - Paysafe Card)."
},
"data": {
"type": "object",
"properties": {
"email": {
"type": "string",
"format": "email",
"description": "Email"
},
"first_name": {
"type": "string",
"example": "John",
"description": "First name"
},
"last_name": {
"type": "string",
"example": "Doe",
"description": "Last name"
}
},
"required": [
"email",
"first_name",
"last_name"
]
}
},
"required": [
"type",
"data"
]
},
"metadata": {
"type": "object",
"additionalProperties": true,
"description": "Additional metadata for the transaction."
},
"return_url": {
"type": "string",
"description": "URL to redirect to after successful processing."
},
"error_url": {
"type": "string",
"description": "URL to redirect to on error."
},
"cancel_url": {
"type": "string",
"description": "URL to redirect to if the transaction is canceled."
}
},
"required": [
"reference",
"terminal_id",
"description",
"currency",
"amount",
"transaction_type",
"payment_method",
"customer",
"browser_info",
"metadata",
"return_url",
"error_url",
"cancel_url"
]
}
```
Response 200 OK
=== "application/json"
```json
{
"result": null,
"action": null,
"redirect": {
"transaction_id": "vvIVFmPuwYosePLsoDsW",
"session_id": "vvIVFmPuwYosePLsoDsW",
"url": "https://pay.skrill.com?sid=vvIVFmPuwYosePLsoDsW"
},
"form_submit": null
}
```
```json
{
"result": {
"id": "TwAtRCuUVgNMuynYLfPt",
"merchant_id": "0000000000000fpg-dev",
"order_id": "oeTgLdAXNFnpxELFzeof",
"terminal_id": "0000000000000fpg-dev",
"reference": "jYKkVRAcEJganWPBvgcOUPObgfqGQXoQiSnWgKkM",
"description": "rOFtlUXaYcolNOFrjqlpIOjrKzJvPaJtpHoKHFfF",
"currency": "EUR",
"amount": 100,
"customer": {
"first_name": null,
"last_name": null,
"address": null,
"city": null,
"country": null,
"postal_code": null,
"email": null,
"phone": null,
"id": null
},
"processing_result": {
"payment_provider_id": "YmlVNADqBCmHgSbVruIb",
"payment_provider_account_id": "IyNmNmCntPaEpXMatLkB",
"approval_code": null,
"reference_number": null
},
"approved": false,
"pending": false,
"channel": "ecommerce",
"transaction_type": "PURCHASE",
"status": "DECLINED",
"payment_method": {
"method": "paysafe-redirect-pcs",
"hash": null,
"type": "paysafe-redirect-pcs",
"masked": "paysafe-redirect-pcs"
},
"redirect_url": null,
"normalized_amount": 100,
"errors": []
},
"action": null,
"redirect": null,
"form_submit": null
}
```
??? hint "Schema of the response body"
```json
{
"type": "object",
"properties": {
"result": {
"$ref": "#/components/schemas/ExtendedTransactionDto",
"description": "Extended transaction details."
},
"action": {
"$ref": "#/components/schemas/ActionRequiredDto",
"description": "Details for any required action (e.g., fingerprint, challenge)."
},
"redirect": {
"$ref": "#/components/schemas/RedirectDto",
"description": "Redirect information for the transaction."
},
"form_submit": {
"$ref": "#/components/schemas/FormSubmitDto",
"description": "Form submission details if required."
}
},
"description": "Response payload for executing a transaction."
}
```
Response 422 Unprocessable Content
=== "application/json"
```json
{
"errors": [
{
"message": "The size of \"reference\" must be less than or equal to 40. The given size is 100",
"params": [
"reference",
"40",
"100"
],
"property": "reference"
}
],
"method": "POST",
"status": 422
}
```
??? hint "Schema of the response body"
```json
{
"type": "object",
"properties": {
"errors": {
"type": "array",
"items": {
"type": "object",
"properties": {
"message": {
"type": "string"
},
"params": {
"type": "array",
"items": {
"type": "string"
}
},
"property": {
"type": "string"
}
}
}
},
"method": {
"type": "string"
},
"status": {
"type": "integer"
}
}
}
```
Schemas¶
ActionRequiredDto¶
| Name | Type |
|---|---|
payment_data |
string |
session_id |
string |
token |
string |
transaction_id |
string |
type |
string |
ExecuteTransactionResponseDto¶
| Name | Type |
|---|---|
action |
ActionRequiredDto |
form_submit |
FormSubmitDto |
redirect |
RedirectDto |
result |
ExtendedTransactionDto |
ExtendedTransactionDto¶
| Name | Type |
|---|---|
amount |
integer(int64) |
approved |
boolean |
channel |
string |
currency |
string |
customer |
CustomerDto |
description |
string |
errors |
Array<> |
id |
string |
merchant_id |
string |
normalized_amount |
integer(int64) |
order_id |
string |
payment_method |
PaymentMethodDataDto |
pending |
boolean |
processing_result |
ProcessingResultDto |
redirect_url |
string |
reference |
string |
status |
TransactionStatus |
terminal_id |
string |
transaction_type |
string |
FormSubmitDto¶
| Name | Type |
|---|---|
data |
|
session_id |
string |
transaction_id |
string |
url |
string |
PaymentMethodDataDto¶
| Name | Type |
|---|---|
brand |
string |
hash |
string |
masked |
string |
method |
string |
token |
string| null |
type |
string |
ProcessingResultDto¶
RedirectDto¶
| Name | Type |
|---|---|
session_id |
string |
transaction_id |
string |
url |
string |
TransactionExecuteRequestDto¶
| Name | Type |
|---|---|
amount |
integer(int64) |
cancel_url |
string |
currency |
string |
description |
string |
error_url |
string |
metadata |
|
payment_method |
Properties: type, data |
reference |
string |
return_url |
string |
terminal_id |
string |
transaction_type |
string |
TransactionStatus¶
Type: string
Security schemes¶
| Name | Type | Scheme | Description |
|---|---|---|---|
| bearerAuth | http | bearer |
OpenAPI: External YAML reference (to be migrated locally)