Currency Conversion 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 Currency Conversion service allows merchants to dynamically convert transaction amounts from one currency to another using real-time exchange rates. This service enables you to display prices in your customer's local currency, improving the shopping experience and reducing cart abandonment due to currency confusion.

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

Currency conversion uses real-time exchange rates that are updated frequently throughout the day. Rates may vary between conversion requests based on market conditions.

Request Parameters

Parameter
service_command   String Max: 20 Required Service command for currency conversion request. Value: CURRENCY_CONVERSION Example. CURRENCY_CONVERSION
access_code   String Max: 20 Required Merchant access code obtained from Amazon Payment Services dashboard under Integration Settings. Example. zx0IPmPy5jp1vAz
merchant_identifier   String Max: 20 Required Unique merchant identifier assigned by Amazon Payment Services during account setup. Example. CycHZxVj
amount   Integer Max: 10 Required Amount to be converted in smallest currency unit (e.g., fils for AED, cents for USD). Must be positive integer. Example. 10000
currency   String Max: 3 Required Three-letter ISO 4217 currency code of the source amount. Example. USD
converted_currency   String Max: 3 Required Three-letter ISO 4217 currency code for the target conversion currency. Example. AED
language   String Max: 2 Required Response language for messages and descriptions. Supported values: en (English) or ar (Arabic). Example. en
signature   String Max: 200 Required SHA-256 hash signature for request authentication and integrity validation. Example. 7cad05f0212ed933c9a5d5dffa31661acf2c827a

Multiply your transaction 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 100.00 USD (2 decimal places per ISO code 3), multiply by 100 to send 10000 in your request.

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

Response Parameters

Parameter
service_command   String Max: 20 Service command from the request. Value: CURRENCY_CONVERSION Example. CURRENCY_CONVERSION
access_code   String Max: 20 Merchant access code used in the request. Example. zx0IPmPy5jp1vAz
merchant_identifier   String Max: 20 Merchant identifier used in the request. Example. CycHZxVj
amount   Integer Max: 10 Original amount from the request. Example. 10000
currency   String Max: 3 Source currency code from the request. Example. USD
converted_currency   String Max: 3 Target currency code from the request. Example. AED
language   String Max: 2 Language used for the response. Example. en
signature   String Max: 200 Response signature for verification. Example. 7cad05f0212ed933c9a5d5dffa31661acf2c827a
converted_amount   String Max: 20 Converted amount in the target currency using current exchange rates. Example. 36729.8
conversion_number   String Max: 20 Unique conversion reference generated by Amazon Payment Services for tracking purposes. Example. 1443796866848
response_message   String Max: 150 Human-readable response description in requested language. Example. Success
response_code   String Max: 5 Numeric response code indicating conversion result. Example. 42000
status   String Max: 2 Two-digit status code indicating conversion state. Example. 20

Response Codes

For a complete list of response codes and their descriptions, please refer to our Error Codes Documentation.

Sample Request

{
  "service_command": "CURRENCY_CONVERSION",
  "access_code": "DyGkTj68aMuexd2geu2j",
  "merchant_identifier": "bYqNmale",
  "amount": 10000,
  "currency": "USD",
  "language": "en",
  "converted_currency": "AED",
  "signature": "7cad05f0212ed933c9a5d5dffa31661acf2c827a"
}

import hashlib
import json
import requests
from urllib.parse import urlencode

