Capture API

Copy page

Copy page as Markdown for LLMs

Open in ChatGPT

Ask questions about this page

Open in Claude

Ask questions about this page

The capture operation allows merchants to capture previously authorized amounts to their account. Captures can be partial or full, depending on merchant requirements.

Captures must be processed within 7 days of the authorization date

API Endpoints

https://sbpaymentservices.payfort.com/FortAPI/paymentApi

https://paymentservices.payfort.com/FortAPI/paymentApi

Request Format

• Method: POST
• Content-Type: application/json
• Submission: Server-to-server HTTPS POST

Request Parameters

Parameter
command   String Max: 20 Required Operation command for capture request. Value: CAPTURE Example. CAPTURE
access_code   String Max: 20 Required Merchant access code obtained from Amazon Payment Services dashboard under Integration Settings → Security Settings. Example. zx0IPmPy5jp1vAz8Kpg7
merchant_identifier   String Max: 20 Required Unique merchant identifier assigned by Amazon Payment Services during account setup. Example. CycHZxVj
merchant_reference   String Max: 40 Required Unique order reference that must be unique per merchant. Alphanumeric characters, hyphens (-), underscores (_), and periods (.) allowed. Example. XYZ9239-yu898
amount   Integer Max: 10 Required Transaction amount in smallest currency unit (no decimal points). For AED: multiply by 100 (1.00 AED = 100), for USD: multiply by 100 (1.00 USD = 100), for KWD: multiply by 1000 (1.000 KWD = 1000). Example. 10000
currency   String Max: 3 Required Three-letter ISO 4217 currency code. Example. AED
language   String Max: 2 Required Response language for error messages and transaction descriptions. Values: en, ar Example. en
signature   String Max: 200 Required SHA-256 HMAC signature calculated using your secret key and request parameters for authentication and integrity validation. Example. 7cad05f0212ed933c9a5d5dffa31661acf2c827a
fort_id   Integer Max: 20 Optional Unique transaction reference generated by Amazon Payment Services. Example. 149295435400084008
order_description   String Max: 150 Optional Descriptive text about the purchase that appears in transaction records and may be shown to customers. Example. Premium Subscription - 12 months

Multiply your capture amount by the currency decimal code per ISO code 3 before sending the amount parameter. For currencies with three-decimal codes, round VISA transactions to zero in the final decimal place to avoid declined transactions. Example: For 500 AED (2 decimal places per ISO code 3), multiply by 100 to send 50000 in your request.

You can send merchant_reference and/or fort_id in the capture request to identify the original authorization. At least one of these parameters is required.

Check signature calculation section to learn how to calculate the signature.

Sample Request

{
  "command": "CAPTURE",
  "access_code": "zx0IPmPy5jp1vAz8Kpg7",
  "merchant_identifier": "CycHZxVj",
  "merchant_reference": "XYZ9239-yu898",
  "amount": 10000,
  "currency": "AED",
  "language": "en",
  "fort_id": "149295435400084008",
  "signature": "7cad05f0212ed933c9a5d5dffa31661acf2c827a",
  "order_description": "iPhone 6-S - Full Capture"
}

import requests

# Capture request data
capture_data = {
    "command": "CAPTURE",
    "access_code": "zx0IPmPy5jp1vAz8Kpg7",
    "merchant_identifier": "CycHZxVj",
    "merchant_reference": "XYZ9239-yu898",
    "amount": "10000",
    "currency": "AED",
    "language": "en",
    "fort_id": "149295435400084008",
    "signature": "7cad05f0212ed933c9a5d5dffa31661acf2c827a",
    "order_description": "iPhone 6-S - Full Capture"
}

# Send capture request
response = requests.post(
    "https://sbpaymentservices.payfort.com/FortAPI/paymentApi",
    json=capture_data,
    headers={"Content-Type": "application/json"}
)

result = response.json()

<?php
// Capture request data
$captureData = [
    'command' => 'CAPTURE',
    'access_code' => 'zx0IPmPy5jp1vAz8Kpg7',
    'merchant_identifier' => 'CycHZxVj',
    'merchant_reference' => 'XYZ9239-yu898',
    'amount' => '10000',
    'currency' => 'AED',
    'language' => 'en',
    'fort_id' => '149295435400084008',
    'signature' => '7cad05f0212ed933c9a5d5dffa31661acf2c827a',
    'order_description' => 'iPhone 6-S - Full Capture'
];

