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
{
"reference": "string",
"terminal_id": "string",
"description": "string",
"currency": "EUR",
"amount": 41,
"transaction_type": "AUTHORIZE",
"payment_method": {
"type": "card",
"data": null
},
"tokenization": {
"save_card_for_future_payments": true,
"tokenize_for": "CUSTOMER_INITIATED_TRANSACTION"
},
"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",
"customer_ip": "203.0.113.42"
}
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, as an integer (e.g., `10000` = 100.00). Decimal or fractional values such as `100.00` or `\"100.00\"` are rejected at request validation."
},
"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)."
},
"error_url": {
"type": "string",
"nullable": true,
"description": "URL to redirect the customer to after a failed (declined, invalid, or expired) transaction. Optional.\n\nIf omitted, the customer is redirected to `return_url` regardless of the outcome — use the transaction status API or webhooks to determine the final result.\n"
},
"cancel_url": {
"type": "string",
"nullable": true,
"description": "URL to redirect the customer to after a canceled transaction. Optional.\n\nIf omitted, the customer is redirected to `return_url` regardless of the outcome — use the transaction status API or webhooks to determine the final result.\n"
},
"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"
]
}
Response 200 OK
{
"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 Entity
{
"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 |
|---|---|
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 |
NetworkTokenPaymentData¶
| Name | Type |
|---|---|
eci |
string |
encrypted_cryptogram |
string| null |
encrypted_expiration_month |
string |
encrypted_expiration_year |
string |
encrypted_token_number |
string |
source |
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 |
tokenize_for |
string| null |
TransactionExecuteRequestDto¶
| Name | Type |
|---|---|
amount |
integer(int64) |
browser_info |
BrowserInfo |
cancel_url |
string| null |
currency |
string |
customer |
CustomerDto |
customer_ip |
string| null |
description |
string |
error_url |
string| null |
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 |