class APSCurrencyConverter:
    def __init__(self, access_code, merchant_identifier, sha_request_phrase, sha_response_phrase, sandbox=True):
        self.access_code = access_code
        self.merchant_identifier = merchant_identifier
        self.sha_request_phrase = sha_request_phrase
        self.sha_response_phrase = sha_response_phrase
        self.base_url = "https://sbpaymentservices.PayFort.com" if sandbox else "https://paymentservices.PayFort.com"
    
    def calculate_signature(self, parameters, phrase):
        """Calculate SHA256 signature for request parameters"""
        filtered_params = {k: v for k, v in parameters.items() if v is not None and v != ''}
        sorted_params = dict(sorted(filtered_params.items()))
        query_string = urlencode(sorted_params, safe='')
        signature_string = f"{phrase}{query_string}{phrase}"
        return hashlib.sha256(signature_string.encode('utf-8')).hexdigest()
    
    def convert_currency(self, amount, from_currency, to_currency, language='en'):
        """
        Convert currency using APS currency conversion service
        
        Args:
            amount (int): Amount in smallest currency unit
            from_currency (str): Source currency ISO code
            to_currency (str): Target currency ISO code  
            language (str): Response language ('en' or 'ar')
            
        Returns:
            dict: API response with converted amount
        """
        params = {
            'service_command': 'CURRENCY_CONVERSION',
            'access_code': self.access_code,
            'merchant_identifier': self.merchant_identifier,
            'amount': str(amount),
            'currency': from_currency,
            'converted_currency': to_currency,
            'language': language
        }
        
        # Calculate signature
        params['signature'] = self.calculate_signature(params, self.sha_request_phrase)
        
        try:
            response = requests.post(
                f"{self.base_url}/FortAPI/paymentApi",
                json=params,
                headers={'Content-Type': 'application/json'},
                timeout=30
            )
            response.raise_for_status()
            return response.json()
        except requests.exceptions.RequestException as e:
            return {'success': False, 'error': f'Request failed: {str(e)}'}
        except Exception as e:
            return {'success': False, 'error': str(e)}
    
    def validate_response_signature(self, response_params):
        """Validate response signature for security"""
        if 'signature' not in response_params:
            return False
        
        response_copy = response_params.copy()
        received_signature = response_copy.pop('signature')
        calculated_signature = self.calculate_signature(response_copy, self.sha_response_phrase)
        return received_signature == calculated_signature

# Usage example
converter = APSCurrencyConverter(
    access_code="DyGkTj68aMuexd2geu2j",
    merchant_identifier="bYqNmale",
    sha_request_phrase="your_sha_request_phrase",
    sha_response_phrase="your_sha_response_phrase",
    sandbox=True
)

# Convert 100.00 USD to AED
response = converter.convert_currency(
    amount=10000,  # 100.00 USD in cents
    from_currency="USD",
    to_currency="AED"
)

if response.get('response_code') == '42000':
    converted_amount = float(response['converted_amount']) / 100  # Convert back to decimal
    print(f"Converted amount: {converted_amount} AED")
else:
    print(f"Conversion failed: {response.get('response_message', 'Unknown error')}")

<?php

class APSCurrencyConverter {
    private $accessCode;
    private $merchantIdentifier;
    private $shaRequestPhrase;
    private $shaResponsePhrase;
    private $baseUrl;
    
    public function __construct($accessCode, $merchantIdentifier, $shaRequestPhrase, $shaResponsePhrase, $sandbox = true) {
        $this->accessCode = $accessCode;
        $this->merchantIdentifier = $merchantIdentifier;
        $this->shaRequestPhrase = $shaRequestPhrase;
        $this->shaResponsePhrase = $shaResponsePhrase;
        $this->baseUrl = $sandbox ? 'https://sbpaymentservices.PayFort.com' : 'https://paymentservices.PayFort.com';
    }
    
    public function calculateSignature($parameters, $phrase) {
        $filteredParams = array_filter($parameters, function($value) {
            return $value !== null && $value !== '';
        });
        
        ksort($filteredParams);
        $queryString = http_build_query($filteredParams, '', '&', PHP_QUERY_RFC3986);
        $signatureString = $phrase . $queryString . $phrase;
        
        return hash('sha256', $signatureString);
    }
    