// Send capture request
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'https://sbpaymentservices.payfort.com/FortAPI/paymentApi');
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($captureData));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Content-Type: application/json']);

$response = curl_exec($ch);
curl_close($ch);

$result = json_decode($response, true);
?>

// Capture request data
const captureData = {
  command: "CAPTURE",
  access_code: "zx0IPmPy5jp1vAz8Kpg7",
  merchant_identifier: "CycHZxVj",
  merchant_reference: "XYZ9239-yu898",
  amount: "10000",
  currency: "AED",
  language: "en",
  fort_id: "149295435400084008",
  signature: "7cad05f0212ed933c9a5d5dffa31661acf2c827a",
  order_description: "iPhone 6-S - Full Capture"
};

// Send capture request
const response = await fetch("https://sbpaymentservices.payfort.com/FortAPI/paymentApi", {
  method: "POST",
  headers: {
    "Content-Type": "application/json"
  },
  body: JSON.stringify(captureData)
});

const result = await response.json();

curl -X POST https://sbpaymentservices.payfort.com/FortAPI/paymentApi \
  -H "Content-Type: application/json" \
  -d '{
    "command": "CAPTURE",
    "access_code": "zx0IPmPy5jp1vAz8Kpg7",
    "merchant_identifier": "CycHZxVj",
    "merchant_reference": "XYZ9239-yu898",
    "amount": "10000",
    "currency": "AED",
    "language": "en",
    "fort_id": "149295435400084008",
    "signature": "7cad05f0212ed933c9a5d5dffa31661acf2c827a",
    "order_description": "iPhone 6-S - Full Capture"
  }'

Sample Response

{
  "command": "CAPTURE",
  "access_code": "zx0IPmPy5jp1vAz8Kpg7",
  "merchant_identifier": "CycHZxVj",
  "merchant_reference": "XYZ9239-yu898",
  "amount": 10000,
  "currency": "AED",
  "language": "en",
  "fort_id": "149295435400084008",
  "signature": "7cad05f0212ed933c9a5d5dffa31661acf2c827a",
  "order_description": "iPhone 6-S - Full Capture",
  "response_message": "Success",
  "response_code": "20064",
  "status": "04"
}

Response Parameters

Parameter
command   String Max: 20 Operation command from the request. Value: CAPTURE Example. CAPTURE
access_code   String Max: 20 Merchant access code used in the request. Example. zx0IPmPy5jp1vAz8Kpg7
merchant_identifier   String Max: 20 Merchant identifier used in the request. Example. CycHZxVj
merchant_reference   String Max: 40 Unique order reference from the request. Example. XYZ9239-yu898
amount   Integer Max: 10 Transaction amount processed. Example. 10000
currency   String Max: 3 Currency code used for the transaction. Example. AED
language   String Max: 2 Language used for the response. Example. en
signature   String Max: 200 Response signature for verification. Example. 7cad05f0212ed933c9a5d5dffa31661acf2c827a
fort_id   Integer Max: 20 Unique transaction reference generated by Amazon Payment Services. Example. 149295435400084008
order_description   String Max: 150 Order description from the request. Example. Premium Subscription - 12 months
response_message   String Max: 150 Human-readable response description in requested language. Example. Success
response_code   Integer Max: 5 Numeric response code indicating transaction result. Example. 20064
status   Integer Max: 2 Two-digit status code indicating transaction state. Example. 20

Response Codes

The response of capture will be returned to your configured notification URL. For a complete list of response codes and their descriptions, please refer to our Error Codes Documentation.

Testing The Integration

Use the sandbox environment for development and testing:

• Sandbox URL: https://sbpaymentservices.payfort.com/FortAPI/paymentApi
• Test Scenarios: Test both full and partial captures with various amounts
• Test Cards: Use our comprehensive Testing Cards

Go-Live Process

When ready to move to production, follow our Go-Live checklist

If you prefer using your account dashboard, you can capture payments by navigating to the "Order Transaction Management" tab. For more information, see our capturing payment guide.