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"
```json
{
"reference": "string",
"terminal_id": "string",
"description": "string",
"currency": "EUR",
"amount": 252,
"transaction_type": "AUTHORIZE",
"payment_method": {
"type": "card",
"data": {
"encrypted_card_number": "string",
"encrypted_cvv": "string",
"encrypted_expiration_month": "string",
"encrypted_expiration_year": "string"
}
},
"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"
}
```
<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",
"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 (e.g., card)."
},
"data": {
"type": "object",
"description": "Encrypted card details. **Important:** These fields must be encrypted using your public key.\n",
"properties": {
"encrypted_card_number": {
"type": "string",
"description": "Encrypted card number."
},
"encrypted_cvv": {
"type": "string",
"description": "Encrypted CVV."
},
"encrypted_expiration_month": {
"type": "string",
"description": "Encrypted expiration month."
},
"encrypted_expiration_year": {
"type": "string",
"description": "Encrypted expiration year."
}
},
"required": [
"encrypted_card_number",
"encrypted_cvv",
"encrypted_expiration_month",
"encrypted_expiration_year"
]
}
},
"required": [
"type",
"data"
]
},
"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"
```json
{
"result": null,
"action": null,
"redirect": {
"transaction_id": "vvIVFmPuwYosePLsoDsW",
"session_id": "vvIVFmPuwYosePLsoDsW",
"url": "https://redirect-domain-example.com"
},
"form_submit": null
}
```
```json
{
"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
}
```
```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": "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
}
```
??? 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"
}
}
}
```
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"
```json
{
"client_id": "string",
"client_secret": "string",
"grant_type": "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": {
"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"
```json
{
"access_token": "string",
"token_type": "string",
"expires_in": 0
}
```
<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 response body"
```json
{
"type": "object",
"properties": {
"access_token": {
"type": "string"
},
"token_type": {
"type": "string"
},
"expires_in": {
"type": "integer"
}
}
}
```
Response 400 Bad Request
=== "application/json"
```json
{
"error": "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 response body"
```json
{
"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 |
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 |
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 |
transaction_type |
string |
TransactionStatus¶
Type: string
Security schemes¶
| Name | Type | Scheme | Description |
|---|---|---|---|
| bearerAuth | http | bearer |