    public function convertCurrency($amount, $fromCurrency, $toCurrency, $language = 'en') {
        $params = [
            'service_command' => 'CURRENCY_CONVERSION',
            'access_code' => $this->accessCode,
            'merchant_identifier' => $this->merchantIdentifier,
            'amount' => (string)$amount,
            'currency' => $fromCurrency,
            'converted_currency' => $toCurrency,
            'language' => $language
        ];
        
        // Calculate signature
        $params['signature'] = $this->calculateSignature($params, $this->shaRequestPhrase);
        
        // Make API request
        $ch = curl_init();
        curl_setopt($ch, CURLOPT_URL, $this->baseUrl . '/FortAPI/paymentApi');
        curl_setopt($ch, CURLOPT_POST, true);
        curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($params));
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($ch, CURLOPT_HTTPHEADER, [
            'Content-Type: application/json',
            'Content-Length: ' . strlen(json_encode($params))
        ]);
        curl_setopt($ch, CURLOPT_TIMEOUT, 30);
        curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, true);
        
        $response = curl_exec($ch);
        $httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
        $error = curl_error($ch);
        curl_close($ch);
        
        if ($error) {
            return ['success' => false, 'error' => 'cURL Error: ' . $error];
        }
        
        if ($httpCode === 200) {
            return json_decode($response, true);
        } else {
            return ['success' => false, 'error' => 'HTTP Error: ' . $httpCode];
        }
    }
    
    public function validateResponseSignature($responseParams) {
        if (!isset($responseParams['signature'])) {
            return false;
        }
        
        $responseCopy = $responseParams;
        $receivedSignature = $responseCopy['signature'];
        unset($responseCopy['signature']);
        
        $calculatedSignature = $this->calculateSignature($responseCopy, $this->shaResponsePhrase);
        return $receivedSignature === $calculatedSignature;
    }
}

// Usage example
$converter = new APSCurrencyConverter(
    'DyGkTj68aMuexd2geu2j',
    'bYqNmale',
    'your_sha_request_phrase',
    'your_sha_response_phrase',
    true // sandbox
);

// Convert 100.00 USD to AED
$response = $converter->convertCurrency(
    10000, // 100.00 USD in cents
    'USD',
    'AED'
);

if ($response['response_code'] === '42000') {
    $convertedAmount = floatval($response['converted_amount']) / 100; // Convert back to decimal
    echo "Converted amount: {$convertedAmount} AED\n";
} else {
    echo "Conversion failed: " . ($response['response_message'] ?? 'Unknown error') . "\n";
}
?>

# Currency conversion request using cURL

curl -X POST https://sbpaymentservices.PayFort.com/FortAPI/paymentApi \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "service_command": "CURRENCY_CONVERSION",
    "access_code": "DyGkTj68aMuexd2geu2j",
    "merchant_identifier": "bYqNmale",
    "amount": 10000,
    "currency": "USD",
    "language": "en",
    "converted_currency": "AED",
    "signature": "7cad05f0212ed933c9a5d5dffa31661acf2c827a"
  }'

# Example with error handling
#!/bin/bash

# Currency conversion with error handling
response=$(curl -s -X POST https://sbpaymentservices.PayFort.com/FortAPI/paymentApi \
  -H "Content-Type: application/json" \
  -w "HTTPSTATUS:%{http_code}" \
  -d '{
    "service_command": "CURRENCY_CONVERSION",
    "access_code": "DyGkTj68aMuexd2geu2j",
    "merchant_identifier": "bYqNmale",
    "amount": 10000,
    "currency": "USD",
    "language": "en",
    "converted_currency": "AED",
    "signature": "7cad05f0212ed933c9a5d5dffa31661acf2c827a"
  }')

# Extract HTTP status code
http_code=$(echo "$response" | tr -d '\n' | sed -e 's/.*HTTPSTATUS://')
# Extract response body
response_body=$(echo "$response" | sed -e 's/HTTPSTATUS\:.*//g')

if [ "$http_code" -eq 200 ]; then
    echo "Currency conversion successful:"
    echo "$response_body" | jq '.'
else
    echo "Currency conversion failed with HTTP code: $http_code"
    echo "$response_body"
fi

{
  "service_command": "CURRENCY_CONVERSION",
  "access_code": "DyGkTj68aMuexd2geu2j",
  "merchant_identifier": "bYqNmale",
  "amount": 10000,
  "currency": "USD",
  "language": "en",
  "signature": "c63a266e5929c6c8b82c2d9f2c8ae5c2b1b6f8a9d7e4f3c2a1b0c9d8e7f6a5b4",
  "response_message": "Success",
  "response_code": "42000",
  "status": "20",
  "converted_amount": "36729.8",
  "converted_currency": "AED",
  "conversion_number": "1443796866848"
}

Testing The Integration

Sandbox Testing

Use the sandbox environment for development and testing:

• Sandbox URL: https://sbpaymentservices.PayFort.com/FortAPI/paymentApi

Go-Live Process

Follow our Go-Live checklist for complete production readiness guidelines.