ValU

Copy page

Copy page as Markdown for LLMs

Open in ChatGPT

Ask questions about this page

Open in Claude

Ask questions about this page

ValU consumer finance is a simple and secure financing platform where your customers can do online purchases on short-term financing and repay the amount based on specific installment plans at an interest rate offered by the financing company. For now, we have partnered with ValU in Egypt to offer consumer financing services.

We support ValU in Egypt. Ensure your merchant account is configured for the Egyptian market before integration.

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

Before Starting

Before you start, remember:

• Your customer should be registered with ValU in order to have this benefit of installments.
• You should have a valid SHA signature, to configure signatures, refer to Signature and Signature Calculation Tool.
• To fetch your merchant reference and merchant access code, go to Merchant Management, search and select the test merchant account and click Security Settings.

Multiply your transaction amount by the currency decimal code per ISO code 3 before sending the amount parameter. Example: For 100 EGP (2 decimal places per ISO code 3), multiply by 100 to send 10000 in your request.

The merchant_reference must be unique per transaction and should be the same for all ValU APIs.

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

Customer Verify

This request allows the Merchant to identify whether the customer is a ValU registered customer or not; by verifying the Customer's phone number.

Request Parameters

Parameter
service_command   String Max: 20 Required Service command for customer verification. Value: CUSTOMER_VERIFY Example. CUSTOMER_VERIFY
access_code   String Max: 20 Required Merchant access code obtained from Amazon Payment Services dashboard under Integration 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. The merchant reference should be the same for all APIs. Alphanumeric characters, hyphens, underscores, and periods allowed. Example. XYZ9239-yu898
language   String Max: 2 Required Response language. Supported values: en (English) or ar (Arabic). Example. en
payment_option   String Max: 10 Required Payment option for ValU transactions. Value: VALU Example. VALU
phone_number   String Max: 19 Required Customer's phone number registered with ValU for verification. Example. 00008557694
signature   String Max: 200 Required SHA-256 hash signature for request authentication and integrity validation. Example. 7cad05f0212ed933c9a5d5dffa31661acf2c827a

Response Parameters

Parameter
service_command   String Max: 20 Service command from the request. Value: CUSTOMER_VERIFY Example. CUSTOMER_VERIFY
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
language   String Max: 2 Language used for the response. Example. en
payment_option   String Max: 10 Payment option used. Value: VALU Example. VALU
phone_number   String Max: 19 Customer's phone number from the request. Example. 00008557694
signature   String Max: 200 Response signature for verification. Example. 7cad05f0212ed933c9a5d5dffa31661acf2c827a
response_message   String Max: 150 Human-readable response description in requested language. Example. Success
response_code   String Max: 5 Numeric response code indicating verification result. Example. 88000
status   String Max: 2 Two-digit status code indicating verification state. Example. 88

Customer Verify Sample Request

{
  "service_command": "CUSTOMER_VERIFY",
  "merchant_reference": "XYZ9239-yu898",
  "merchant_identifier": "CycHZxVj",
  "access_code": "zx0IPmPy5jp1vAz8Kpg7",
  "language": "en",
  "payment_option": "VALU",
  "phone_number": "00008557694",
  "signature": "54efbd76bd644e9ef237c39137bf5d2304dc1bfdf6f6302065b448f2456a07a7"
}

import requests

# Customer verification request
verify_request = {
    "service_command": "CUSTOMER_VERIFY",
    "merchant_reference": "XYZ9239-yu898",
    "merchant_identifier": "CycHZxVj",
    "access_code": "zx0IPmPy5jp1vAz8Kpg7",
    "language": "en",
    "payment_option": "VALU",
    "phone_number": "00008557694",
    "signature": "54efbd76bd644e9ef237c39137bf5d2304dc1bfdf6f6302065b448f2456a07a7"
}

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

print(response.json())

<?php
// Customer verification request
$verify_request = [
    "service_command" => "CUSTOMER_VERIFY",
    "merchant_reference" => "XYZ9239-yu898",
    "merchant_identifier" => "CycHZxVj",
    "access_code" => "zx0IPmPy5jp1vAz8Kpg7",
    "language" => "en",
    "payment_option" => "VALU",
    "phone_number" => "00008557694",
    "signature" => "54efbd76bd644e9ef237c39137bf5d2304dc1bfdf6f6302065b448f2456a07a7"
];

