OCT Authorize¶
Payment Gateway API - OCT 1.0.0¶
This API processes Original Credit Transactions (OCT) — push payments that send funds directly to a cardholder's card.
Access Token: Obtain an access token via OpenID Connect using your client credentials (client_id and client_secret are available in your merchant dashboard). See the Authentication guide for details.
Process OCT Transaction: The /api/transactions/authorize endpoint
processes an OCT transaction and returns detailed response data.
Important: This endpoint requires an Authorization header with a valid
Bearer token. The card number 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"
encrypt_field() {
echo -n "$1" | openssl rsautl -encrypt -pubin -inkey <(echo "$PUBLIC_KEY") |
base64
}
ENCRYPTED_CARD_NUMBER=$(encrypt_field "$CARD_NUMBER")
echo "Encrypted Card Number: $ENCRYPTED_CARD_NUMBER"
Note: Unlike standard card transactions, OCT only requires the encrypted card number. CVV and expiration date are not needed.
Servers¶
| Description | URL |
|---|---|
| https://api.example.com | https://api.example.com |
Endpoints¶
POST /api/transactions/authorize¶
Execute OCT Transaction
Description
Execute an Original Credit Transaction (OCT) to send funds to a cardholder's card.
Requirements:
- An Authorization header with a valid Bearer token is required.
- The card number must be encrypted using your public key. See the
encryption example above.
- The transaction_type must be set to OCT.
- Only card payment method type is supported.
Key differences from standard card authorization:
- Only encrypted_card_number is required (no CVV, expiration date).
- No 3D Secure authentication — the action, redirect, and form_submit
fields in the response will always be null.
- browser_info is not required in the request.
Input parameters
| Parameter | In | Type | Default | Nullable | Description |
|---|---|---|---|---|---|
bearerAuth |
header | string | N/A | No | JWT Bearer token |
Request body
{
"reference": "string",
"terminal_id": "string",
"description": "string",
"currency": "EUR",
"amount": 148,
"transaction_type": "OCT",
"payment_method": {
"type": "card",
"data": {
"encrypted_card_number": "string"
}
},
"customer": {
"first_name": "John",
"last_name": "Doe",
"email": "john.doe@example.com",
"phone": "+1234567890",
"address": "123 Example Street",
"city": "Sampletown",
"country": "BA",
"postal_code": "12345",
"id": "string"
},
"metadata": {},
"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. The terminal must be configured to support OCT transactions.",
"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": [
"OCT"
],
"description": "Must be `OCT` for Original Credit Transactions."
},
"payment_method": {
"type": "object",
"properties": {
"type": {
"type": "string",
"enum": [
"card"
],
"example": "card",
"description": "Payment method type. Only `card` is supported for OCT."
},
"data": {
"$ref": "#/components/schemas/OctCardPaymentData"
}
},
"required": [
"type",
"data"
]
},
"customer": {
"$ref": "#/components/schemas/CustomerDto"
},
"metadata": {
"type": "object",
"additionalProperties": true,
"description": "Additional metadata for the transaction."
},
"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 provider 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"
]
}
Response 200 OK
{
"result": {
"id": "OcTxAbCdEfGhIjKlMnOp",
"merchant_id": "0000000000000fpg-dev",
"order_id": "ORD_OCT_20260313_001",
"terminal_id": "TERM001",
"reference": "PAYOUT-123456",
"description": "Payout to customer card",
"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": null
},
"processing_result": {
"payment_provider_id": "PP_ABC123",
"payment_provider_account_id": "PPACCT_XYZ789",
"approval_code": "AUTH456",
"reference_number": "REF_OCT_001"
},
"approved": true,
"pending": false,
"channel": "ecommerce",
"transaction_type": "OCT",
"status": "APPROVED",
"payment_method": {
"method": "411111-******-1111",
"hash": null,
"type": "card",
"brand": "VISA",
"masked": "411111-******-1111",
"token": null
},
"redirect_url": null,
"normalized_amount": 10000,
"errors": []
},
"action": null,
"redirect": null,
"form_submit": null
}
{
"result": {
"id": "OcTxQrStUvWxYzAbCdEf",
"merchant_id": "0000000000000fpg-dev",
"order_id": "ORD_OCT_20260313_002",
"terminal_id": "TERM001",
"reference": "PAYOUT-789012",
"description": "Payout to customer card",
"currency": "EUR",
"amount": 5000,
"customer": {
"first_name": "Jane",
"last_name": "Smith",
"address": "456 Test Avenue",
"city": "Testville",
"country": "DE",
"postal_code": "54321",
"email": "jane.smith@example.com",
"phone": "+0987654321",
"id": null
},
"processing_result": {
"payment_provider_id": "PP_DEF456",
"payment_provider_account_id": "PPACCT_UVW321",
"approval_code": null,
"reference_number": null
},
"approved": false,
"pending": false,
"channel": "ecommerce",
"transaction_type": "OCT",
"status": "DECLINED",
"payment_method": {
"method": "424242-******-4242",
"hash": null,
"type": "card",
"brand": "VISA",
"masked": "424242-******-4242",
"token": null
},
"redirect_url": null,
"normalized_amount": 5000,
"errors": []
},
"action": null,
"redirect": null,
"form_submit": null
}
{
"result": {
"id": "OcTxPeNdInGhIjKlMnOp",
"merchant_id": "0000000000000fpg-dev",
"order_id": "ORD_OCT_20260313_003",
"terminal_id": "TERM001",
"reference": "PAYOUT-345678",
"description": "Disbursement payment",
"currency": "USD",
"amount": 25000,
"customer": {
"first_name": "Alex",
"last_name": "Johnson",
"address": "789 Main Road",
"city": "Capital City",
"country": "US",
"postal_code": "10001",
"email": "alex.johnson@example.com",
"phone": "+1555123456",
"id": "CUST789"
},
"processing_result": {
"payment_provider_id": "PP_GHI789",
"payment_provider_account_id": "PPACCT_ABC654",
"approval_code": null,
"reference_number": "REF_OCT_003"
},
"approved": false,
"pending": true,
"channel": "ecommerce",
"transaction_type": "OCT",
"status": "PENDING",
"payment_method": {
"method": "555555-******-4444",
"hash": null,
"type": "card",
"brand": "MASTERCARD",
"masked": "555555-******-4444",
"token": null
},
"redirect_url": null,
"normalized_amount": 25000,
"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": {
"type": "object",
"nullable": true,
"description": "Always null for OCT transactions (no 3DS authentication required)."
},
"redirect": {
"type": "object",
"nullable": true,
"description": "Always null for OCT transactions (no redirect required)."
},
"form_submit": {
"type": "object",
"nullable": true,
"description": "Always null for OCT transactions (no form submission required)."
}
},
"description": "Response payload for an OCT 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"
}
}
}
Response 401 Unauthorized
{
"error": "Unauthorized"
}
Schema of the response body
{
"type": "object",
"properties": {
"error": {
"type": "string"
}
}
}
Schemas¶
CustomerDto¶
| Name | Type |
|---|---|
address |
string |
city |
string |
country |
string |
email |
string |
first_name |
string |
id |
string| null |
last_name |
string |
phone |
string |
postal_code |
string |
ExecuteTransactionResponseDto¶
| Name | Type |
|---|---|
action |
|
form_submit |
|
redirect |
|
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| null |
reference |
string |
status |
TransactionStatus |
terminal_id |
string |
transaction_type |
string |
OctCardPaymentData¶
| Name | Type |
|---|---|
encrypted_card_number |
string |
OctTransactionRequestDto¶
| Name | Type |
|---|---|
amount |
integer(int64) |
currency |
string |
customer |
CustomerDto |
customer_ip |
string| null |
description |
string |
metadata |
|
payment_method |
Properties: type, data |
reference |
string |
terminal_id |
string |
transaction_type |
string |
PaymentMethodDataDto¶
| Name | Type |
|---|---|
brand |
string |
hash |
string| null |
masked |
string |
method |
string |
token |
string| null |
type |
string |
ProcessingResultDto¶
TransactionStatus¶
Type: string
Security schemes¶
| Name | Type | Scheme | Description |
|---|---|---|---|
| bearerAuth | http | bearer |