Authorize

Payment Gateway API 1.0.0

This API authorizes card transactions.

Access Token: Obtain an access token using your client credentials (client_id and client_secret are available in your merchant dashboard). See the Obtain Access Token documentation for details.

Process Card Transaction: The /api/transactions/authorize endpoint processes a card transaction and returns detailed response data.

Important: This endpoint requires an Authorization header with a valid Bearer token. Additionally, card data fields must be encrypted using your public key before sending.

Encryption Example (Shell using OpenSSL):

#!/bin/bash
PUBLIC_KEY="-----BEGIN PUBLIC KEY-----\n...your public key here...\n-----END PUBLIC KEY-----"
CARD_NUMBER="4111111111111111"
CVV="123"
EXPIRATION_MONTH="10"
EXPIRATION_YEAR="2045"

encrypt_field() {
  echo -n "$1" | openssl rsautl -encrypt -pubin -inkey <(echo "$PUBLIC_KEY") | base64
}

ENCRYPTED_CARD_NUMBER=$(encrypt_field "$CARD_NUMBER")
ENCRYPTED_CVV=$(encrypt_field "$CVV")
ENCRYPTED_EXPIRATION_MONTH=$(encrypt_field "$EXPIRATION_MONTH")
ENCRYPTED_EXPIRATION_YEAR=$(encrypt_field "$EXPIRATION_YEAR")

echo "Encrypted Card Number: $ENCRYPTED_CARD_NUMBER"
echo "Encrypted CVV: $ENCRYPTED_CVV"
echo "Encrypted Expiration Month: $ENCRYPTED_EXPIRATION_MONTH"
echo "Encrypted Expiration Year: $ENCRYPTED_EXPIRATION_YEAR"

---

Servers

Description	URL
https://api.example.com	https://api.example.com

Endpoints

---

POST /api/transactions/authorize

Authorize Transaction

Description

Authorize a card transaction.

Requirements: - An Authorization header with a valid Bearer token is required. - Card details must be encrypted using your public key. See the encryption example above.

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

{
    "reference": "string",
    "terminal_id": "string",
    "description": "string",
    "currency": "EUR",
    "amount": 211,
    "transaction_type": "AUTHORIZE",
    "payment_method": {
        "type": "card",
        "data": null
    },
    "tokenization": {
        "save_card_for_future_payments": true
    },
    "customer": {
        "first_name": "string",
        "last_name": "string",
        "address": "string",
        "city": "string",
        "country": "string",
        "postal_code": "string",
        "email": "string",
        "phone": "string",
        "id": "string"
    },
    "browser_info": {
        "user_agent": "Mozilla/5.0 (X11; U; Linux i686; en-US; rv:1.9) Gecko/2008052912 Firefox/3.0",
        "accept_header": "text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8",
        "java_enabled": true,
        "color_depth": 10,
        "screen_height": 2000,
        "screen_width": 3000,
        "time_zone_offset": 5,
        "language": "en"
    },
    "metadata": {},
    "return_url": "string",
    "customer_ip": "203.0.113.42"
}

⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the request body