// Send verification 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($verify_request));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Content-Type: application/json'
]);

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

echo $response;
?>

# Customer verification request using cURL

curl -X POST https://sbpaymentservices.payfort.com/FortAPI/paymentApi \
  -H "Content-Type: application/json" \
  -d '{
    "service_command": "CUSTOMER_VERIFY",
    "merchant_reference": "XYZ9239-yu898",
    "merchant_identifier": "CycHZxVj",
    "access_code": "zx0IPmPy5jp1vAz8Kpg7",
    "language": "en",
    "payment_option": "VALU",
    "phone_number": "00008557694",
    "signature": "54efbd76bd644e9ef237c39137bf5d2304dc1bfdf6f6302065b448f2456a07a7"
  }'

Sample Response

{
  "service_command": "CUSTOMER_VERIFY",
  "access_code": "zx0IPmPy5jp1vAz8Kpg7",
  "merchant_identifier": "CycHZxVj",
  "merchant_reference": "XYZ9239-yu898",
  "language": "en",
  "payment_option": "VALU",
  "phone_number": "00008557694",
  "signature": "7cad05f0212ed933c9a5d5dffa31661acf2c827a",
  "response_message": "Success",
  "response_code": "88000",
  "status": "88"
}

OTP Generate

Generate an OTP for the customer, where the customer should fill in their phone number in the merchant's check-out page. ValU will generate the OTP code and send it to customer as SMS.

Request Parameters

Parameter
service_command   String Max: 20 Required Service command for OTP generation. Value: OTP_GENERATE Example. OTP_GENERATE
access_code   String Max: 20 Required Merchant access code obtained from Amazon Payment Services dashboard under Integration 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. The merchant reference should be the same for all APIs. Alphanumeric characters, hyphens, underscores, and periods allowed. Example. XYZ9239-yu898
language   String Max: 2 Required Response language. Supported values: en (English) or ar (Arabic). Example. en
payment_option   String Max: 10 Required Payment option for ValU transactions. Value: VALU Example. VALU
phone_number   String Max: 19 Required Customer's phone number registered with ValU for OTP delivery. Example. 00008557694
amount   Integer Max: 10 Required Transaction amount in smallest currency unit (e.g., piasters for EGP). Must be positive integer. Example. 10000
currency   String Max: 3 Required Three-letter ISO 4217 currency code for the transaction amount. Value: EGP Example. EGP
signature   String Max: 200 Required SHA-256 hash signature for request authentication and integrity validation. Example. 7cad05f0212ed933c9a5d5dffa31661acf2c827a
wallet_amount   Integer Max: 10 Required Wallet amount or ToU (Transfer of Use) - a gift balance that can be purchased using valU limit and paid in flexible installment plans from 6-60 months. Amount in smallest currency unit. Example. 10000
cashback_wallet_amount   Integer Max: 10 Required Amount stored in cashback wallet. Amount in smallest currency unit. Example. 10000
include_installments   String Max: 3 Optional Defines whether the customer can pay in installments. Values: YES, NO Default: YES Example. YES
total_downpayment   Integer Max: 100 Optional Total down-payment amount payable by the customer. Decimal values are not accepted. Example. 1200
merchant_extra1   String Max: 250 Optional Additional custom field for merchant-specific data. Will be received and sent back as received. Special characters: ;/_-,'@ Example. JohnSmith
merchant_extra2   String Max: 250 Optional Additional custom field for merchant-specific data. Will be received and sent back as received. Special characters: ;/_-,'@ Example. JohnSmith
merchant_extra3   String Max: 250 Optional Additional custom field for merchant-specific data. Will be received and sent back as received. Special characters: ;/_-,'@ Example. JohnSmith

Response Parameters

