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": 47,
"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 (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",
"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"
]
}
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 | Recipient's street address. |
city |
string | Recipient's city. |
country |
string | ISO 3166-1 alpha-2 country code. |
email |
string | Recipient's email address. |
first_name |
string | Recipient's first name. |
id |
string | null | Optional merchant-assigned customer identifier. |
last_name |
string | Recipient's last name. |
phone |
string | Recipient's phone number in E.164 format. |
postal_code |
string | Recipient's postal / ZIP code. |
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 | null | Customer's IP address (IPv4 or IPv6). Optional. If 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. |
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 |