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": 281,
"transaction_type": "OCT",
"payment_method": {
"type": "card",
"data": {
"encrypted_card_number": "string"
}
},
"customer": {
"first_name": "string",
"last_name": "string",
"address": "string",
"city": "string",
"country": "string",
"postal_code": "string",
"email": "string",
"phone": "string",
"id": "string"
},
"metadata": {},
"customer_ip": "192.168.1.1"
}
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 (e.g., 100 = 1.00 EUR)."
},
"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",
"description": "Customer IP address.",
"example": "192.168.1.1"
}
},
"required": [
"reference",
"terminal_id",
"description",
"currency",
"amount",
"transaction_type",
"payment_method",
"customer"
]
}
Responses
{
"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."
}
{
"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"
}
}
}
{
"error": "Unauthorized"
}
Schema of the response body
{
"type": "object",
"properties": {
"error": {
"type": "string"
}
}
}
Schemas¶
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 |
Always null for OCT transactions (no 3DS authentication required). | |
form_submit |
Always null for OCT transactions (no form submission required). | |
redirect |
Always null for OCT transactions (no redirect required). | |
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 | null | |
reference |
string | |
status |
TransactionStatus | |
terminal_id |
string | |
transaction_type |
string |
OctCardPaymentData¶
| Name | Type | Description |
|---|---|---|
encrypted_card_number |
string | Encrypted card number of the recipient. Must be encrypted using your merchant public key. |
OctTransactionRequestDto¶
| Name | Type | Description |
|---|---|---|
amount |
integer(int64) | Transaction amount in minor units (e.g., 100 = 1.00 EUR). |
currency |
string | Currency code (e.g., EUR). |
customer |
CustomerDto | |
customer_ip |
string | Customer IP address. |
description |
string | Transaction description. |
metadata |
Additional metadata for the transaction. | |
payment_method |
Properties: type, data |
|
reference |
string | Unique transaction reference. |
terminal_id |
string | Terminal identifier. The terminal must be configured to support OCT transactions. |
transaction_type |
string | Must be `OCT` for Original Credit Transactions. |
PaymentMethodDataDto¶
| Name | Type | Description |
|---|---|---|
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 |