Parameter
service_command   String Max: 20 Service command from the request. Value: OTP_GENERATE Example. OTP_GENERATE
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
language   String Max: 2 Language used for the response. Example. en
payment_option   String Max: 10 Payment option used. Value: VALU Example. VALU
phone_number   String Max: 19 Customer's phone number from the request. Example. 00008557694
merchant_order_id   String Max: 100 Unique order identifier generated by the system. Use this value for all subsequent APIs. Example. Valu123
amount   Integer Max: 10 Transaction amount from the request. Example. 10000
currency   String Max: 3 Currency code from the request. Example. EGP
total_downpayment   Integer Max: 100 Total down-payment amount from the request. Example. 10000
installment_detail   Array Array of installment plan details if include_installments is set to YES. Contains fee amount, installment amount, installment per month and total installment information. Example. Array of objects
signature   String Max: 200 Response signature for verification. Example. 7cad05f0212ed933c9a5d5dffa31661acf2c827a
merchant_extra1   String Max: 250 Custom data from the request. Example. JohnSmith
merchant_extra2   String Max: 250 Custom data from the request. Example. JohnSmith
merchant_extra3   String Max: 250 Custom data from the request. Example. JohnSmith
response_message   String Max: 150 Human-readable response description in requested language. Example. Success
response_code   String Max: 5 Numeric response code indicating OTP generation result. Example. 88000
status   String Max: 2 Two-digit status code indicating OTP generation state. Example. 88
wallet_amount   Integer Max: 10 Wallet amount from the request. Example. 10000
cashback_wallet_amount   Integer Max: 10 Cashback wallet amount from the request. Example. 10000

OTP Generate Sample Request

{
  "merchant_reference": "TEST-009967",
  "merchant_identifier": "CycHZxVj",
  "access_code": "zx0IPmPy5jp1vAz8Kpg7",
  "signature": "27c1303138f8718e56f311d1b3d823b5a644e6bcd4fac43d5454955b13b5b337",
  "service_command": "OTP_GENERATE",
  "language": "en",
  "payment_option": "VALU",
  "phone_number": "01220422223",
  "amount": 100000,
  "currency": "EGP",
  "include_installments": "YES",
  "wallet_amount": 500000,
  "cashback_wallet_amount": 300000
}

import requests

# OTP generation request
otp_request = {
    "merchant_reference": "TEST-009967",
    "merchant_identifier": "CycHZxVj",
    "access_code": "zx0IPmPy5jp1vAz8Kpg7",
    "signature": "27c1303138f8718e56f311d1b3d823b5a644e6bcd4fac43d5454955b13b5b337",
    "service_command": "OTP_GENERATE",
    "language": "en",
    "payment_option": "VALU",
    "phone_number": "01220422223",
    "amount": 100000,
    "currency": "EGP",
    "include_installments": "YES",
    "wallet_amount": 500000,
    "cashback_wallet_amount": 300000
}

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

print(response.json())

<?php
// OTP generation request
$otp_request = [
    "merchant_reference" => "TEST-009967",
    "merchant_identifier" => "CycHZxVj",
    "access_code" => "zx0IPmPy5jp1vAz8Kpg7",
    "signature" => "27c1303138f8718e56f311d1b3d823b5a644e6bcd4fac43d5454955b13b5b337",
    "service_command" => "OTP_GENERATE",
    "language" => "en",
    "payment_option" => "VALU",
    "phone_number" => "01220422223",
    "amount" => 100000,
    "currency" => "EGP",
    "include_installments" => "YES",
    "wallet_amount" => 500000,
    "cashback_wallet_amount" => 300000
];

// Send OTP generation 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($otp_request));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Content-Type: application/json'
]);

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

echo $response;
?>

# OTP generation request using cURL

curl -X POST https://sbpaymentservices.payfort.com/FortAPI/paymentApi \
  -H "Content-Type: application/json" \
  -d '{
    "merchant_reference": "TEST-009967",
    "merchant_identifier": "CycHZxVj",
    "access_code": "zx0IPmPy5jp1vAz8Kpg7",
    "signature": "27c1303138f8718e56f311d1b3d823b5a644e6bcd4fac43d5454955b13b5b337",
    "service_command": "OTP_GENERATE",
    "language": "en",
    "payment_option": "VALU",
    "phone_number": "01220422223",
    "amount": 100000,
    "currency": "EGP",
    "include_installments": "YES",
    "wallet_amount": 500000,
    "cashback_wallet_amount": 300000
  }'

Sample Response