{
    "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",
            "description": "Transaction amount in minor units."
        },
        "transaction_type": {
            "type": "string",
            "enum": [
                "AUTHORIZE",
                "PURCHASE"
            ],
            "description": "Type of transaction."
        },
        "payment_method": {
            "type": "object",
            "properties": {
                "type": {
                    "type": "string",
                    "enum": [
                        "card",
                        "saved_card",
                        "network-token"
                    ],
                    "example": "card",
                    "description": "Payment method type:\n- `card` — New card payment with encrypted card details\n- `saved_card` — Tokenized payment method from a previous transaction\n- `network-token` — Pre-decrypted network token data (e.g. from Apple Pay, Google Pay, or other TSP integrations)\n"
                },
                "data": {
                    "oneOf": [
                        {
                            "$ref": "#/components/schemas/CardPaymentData"
                        },
                        {
                            "$ref": "#/components/schemas/SavedCardPaymentData"
                        },
                        {
                            "$ref": "#/components/schemas/NetworkTokenPaymentData"
                        }
                    ]
                }
            },
            "required": [
                "type",
                "data"
            ]
        },
        "tokenization": {
            "$ref": "#/components/schemas/TokenizationDto"
        },
        "customer": {
            "$ref": "#/components/schemas/CustomerDto"
        },
        "browser_info": {
            "$ref": "#/components/schemas/BrowserInfo"
        },
        "metadata": {
            "type": "object",
            "additionalProperties": true,
            "description": "Additional metadata for the transaction."
        },
        "return_url": {
            "type": "string",
            "description": "URL to redirect to after the transaction completes (approved, declined, canceled, or error)."
        },
        "customer_ip": {
            "type": "string",
            "nullable": true,
            "description": "Customer's IP address (IPv4 or IPv6). Optional.\n\nIf omitted or empty, the gateway falls back to the IP address of the incoming HTTP request. Provide this field explicitly when the request reaches the gateway through your own backend, so that fraud and 3DS risk checks see the end customer's IP rather than your server's.\n",
            "example": "203.0.113.42"
        }
    },
    "required": [
        "reference",
        "terminal_id",
        "description",
        "currency",
        "amount",
        "transaction_type",
        "payment_method",
        "customer",
        "browser_info",
        "metadata",
        "return_url"
    ]
}

Responses

200 OK422 Unprocessable Content

application/json

{
    "result": null,
    "action": null,
    "redirect": {
        "transaction_id": "vvIVFmPuwYosePLsoDsW",
        "session_id": "vvIVFmPuwYosePLsoDsW",
        "url": "https://redirect-domain-example.com"
    },
    "form_submit": null
}

{
    "result": {
        "id": "QGdRemFVORbimpWHrHtu",
        "merchant_id": "0000000000000fpg-dev",
        "order_id": "HRfkRyHcrSlRJxKqbgyY",
        "terminal_id": "0000000000000fpg-dev",
        "reference": "ghymUfiJTkugUelglUqBfcdmPKnmHfNJJbmylxAr",
        "description": "DjfehLZprMcAFiQSnozDMdFfbaYcatErWriiWVjr",
        "currency": "EUR",
        "amount": 100,
        "customer": {
            "first_name": "Jeanine",
            "last_name": "Hilpert",
            "address": "130 Adams Viaduct",
            "city": "Hammesland",
            "country": "Guyana",
            "postal_code": "11698",
            "email": "antonio.littel@hotmail.com",
            "phone": "+1 614-501-4825 x6600",
            "id": null
        },
        "processing_result": {
            "payment_provider_id": "zqdejuEYUNDUZDZBGTam",
            "payment_provider_account_id": "PVuYwNrzQMOQRpruRTxs",
            "approval_code": "sTiSYs",
            "reference_number": ""
        },
        "approved": true,
        "pending": false,
        "channel": "ecommerce",
        "transaction_type": "AUTHORIZE",
        "status": "APPROVED",
        "payment_method": {
            "method": "411111-******-1111",
            "hash": null,
            "type": "card",
            "brand": "VISA",
            "masked": "411111-******-1111",
            "token": null
        },
        "redirect_url": "https://test.com/return-url",
        "normalized_amount": 100,
        "errors": []
    },
    "action": null,
    "redirect": null,
    "form_submit": null
}

{
    "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": "string",
            "last_name": "string",
            "address": "string",
            "city": "string",
            "country": "string",
            "postal_code": "string",
            "email": "string",
            "phone": "string",
            "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": "AUTHORIZE",
        "status": "DECLINED",
        "payment_method": {
            "method": "424242-******-4242",
            "hash": null,
            "type": "saved_card",
            "brand": "VISA",
            "masked": "424242-******-4242",
            "token": "VVWeQYCIIQZbYEgshQQn"
        },
        "redirect_url": null,
        "normalized_amount": 100,
        "errors": []
    },
    "action": null,
    "redirect": null,
    "form_submit": null
}

