Authorize¶

Payment Gateway API 1.0.0¶

This API authorizes card transactions.

Access Token: Use the /api/token endpoint to obtain an access token using your client credentials (client_id and client_secret are available in your merchant dashboard).

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": 5,
    "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",
    "error_url": "string",
    "cancel_url": "string"
}

⚠️ 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"
                    ],
                    "example": "card",
                    "description": "Payment method type. Use 'card' for new card payments or 'saved_card' for tokenized payment methods."
                },
                "data": {
                    "oneOf": [
                        {
                            "$ref": "#/components/schemas/CardPaymentData"
                        },
                        {
                            "$ref": "#/components/schemas/SavedCardPaymentData"
                        }
                    ]
                }
            },
            "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 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

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

Response 422 Unprocessable Content

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

POST /api/token¶

Obtain Access Token

Description

Request an access token using your client credentials. The client_id and client_secret can be found on your merchant dashboard.

Request body

application/json

{
    "client_id": "string",
    "client_secret": "string",
    "grant_type": "string"
}

⚠️ 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": {
        "client_id": {
            "type": "string",
            "description": "The client ID from your merchant dashboard."
        },
        "client_secret": {
            "type": "string",
            "description": "The client secret from your merchant dashboard."
        },
        "grant_type": {
            "type": "string",
            "default": "client_credentials"
        }
    },
    "required": [
        "client_id",
        "client_secret"
    ]
}

Response 200 OK

application/json

{
    "access_token": "string",
    "token_type": "string",
    "expires_in": 0
}

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

Schema of the response body

{
    "type": "object",
    "properties": {
        "access_token": {
            "type": "string"
        },
        "token_type": {
            "type": "string"
        },
        "expires_in": {
            "type": "integer"
        }
    }
}

Response 400 Bad Request

application/json

{
    "error": "string"
}

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

Schema of the response body

{
    "type": "object",
    "properties": {
        "error": {
            "type": "string"
        }
    }
}

Schemas¶

ActionRequiredDto¶

Name	Type
`payment_data`	string
`session_id`	string
`token`	string
`transaction_id`	string
`type`	string

BrowserInfo¶

Name	Type
`accept_header`	string
`color_depth`	integer
`java_enabled`	boolean
`language`	string
`screen_height`	integer
`screen_width`	integer
`time_zone_offset`	integer
`user_agent`	string

CardPaymentData¶

Name	Type
`encrypted_card_number`	string
`encrypted_cvv`	string
`encrypted_expiration_month`	string
`encrypted_expiration_year`	string

CustomerDto¶

Name	Type
`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
`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

SavedCardPaymentData¶

Name	Type
`encrypted_cvv`	string
`payment_method_id`	string

TokenizationDto¶

Name	Type
`save_card_for_future_payments`	boolean

TransactionExecuteRequestDto¶

Name	Type
`amount`	integer(int64)
`browser_info`	BrowserInfo
`cancel_url`	string
`currency`	string
`customer`	CustomerDto
`description`	string
`error_url`	string
`metadata`
`payment_method`	Properties: `type, data`
`reference`	string
`return_url`	string
`terminal_id`	string
`tokenization`	TokenizationDto
`transaction_type`	string

TransactionStatus¶

Type: string

Security schemes¶

Name	Type	Scheme	Description
bearerAuth	http	bearer