{
  "service_command": "OTP_GENERATE",
  "access_code": "zx0IPmPy5jp1vAz8Kpg7",
  "merchant_identifier": "CycHZxVj",
  "merchant_reference": "TEST-009967",
  "language": "en",
  "payment_option": "VALU",
  "phone_number": "01220422223",
  "merchant_order_id": "Valu123",
  "amount": 100000,
  "currency": "EGP",
  "total_downpayment": 10000,
  "installment_detail": [
    {
      "fee_amount": 500,
      "installment_amount": 17500,
      "installment_per_month": 6,
      "total_installment": 105000
    }
  ],
  "signature": "7cad05f0212ed933c9a5d5dffa31661acf2c827a",
  "response_message": "Success",
  "response_code": "88000",
  "status": "88",
  "wallet_amount": 500000,
  "cashback_wallet_amount": 300000
}

Get Installment Plans

Using this API, you can fetch the installment plans the customer has selected.

Request Parameters

Parameter
service_command   String Max: 20 Required Service command for retrieving installment plans. Value: GET_INSTALLMENTS_PLANS Example. GET_INSTALLMENTS_PLANS
access_code   String Max: 20 Required Merchant access code obtained from Amazon Payment Services dashboard under Integration 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. The merchant reference should be the same for all APIs. Alphanumeric characters, hyphens, underscores, and periods allowed. Example. XYZ9239-yu898
language   String Max: 2 Required Response language. Supported values: en (English) or ar (Arabic). Example. en
payment_option   String Max: 10 Required Payment option for ValU transactions. Value: VALU Example. VALU
phone_number   String Max: 19 Required Customer's phone number registered with ValU. Example. 00008557694
amount   Integer Max: 10 Required Transaction amount in smallest currency unit (e.g., piasters for EGP). Must be positive integer. Example. 10000
currency   String Max: 3 Required Three-letter ISO 4217 currency code for the transaction amount. Value: EGP Example. EGP
signature   String Max: 200 Required SHA-256 hash signature for request authentication and integrity validation. Example. 7cad05f0212ed933c9a5d5dffa31661acf2c827a
wallet_amount   Integer Max: 10 Required Wallet amount or ToU (Transfer of Use) - a gift balance that can be purchased using valU limit and paid in flexible installment plans from 6-60 months. Amount in smallest currency unit. Example. 10000
cashback_wallet_amount   Integer Max: 10 Required Amount stored in cashback wallet. Amount in smallest currency unit. Example. 10000
total_downpayment   Integer Max: 100 Optional Total down-payment amount payable by the customer. Decimal values are not accepted. Example. 1200

Response Parameters

Parameter
service_command   String Max: 20 Service command from the request. Value: GET_INSTALLMENTS_PLANS Example. GET_INSTALLMENTS_PLANS
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
language   String Max: 2 Language used for the response. Example. en
payment_option   String Max: 10 Payment option used. Value: VALU Example. VALU
total_downpayment   Integer Max: 100 Total down-payment amount from the request. Example. 1200
phone_number   String Max: 19 Customer's phone number from the request. Example. 00008557694
amount   Integer Max: 10 Transaction amount from the request. Example. 10000
currency   String Max: 3 Currency code from the request. Example. EGP
signature   String Max: 200 Response signature for verification. Example. 7cad05f0212ed933c9a5d5dffa31661acf2c827a
installment_detail   Array Array containing detailed information about all available installment plans, including number of installments, fees due every month, and total amounts. Example. Array of objects
wallet_amount   Integer Max: 10 Wallet amount from the request. Example. 10000
cashback_wallet_amount   Integer Max: 10 Cashback wallet amount from the request. Example. 10000

Get Installment Plans Sample Request

{
  "service_command": "GET_INSTALLMENTS_PLANS",
  "merchant_reference": "XYZ9239-yu898",
  "merchant_identifier": "CycHZxVj",
  "access_code": "zx0IPmPy5jp1vAz8Kpg7",
  "signature": "b574e362cc08d7504d8277e71400132f06064ee1537cd570717569b583dec0b5",
  "phone_number": "01220422223",
  "payment_option": "VALU",
  "language": "en",
  "amount": 100000,
  "currency": "EGP",
  "total_downpayment": 1200,
  "wallet_amount": 500000,
  "cashback_wallet_amount": 300000
}

