Paytabs provides you with a collection of API endpoints which used to process all payments, regardless of if they are through either your own payment pages, the managed payment pages, or if you are using the hosted payment pages. 


This article is dedicated to the clarification of the alternative currency (alt_currency) parameter. "alt_currencywithin" is one of the optional parameters that you use within your request, which Indicates an alternative currency that you want to display your amount with it in your payment page. This will allow you to display the approximate amount of the payment cart amount in this alternative currency for this transaction. However, you can set this value for all of your payments by following the steps mentioned here.

Note that this will ONLY affect the displayed currency, it has no affects on the payout settlments currency



In this article we will be going through the following:

Specifications 


The Parameter Tag/Namealt_currency
JSON Example
{
"alt_currency": "AED",
}
Data TypeSTRING  
Required
x
Validation Rules
  • Valid and Supported currency code
  • Accepts both upper- and lower-case characters
Max Length3 Characters



Usage Workflow


Along with the required parameters mentioned in our Step 3 - PT2 API Endpoints | Initiating the payment solution article, you can set the "alt_currency" as shown below:


Note that this parameter will NOT work if you have enabled the Donation mode or if any of the discount parameters was passed.



Sample Request Payload

 

{
    "profile_id": XXXXX,
    "tran_type": "sale",
    "tran_class": "ecom",
    "cart_id": "cart_11111",
    "cart_currency": "EGP",

    "alt_currency": "USD",

    "cart_amount": 12.3,
    "cart_description": "Description of the items/services",
    "paypage_lang": "en"
}


Sample Response Payload

 

   "tran_ref": "TSTxxxxxxxx",
    "tran_type": "Sale",
    "cart_id": "cart_11111",
    "cart_description": "Description of the items/services",
    "cart_currency": "EGP",
    "cart_amount": "12.30",
    "tran_currency": "",
    "tran_total": "0",
    "return": "none",
    "redirect_url": "https://secure-egypt.paytabs.com/payment/wr/5E3001E582E459830CC526E72549FAAD62E7BC358F7091F572406A18",
    "serviceId": 2,
    "profileId": 81784,
    "merchantId": 31237,
    "trace": "PMNT0404.64C3C4FB.00022D8A"


The Expected Behavior

By following the above you will see below that the resulting payment page will include an approximate value of the cart amount in the passed alternative currency.