{
    "result": {
        "id": "XYZabcDEF123456789",
        "merchant_id": "0000000000000fpg-dev",
        "order_id": "ORD_20241021_001",
        "terminal_id": "TERM001",
        "reference": "ORDER-123456",
        "description": "Order payment with card saving",
        "currency": "EUR",
        "amount": 10000,
        "customer": {
            "first_name": "John",
            "last_name": "Doe",
            "address": "123 Example Street",
            "city": "Sampletown",
            "country": "BA",
            "postal_code": "12345",
            "email": "john.doe@example.com",
            "phone": "+1234567890",
            "id": "CUST123456"
        },
        "processing_result": {
            "payment_provider_id": "PP_ABC123",
            "payment_provider_account_id": "PPACCT_XYZ789",
            "approval_code": "AUTH123",
            "reference_number": "REF_987654"
        },
        "approved": true,
        "pending": false,
        "channel": "ecommerce",
        "transaction_type": "AUTHORIZE",
        "status": "APPROVED",
        "payment_method": {
            "method": "411111-******-1111",
            "hash": null,
            "type": "card",
            "brand": "VISA",
            "masked": "411111-******-1111",
            "token": "abc123def456ghi789"
        },
        "redirect_url": "https://merchant.example.com/return",
        "normalized_amount": 10000,
        "errors": []
    },
    "action": null,
    "redirect": null,
    "form_submit": null
}

{
    "result": {
        "id": "TXN_SAVED_789012",
        "merchant_id": "0000000000000fpg-dev",
        "order_id": "ORD_20241021_002",
        "terminal_id": "TERM001",
        "reference": "ORDER-789012",
        "description": "Subscription renewal",
        "currency": "EUR",
        "amount": 5000,
        "customer": {
            "first_name": "John",
            "last_name": "Doe",
            "address": "123 Example Street",
            "city": "Sampletown",
            "country": "BA",
            "postal_code": "12345",
            "email": "john.doe@example.com",
            "phone": "+1234567890",
            "id": "CUST123456"
        },
        "processing_result": {
            "payment_provider_id": "PP_DEF456",
            "payment_provider_account_id": "PPACCT_UVW321",
            "approval_code": "AUTH789",
            "reference_number": "REF_654321"
        },
        "approved": true,
        "pending": false,
        "channel": "ecommerce",
        "transaction_type": "PURCHASE",
        "status": "APPROVED",
        "payment_method": {
            "method": "411111-******-1111",
            "hash": null,
            "type": "saved_card",
            "brand": "VISA",
            "masked": "411111-******-1111",
            "token": "abc123def456ghi789"
        },
        "redirect_url": "https://merchant.example.com/return",
        "normalized_amount": 5000,
        "errors": []
    },
    "action": null,
    "redirect": null,
    "form_submit": null
}

Schema of the response body

{
    "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."
}

application/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
}

Schema of the response body