import requests

# Get installment plans request
plans_request = {
    "service_command": "GET_INSTALLMENTS_PLANS",
    "merchant_reference": "XYZ9239-yu898",
    "merchant_identifier": "CycHZxVj",
    "access_code": "zx0IPmPy5jp1vAz8Kpg7",
    "signature": "b574e362cc08d7504d8277e71400132f06064ee1537cd570717569b583dec0b5",
    "phone_number": "01220422223",
    "payment_option": "VALU",
    "language": "en",
    "amount": 100000,
    "currency": "EGP",
    "total_downpayment": 1200,
    "wallet_amount": 500000,
    "cashback_wallet_amount": 300000
}

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

print(response.json())

<?php
// Get installment plans request
$plans_request = [
    "service_command" => "GET_INSTALLMENTS_PLANS",
    "merchant_reference" => "XYZ9239-yu898",
    "merchant_identifier" => "CycHZxVj",
    "access_code" => "zx0IPmPy5jp1vAz8Kpg7",
    "signature" => "b574e362cc08d7504d8277e71400132f06064ee1537cd570717569b583dec0b5",
    "phone_number" => "01220422223",
    "payment_option" => "VALU",
    "language" => "en",
    "amount" => 100000,
    "currency" => "EGP",
    "total_downpayment" => 1200,
    "wallet_amount" => 500000,
    "cashback_wallet_amount" => 300000
];

// Send installment plans 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($plans_request));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Content-Type: application/json'
]);

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

echo $response;
?>

# Get installment plans request using cURL

curl -X POST https://sbpaymentservices.payfort.com/FortAPI/paymentApi \
  -H "Content-Type: application/json" \
  -d '{
    "service_command": "GET_INSTALLMENTS_PLANS",
    "merchant_reference": "XYZ9239-yu898",
    "merchant_identifier": "CycHZxVj",
    "access_code": "zx0IPmPy5jp1vAz8Kpg7",
    "signature": "b574e362cc08d7504d8277e71400132f06064ee1537cd570717569b583dec0b5",
    "phone_number": "01220422223",
    "payment_option": "VALU",
    "language": "en",
    "amount": 100000,
    "currency": "EGP",
    "total_downpayment": 1200,
    "wallet_amount": 500000,
    "cashback_wallet_amount": 300000
  }'

Sample Response

{
  "service_command": "GET_INSTALLMENTS_PLANS",
  "access_code": "zx0IPmPy5jp1vAz8Kpg7",
  "merchant_identifier": "CycHZxVj",
  "merchant_reference": "XYZ9239-yu898",
  "language": "en",
  "payment_option": "VALU",
  "total_downpayment": 1200,
  "phone_number": "01220422223",
  "amount": 100000,
  "currency": "EGP",
  "signature": "7cad05f0212ed933c9a5d5dffa31661acf2c827a",
  "installment_detail": [
    {
      "tenure": 6,
      "fee_amount": 2500,
      "installment_amount": 17083,
      "total_installment": 102500
    },
    {
      "tenure": 12,
      "fee_amount": 5000,
      "installment_amount": 8750,
      "total_installment": 105000
    }
  ],
  "wallet_amount": 500000,
  "cashback_wallet_amount": 300000
}

Purchase

This request allows the Customer to Purchase his selected items through the selected consumer finance.

Request Parameters

Mandatory Parameters

Parameter
command   String Max: 20 Required Transaction type to be executed for ValU purchase. Value: PURCHASE Example. PURCHASE
access_code   String Max: 20 Required Merchant access code obtained from Amazon Payment Services dashboard under Integration 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. The merchant reference should be the same for all APIs. Alphanumeric characters, hyphens, underscores, and periods allowed. Example. XYZ9239-yu898
payment_option   String Max: 10 Required Payment option for ValU transactions. Value: VALU Example. VALU
phone_number   String Max: 19 Required Customer's phone number registered with ValU. Example. 00008557694
amount   Integer Max: 10 Required Transaction amount in smallest currency unit (e.g., piasters for EGP). Must be positive integer. Example. 10000
currency   String Max: 3 Required Three-letter ISO 4217 currency code for the transaction amount. Value: EGP Example. EGP
language   String Max: 2 Required Response language. Supported values: en (English) or ar (Arabic). Example. en
customer_email   String Max: 254 Required Valid customer email address for payment notifications and receipt delivery. Special characters: _-.@+ Example. customer@domain.com
otp   String Max: 10 Required One-time password sent to customer's mobile phone via SMS from ValU. Example. 123456
tenure   String Max: 100 Required Selected tenure for the installment payments in months. Example. 6
signature   String Max: 200 Required SHA-256 hash signature for request authentication and integrity validation. Example. 7cad05f0212ed933c9a5d5dffa31661acf2c827a
purchase_description   String Max: 100 Required Human-readable description of the purchase or service being paid for. Example. Test
total_down_payment   String Max: 100 Required Total down-payment amount for the transaction. Decimal values are not accepted. Example. 0
wallet_amount   Integer Max: 10 Required Wallet amount or ToU (Transfer of Use) - a gift balance that can be purchased using valU limit and paid in flexible installment plans from 6-60 months. Amount in smallest currency unit. Example. 10000
cashback_wallet_amount   Integer Max: 10 Required Amount stored in cashback wallet. Amount in smallest currency unit. Example. 10000

Response Parameters

Parameter
command   String Max: 20 Transaction type executed. Value: PURCHASE Example. PURCHASE
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
payment_option   String Max: 10 Payment option used. Value: VALU Example. VALU
phone_number   String Max: 19 Customer's phone number from the request. Example. 00008557694
amount   Integer Max: 10 Transaction amount processed. Example. 10000
currency   String Max: 3 Currency code used for the transaction. Example. EGP
language   String Max: 2 Language used for the response. Example. en
customer_email   String Max: 254 Customer email address used. Example. customer@domain.com
signature   String Max: 200 Response signature for verification. Example. 7cad05f0212ed933c9a5d5dffa31661acf2c827a
purchase_description   String Max: 100 Purchase description from the request. Example. Test
customer_ip   String Max: 45 Customer's IP address captured during the transaction. Supports IPv4 and IPv6 formats. Example. 192.178.1.10
eci   String Max: 16 E-commerce indicator for the transaction. Value: ECOMMERCE Example. ECOMMERCE
fort_id   Integer Max: 20 Unique transaction reference generated by Amazon Payment Services. Example. 149295435400084008
response_message   String Max: 150 Human-readable response description in requested language. Example. Success
response_code   String Max: 5 Numeric response code indicating purchase result. Example. 14000
status   String Max: 2 Two-digit status code indicating purchase state. Example. 14
wallet_amount   Integer Max: 10 Wallet amount from the request. Example. 10000
cashback_wallet_amount   Integer Max: 10 Cashback wallet amount from the request. Example. 10000
loan_number   String Max: 100 Unique loan number generated by ValU for each successful purchase transaction. Example. VL123456789
valu_transaction_id   String Max: 100 Unique identifier for the transaction generated by ValU system. Example. VTX987654321

Purchase Sample Request

{
  "merchant_reference": "XYZ9239-yu898",
  "merchant_identifier": "CycHZxVj",
  "access_code": "zx0IPmPy5jp1vAz8Kpg7",
  "signature": "b574e362cc08d7504d8277e71400132f06064ee1537cd570717569b583dec0b5",
  "command": "PURCHASE",
  "language": "en",
  "payment_option": "VALU",
  "phone_number": "00008557694",
  "amount": 10000,
  "currency": "EGP",
  "customer_email": "customer@domain.com",
  "otp": "123456",
  "tenure": "6",
  "total_down_payment": "1200",
  "purchase_description": "Test",
  "wallet_amount": 500000,
  "cashback_wallet_amount": 300000
}

import requests

# Purchase request
purchase_request = {
    "merchant_reference": "XYZ9239-yu898",
    "merchant_identifier": "CycHZxVj",
    "access_code": "zx0IPmPy5jp1vAz8Kpg7",
    "signature": "b574e362cc08d7504d8277e71400132f06064ee1537cd570717569b583dec0b5",
    "command": "PURCHASE",
    "language": "en",
    "payment_option": "VALU",
    "phone_number": "00008557694",
    "amount": 10000,
    "currency": "EGP",
    "customer_email": "customer@domain.com",
    "otp": "123456",
    "tenure": "6",
    "total_down_payment": "1200",
    "purchase_description": "Test",
    "wallet_amount": 500000,
    "cashback_wallet_amount": 300000
}

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