{
    "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	Description
payment_data	string	Encrypted payment data; sensitive card details are not stored in memory
session_id	string
token	string	Base64 encoded data; value depends on type
transaction_id	string
type	string	Action type: THREE_DS_2_FINGERPRINT (device fingerprint collection required) or THREE_DS_2_CHALLENGE (3DS challenge authentication required)

BrowserInfo

Name	Type	Description
accept_header	string	HTTP Accept header.
color_depth	integer	Color depth of the browser display.
java_enabled	boolean	Indicates if Java is enabled in the browser.
language	string	Browser language.
screen_height	integer	Screen height in pixels.
screen_width	integer	Screen width in pixels.
time_zone_offset	integer	Time zone offset from UTC.
user_agent	string	Browser user agent string.

CardPaymentData

Name	Type	Description
encrypted_card_number	string	Encrypted card number.
encrypted_cvv	string	Encrypted CVV.
encrypted_expiration_month	string	Encrypted expiration month. Plain-text value must be an integer with no leading zero (range: 1–12).
encrypted_expiration_year	string	Encrypted expiration year. Plain-text value may be 2-digit (e.g. `26`) or 4-digit (e.g. `2026`). Must represent the current or a future year.

CustomerDto

Name	Type	Description
address	string | null
city	string | null
country	string | null
email	string | null
first_name	string | null
id	string | null
last_name	string | null
phone	string | null
postal_code	string | null

ExecuteTransactionResponseDto

Name	Type	Description
action	ActionRequiredDto	Details for any required action (e.g., fingerprint, challenge).
form_submit	FormSubmitDto	Form submission details if required.
redirect	RedirectDto	Redirect information for the transaction.
result	ExtendedTransactionDto	Extended transaction details.

ExtendedTransactionDto

Name	Type	Description
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	Description
data
session_id	string
transaction_id	string
url	string

NetworkTokenPaymentData

Name	Type	Description
eci	string	Electronic Commerce Indicator. Indicates the level of authentication performed. Common values: `"05"` (fully authenticated), `"06"` (attempted authentication), `"07"` (non-3DS transaction). **Not encrypted** — sent as plain text.
encrypted_cryptogram	string | null	Encrypted payment cryptogram (3DS cryptogram / TAVV). Must be encrypted using your merchant public key. **Optional** — absent for PAN_ONLY tokens (e.g. Google Pay PAN_ONLY authentication method). Required for CRYPTOGRAM_3DS authentication.
encrypted_expiration_month	string	Encrypted expiration month of the network token. Plain-text value must be an integer with no leading zero (range: 1–12). Must be encrypted using your merchant public key.
encrypted_expiration_year	string	Encrypted expiration year of the network token. Plain-text value may be 2-digit (e.g. `26`) or 4-digit (e.g. `2026`). Must represent the current or a future year. Must be encrypted using your merchant public key.
encrypted_token_number	string	Encrypted Device Primary Account Number (DPAN). This is the network token that substitutes the actual card PAN. Must be encrypted using your merchant public key.
source	string	Identifies the origin of the network token. Used for transaction routing and reporting. **Not encrypted** — sent as plain text.

PaymentMethodDataDto

Name	Type	Description
brand	string
hash	string
masked	string
method	string
token	string | null
type	string

ProcessingResultDto

RedirectDto

Name	Type	Description
session_id	string
transaction_id	string
url	string

SavedCardPaymentData

Name	Type	Description
encrypted_cvv	string	Encrypted CVV. May be required depending on Payment Provider support. **Important:** When required, must be encrypted using your public key.
payment_method_id	string	The payment method token/ID from a previous transaction where the card was saved.

TokenizationDto

Name	Type	Description
save_card_for_future_payments	boolean	If true, the card will be saved for future payments. Requires tokenization to be enabled at the merchant level. If a customer.id is provided, the payment method will be associated with that customer.

TransactionExecuteRequestDto

Name	Type	Description
amount	integer(int64)	Transaction amount in minor units.
browser_info	BrowserInfo
currency	string	Currency code (e.g., EUR).
customer	CustomerDto
customer_ip	string | null	Customer's IP address (IPv4 or IPv6). Optional. If omitted or empty, the gateway falls back to the IP address of the incoming HTTP request. Provide this field explicitly when the request reaches the gateway through your own backend, so that fraud and 3DS risk checks see the end customer's IP rather than your server's.
description	string	Transaction description.
metadata		Additional metadata for the transaction.
payment_method	Properties: type, data
reference	string	Unique transaction reference.
return_url	string	URL to redirect to after the transaction completes (approved, declined, canceled, or error).
terminal_id	string	Terminal identifier.
tokenization	TokenizationDto
transaction_type	string	Type of transaction.

TransactionStatus

Type: string

Security schemes

Name	Type	Scheme	Description
bearerAuth	http	bearer