print(response.json())

<?php
// Purchase request
$purchase_request = [
    "merchant_reference" => "XYZ9239-yu898",
    "merchant_identifier" => "CycHZxVj",
    "access_code" => "zx0IPmPy5jp1vAz8Kpg7",
    "signature" => "b574e362cc08d7504d8277e71400132f06064ee1537cd570717569b583dec0b5",
    "command" => "PURCHASE",
    "language" => "en",
    "payment_option" => "VALU",
    "phone_number" => "00008557694",
    "amount" => 10000,
    "currency" => "EGP",
    "customer_email" => "customer@domain.com",
    "otp" => "123456",
    "tenure" => "6",
    "total_down_payment" => "1200",
    "purchase_description" => "Test",
    "wallet_amount" => 500000,
    "cashback_wallet_amount" => 300000
];

// Send purchase 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($purchase_request));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Content-Type: application/json'
]);

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

echo $response;
?>

# Purchase request using cURL

curl -X POST https://sbpaymentservices.payfort.com/FortAPI/paymentApi \
  -H "Content-Type: application/json" \
  -d '{
    "merchant_reference": "XYZ9239-yu898",
    "merchant_identifier": "CycHZxVj",
    "access_code": "zx0IPmPy5jp1vAz8Kpg7",
    "signature": "b574e362cc08d7504d8277e71400132f06064ee1537cd570717569b583dec0b5",
    "command": "PURCHASE",
    "language": "en",
    "payment_option": "VALU",
    "phone_number": "00008557694",
    "amount": 10000,
    "currency": "EGP",
    "customer_email": "customer@domain.com",
    "otp": "123456",
    "tenure": "6",
    "total_down_payment": "1200",
    "purchase_description": "Test",
    "wallet_amount": 500000,
    "cashback_wallet_amount": 300000
  }'

Sample Response

{
  "command": "PURCHASE",
  "access_code": "zx0IPmPy5jp1vAz8Kpg7",
  "merchant_identifier": "CycHZxVj",
  "merchant_reference": "XYZ9239-yu898",
  "payment_option": "VALU",
  "phone_number": "00008557694",
  "amount": 10000,
  "currency": "EGP",
  "language": "en",
  "customer_email": "customer@domain.com",
  "signature": "7cad05f0212ed933c9a5d5dffa31661acf2c827a",
  "purchase_description": "Test",
  "customer_ip": "192.178.1.10",
  "eci": "ECOMMERCE",
  "fort_id": "149295435400084008",
  "response_message": "Success",
  "response_code": "14000",
  "status": "14",
  "wallet_amount": 500000,
  "cashback_wallet_amount": 300000,
  "loan_number": "VL123456789",
  "valu_transaction_id": "VTX987654321"
}

Refund Operations

The refund API follows the same standards as other payment options. ValU supports both full and partial refund operations.

The refund API of ValU supports both full refund and partial refund operations. Please use the standard Refund Operation documentation for implementation details.

Response Codes

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

Important Notes

Prior to sending the transaction value, multiply the value by the currency decimal code corresponding to the ISO code 3.

Example: If the amount was 100 EGP, multiply the value with 100 (2 decimal points). The request amount will be 10000.

• Wallet Amount (ToU): A gift balance that can be purchased using your valU limit and paid in flexible installment plans from 6-60 months.
• Cashback Wallet Amount: Amount stored in the cashback wallet for the customer.
• Both amounts are mandatory parameters and must follow the currency decimal point rules.

Your customer must be registered with ValU to access installment benefits. Use the Customer Verify API to check registration status before proceeding with other operations.

Testing The Integration

Sandbox Testing

Use the sandbox environment for development and testing:

• Sandbox URL: https://sbpaymentservices.payfort.com/FortAPI/paymentApi
• Test Phone Numbers: Contact your integration team for ValU test phone numbers
• Test OTP Codes: Use sandbox-specific OTP codes provided by your integration team

Go-Live Process

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